Using Skuid with JavaScript: A Primer

The Skuid JavaScript API is powerful, but with that power comes complexity. The best way to overcome that complexity and illustrate some of its concepts and uses is by trying it. So let’s do that!

Create a test page

Note

To protect your data, create this test page in a personal developer org or a sandbox org .

  1. From the Skuid navbar, click Compose > New Page
  2. Enter a Page Name—any name will work.
  3. Click Next Step.
  4. As your Starting point, select Use a page template.
  5. Click Select Page Template.
  6. In the Create New Page dialog, set your Primary Object to any data object with multiple records, e.g. Account. Leave everything else at their default settings.

Note

In the examples that follow, it’s assumed you are using the Account object, with your model also named Account. If you are using a different data object, substitute the name of the object/model you used.

  1. Click Create Page.
  2. In your new page, in the properties pane, click Layout.
  3. Unclick the Show Salesforce Header and Show Salesforce sidebar checkboxes.
    • This ensures compatibility across browser consoles.
  4. Preview your newly created Skuid page.

With this Skuid page, you’ll be able to learn the basics of how to use the Skuid JavaScript API.

To ensure the page is set up correctly:

  1. In your preview, open your browser’s console
  2. Type skuid in the console. The skuid object should be returned in your console.

Some Basics

When you preview your page, you’ll see a basic table, with a list of accounts, attached to the account model. As a user, this is a handy way to see the information, but how can a developer access model data programmatically? How can they update rows of data within a model programmatically? How can they control the UI to display appropriate popup messages to the end user? Whether you’re writing a small snippet or a completely custom component, you’ll need to have a grasp on these basic Skuid actions.

Let’s look at how to do all that using the API.

Accessing model data

Seeing all models on a page

First, let’s see which models are on the page.

  1. Open your browser’s console.
  2. Type skuid.model.map(). Skuid will return an object that has all of your model IDs as its properties, with the model data as values of those properties.

What if—for your use case—you’d like to receive that data as an array? Then type

1
skuid.model.getModelList()

Again you’ll all of your model’s data listed, but this time as an array. You can often access the same data in a variety of ways, so choose the data type most appropriate for your use.

For example, enter the following:

1
2
modelsObject = skuid.model.map();
modelsArray = skuid.model.getModelList();

Now you’ll find that you reach your Account object in two ways:

modelsObject.Account
or
modelsArray[0]

But this isn’t the most efficient—or in the case of the array, the most accurate—way to reach a specific model’s data.

Accessing a single model’s data

If you know the ID of your model—or if your code will eventually be used as a snippet or custom component across pages—you’ll likely be using it to access or update the data of one or more models. To do that, you’ll need to access that model as a JavaScript object.

Type the following:

1
skuid.model.getModel('Account');

This function will return our model data as an skuid.model.Model object, much like the above code, but we’re reaching it in one step. Now let’s use a variable to refer to this function so everything we do moving forward is much more readable.

1
var account = skuid.model.getModel('Account');

Note

When creating variable shortcuts, undefined will often be returned by the console. This is normal, and entering your variable after defining it will return the object you created a shortcut to.

A key point to remember here is that—when using the JavaScript API—you invoke functions and then work with the data returned by those functions.

When you work declaratively, referring to models, pages, and other elements by their IDs is enough to access and modify them because they exist as unique, concrete entities that you can modify. In contrast, when working with data programmatically using the JavaScript API, you must invoke a function that then returns the element—in essence, you must first ask for an element before you can modify it. (Depending on your experience with JavaScript, you may have already run across this concept, particularly with the often-used document.getElementByID() function.)

Because of this difference in how you handle data when working programmatically, it’s best practice to use appropriate variable shortcuts for both clarity and convenience.

After declaring our shortcut variables, typing either the skuid.model.getModel('Account').id or account.id, would return the same data. As listed in the Best Practices section, using the variable shortcut is the preferable option.

Whenever you invoke skuid.model.getModel(), you can be able to browse the model object within your console. But to demonstrate how your new shortcut variable works, try entering some of the following in your browser’s console:

1
2
3
4
account.objectName //Returns the name of the data source object retrieved by the model//;
account.data //Returns all the record rows inside your model as an array of objects.//;
account.dataMap //Returns all the record rows inside your model as an object, with each row as a property.//;
account.conditions //Returns all of the model's conditions as an array of objects. //;

Interacting with your model

