Basic Tutorial on Functions

Is there a sample code snippet to pass table records into a function? Do I also need to pass the table or field itself (because I need the field to get cell value, or the table to get the field, right?)

1 Like

How do I call datetime_diff from a scripting block?

Is there a function to raise a float to an arbitrary number?

e.g., 2^1.04 = 2.0566

@ATG

All of the SDK that Airtable makes available is documented in the Scripting block. Mostly all you are using the SDK for is to retrieve records, retrieve information about your base schema, or update/create/delete records.

Outside of that, any logic you want to implement (such as the concept of “datetime_diff”) will be done with vanilla JavaScript, not with Airtable formula-field functions. So, for stuff like that, you’ll want to checkout the JavaScript documentation:
https://developer.mozilla.org/en-US/docs/Web/javascript

Here’s information on working with dates in JavaScript:

Here’s information on Math operators in JavaScript:

3 Likes

I haven’t been able to find any documentation on the scripting block - is there a link?

For example, does an Airtable date field correspond to a JavaScript Date object or does it need to be processed?

What is the right way of selecting the first record?
let date0 = query.records[0].getCellValue(date);
//This seems to return an object but not a Javascript Date?

Can I make sure the records are pre-sorted before they are returned in the Javascript environment (or do I need to set up a view with the records sorted and getRecords from the View)?

Lots of basic questions - the scripting block documentation just has 5 pretty limited examples

thanks

1 Like

getCellValue(date) on a date field returns just a Javascript string it seems:

let date0 = query.records[0].getCellValue(date);
output.text(date0);
output.inspect(date0);
output.text(typeof date0);

OUTPUT:

2005-12-30

“2005-12-30”

string

The documentation for the Scripting Block is located in the Block itself, underneath where you write your code:

The documentation is pretty thin, but that’s because the API is pretty thin also. Airtable is only concerned with providing you access to your tables, views, and records via the API, and access to create, update, or destroy them.

All the rest is just JavaScript – which means the limits of what you can do once you have your records is bound by the JavaScript documentation, not Airtable’s API documentation. That’s why I provided you the JavaScript documentation. That said, JavaScript is not easy per se. I feel your pain, @ATG. The struggle is real.

Since you are working with dates, you might benefit from taking a look at my Example Script for Detecting Scheduling Conflicts:

I use, process, and compare dates by retrieving them from Airtable and turning them into JavaScript Date objects in that Script.

It looks like you are mostly on the right track with stuff, and I promise you that you will learn far more from the difficult “troubleshoot as you go process” you are going through now than you would by reading documentation! Experience is the best teacher.

Another little tip - make use of the output.inspect() function Airtable makes available while you are trying to figure stuff out. If you are unsure what some variable in your code might be holding at any point, throw it into an output.inspect(variable) and run your script to see what it is, what shape it takes, how/if it can be delved into, etc.

1 Like

@Jeremy_Oglesby, great post.

… and excellent insight. And by “thin” I think you mean good (mostly). The SDK Airtable has created is concise, relatively simple to learn, and extremely powerful.

Early on I had trepidation concerning the lack of filter queries and things that are undeniably critical in API integration, but then I realized two things which are key distinctive qualities about Script Blocks -

  1. Gathering records from a table does not actually embody the fields themselves [see output.inspect() of any recordset and you’ll see just how lightweight this request is].

  2. The underlying architecture of Script Blocks appears to lean on the existing Airtable UI [i.e., a block runs in context with the UI and as such, all the data has been previously requested].

Indeed, and this especially the case with “modern” javascript patterns where promises are required.

2 Likes

Thanks, the example is very helpful.

It probably should be documented what types are returned when getCellValue is called on different fields. That belongs in Airtable Scripting Block documentation - it’s not a Javascript not easy issue. If all functionality such as date processing are reliant on Javascript itself then by default it should return a Date object instead of a string, etc.

It is there, @ATG – it’s in the “Cell values & field options” section, which is linked to from the record.getCellValue() documentation:

3 Likes

Can I chime in with my thoughts on the Scripting Block documentation?

I think that the information in the Scripting API documentation is excellent.

  • It contains a wealth of very detailed information.
  • Being able to easily copy code examples is awesome.
  • The examples are generously scattered throughout the documentation.
  • In several places, the documentation has links to outside reference material.
  • Some of the examples pull in actual names from the current base.
  • The formatting is (mostly) beautiful.

However, the documentation does leave several things to be desired.

  • The documentation window is tiny. This discourages people from using it. It is also very hard to see the documentation, a significant portion of code, and actual records all at the same time. When trying to put everything together, it would be nice to be able to comfortable see them all at the same time.

  • At times the documentation oversimplifies things for users who already know JavaScript (such as not differentiating between properties and methods). Yet at other times it overly complicates things for users who don’t know how to read computer documentation (parameter signatures).

  • Navigation within a section of the documentation is poorly supported. If you want to know what is covered in a section, you have to manually scrolling until you get to the info you want.

Then, there are a few minor quirks:

  • The documentation does not cover some items that I think should be covered, because they are unique to Scripting block. (I’ve run into this twice.)

  • The Scripting block does not always follow documented behavior. (I’ve run into this multiple times.)

  • The Scripting block editor sometimes is overly enthusiastic in flagging possible errors.

  • There are undocumented features. (I’ve run into one.)

I second this - some of the information I was looking for was there but took too much scrolling to find.

There should be a short intro laying out the principles (API only for loading updating data, use Javascript for everything else including filters instead of views, whether queries should be global variables or passed as parameters, etc); code snippets for basic things like sorting, filtering; how references/linked fields should be handled; when to calculate in Airtable formulas and when to handle in Scripting block; how to build shares libraries to extend Airtable API, common libraries to link, how to map Airtable data types to Javascript and any common issues, etc. I found the examples not to be that relevant to be honest.

Would be much easier to pick up with a quick primer like this

In 2007 Google released Google Apps Script and it wasn’t until well into the next decade that examples emerged that truly helped users grasp the the subtle differences between Google Apps Script and javascript (lowercase).

Indeed, I agree that we need better examples. but keep in mind that this new feature was created a few months ago and release from beta under great pressure from the community. It’s bound to have significant documentation gaps.

Often, we want these new features in the worst way, but we’re also annoyed when we get them in the worst condition. :slight_smile:

2 Likes

True, except…one is free, and the other isn’t.

Hmmm… does that really matter? They both have free tiers; they both have paid tiers.

1 Like