Now that we know how to reach our model’s data, let’s look at how we can interact with that data programmatically.

First, create a new row on your table by typing account.createRow() in your console. Simple enough, but how do we input data into our newly created row?

Updating a row

1
2
3
4
account.updateRow(account.getFirstRow(), { Name: 'My First API Row Update!' });
// updateRow accepts two parameters:
// the row to update
// the updates to make (as a JavaScript object)

Let’s break down how the updateRow() method used here tells Skuid to update a row.

  • The first parameter is the row we want to update. We use the getFirstRow() method as the first parameter, which tells Skuid to look for the model’s first row at the top of that model’s data and return it as an object that the updateRow() function can recognize.

  • The second parameter is a JavaScript object with properties that correlate to:

    • The ID of our name field: “Name"
    • The value to update that field to: “My First API Update!'

You could also:

  • Use an explicit object literal for your row ID parameter, e.g. {Id:"0012603000X4aYYAAZ"}.

  • Update more than one field in a row at a time:

    let updates = {
      Name: "A good name",
      BillingCity: "A cool city",
      CustomField__c: "A custom value for a custom field"
    };
    
    account.updateRow(account.getFirstRow(), updates);
    
    // Notice that we created our updates in a separate object,
    // then used that object as the parameter.
    // This leads to more readable, easier to update code.
    
  • Create and update your row in one line:
    1
    account.updateRow(account.createRow(),{Name:'Created in one line'});
    

Since our table is currently in inline edit mode, let’s cancel all of our changes to the model so far by using the cancel() function.

1
account.cancel();

Canceling specific rows and saving

Now, let’s create two rows that are stored within variables so we can have more granular control over what we do and do not cancel. Copy and paste the following in your console:

1
2
3
4
var workingRow = account.createRow() //The newly created row returned by this function will be known as "workingRow" //;
account.updateRow(workingRow,{Name:'Working Row'}) //We are now using our newly created and identified row object as our updateRow parameter // ;
var anotherRow = account.createRow() //A second created row stored in another unique variable //;
account.updateRow(anotherRow,{Name:'Another Row'}) ;

Retrieving data from a row

Now we have consistent identifiers for the rows our JavaScript has created. This can be essential when writing snippets or custom component that manipulate model data. By using these row identifiers, we can update—even using data from one row in the other—and abandon these rows easily.

First, let’s look at how we can retrieve data from a particular row:

1
anotherRow.Name;

Entering this will return the value of the Name field on our anotherRow row in our account model. As you can see, by using the functions you’ve learned thus far, along with variable shortcuts, you can easily drill down into your data as far as you’d like.

Now that we know we can access that data programmatically, let’s use it to update our workingRow’s Name field. Then we can cancel our extra row by using abandonRow().

1
2
account.updateRow(workingRow,{Name:anotherRow.Name}) //Updating the workingRow using data from a different row that is stored in a variable, as opposed to using an explicit string //;
account.abandonRow(anotherRow) //Abandoning a specific row allows us to cancel one row without destroying them all //;

And with that, in our hypothetical use case, we’ve made all the changes we want to in our data object.

Let’s save those changes with a function that may be the simplest thus far

1
account.save();

But wait! Changed your mind? Don’t want that garbage row you just saved in your data? Easy fix: delete it instead.

1
2
3
workingRow //First, enter this to see that the row—even after being saved—is still stored within its variable. The row's ID field was updated when it was saved, but that field is also updated within your object as well. //;
account.deleteRow(workingRow) //This function will mark the row for deletion, but it won't be deleted from your data object until you use save()//;
account.save();

Creating a popup

And with that, you’ve accomplished a few common Skuid activities entirely through JavaScript. Let’s display a celebratory message with the blockUI() function.

skuid.$.blockUI({ message: '<h1>You\\'ve used Skuid exclusively through JavaScript!</h1><h2>You\\'re on your way to becoming a pro Skuid developer</h2><h3>Also notice how you can use HTML within your blockUI message!</h3><br/>How <i>cool</i> is that?' });

Okay, so when you’re finished admiring your work, you can unblock your UI just as easily:

1
skuid.$.unblockUI()

Now, go develop!

Though the Skuid JavaScript API is far too vast to cover its intricacies in this overview, you’ve now seen how you can use some of its functions in a basic sense. You can create powerful snippets or intricate custom components using the above functions; doing so just requires that you build on the knowledge you’ve established here.