Using Snippets with Skuid

Snippets are bits of code designed for use cases that are more narrow in scope, and they are not generally reused across pages. For example, you can use JavaScript snippets when you want to create smaller customized interactions—actions and buttons that execute a specified code each time they are activated and need little modification. Skuid allows you to employ JavaScript snippets within your pages in two ways:

  • Storing them within an in-line resource
  • Storing them within a static resource

When using JavaScript snippets, there are several important things to consider. The way you store your JavaScript code within the page makes a big difference in how you must structure that code, and you must be aware of the scope and re-usability of your snippet. Within Skuid, it is best to think of snippets in contrast with custom components.

If you find that your snippet is going to be used regularly across pages, heavily interface with page data, or add a large amount of functionality, the you should consider writing your code as a custom component instead.

How Different Resource Types Store Your Snippet Code

There are three In-Line resource types, and all three add lines of code directly into your Skuid page in different ways.

You could use the basic In-Line option for any JavaScript. However, when you use this option, you must properly register the snippet via the skuid.snippet API. As an alternative, Skuid also offers two “shortcut” options—In-Line (Snippet) and In-Line (Component)—which are dynamically registered with skuid.snippet and skuid.componentType. These two shortcuts encase the entered JavaScript code with common Skuid JavaScript API function calls that allow them to be “seen” by Skuid. While sufficient for creating a quick snippet or component, these shortcuts are not the solution for every scenario.

In-Line

The basic In-Line resource type runs at the page level. It adds the JavaScript code you enter directly into the page. It adds no boilerplate code, so you must register your snippet manually if you wish to use it in your Skuid page.

For example, If you wanted to register a Skuid Snippet to use as a custom Field Renderer, Row Action, Page Title action, Wizard Step Action, etc., you could add the following JavaScript as an in-line resource:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
skuid.snippet.registerSnippet( "sayHelloToSelectedRows", function() {
  //
  // Snippet code goes here
  //
  // If you want to check out the arguments passed in,
  // do a console log on the arguments.
  // Snippets are usually handed helpful arguments
  // depending on the Snippet context

  console.log(arguments);
  // We will use this Snippet as a Mass Action
  // on a table of Contacts.
  // The snippet will display an alert
  // with the names of the selected Contacts

  var params = arguments[0];
  var list = params.list;
  var $ = skuid.$;
  var names = '';
  $.each(list.getSelectedItems(),function(i,item){
    var name = item.row.FirstName + ' ' + item.row.LastName;
    if (email) names += email + '\\n';
  });
  alert('Selected People:\\n\\n' + names);
});

In-Line (Snippet)

This resource type can be integrated with the Action Framework to run when initiated by a button or action, or it can be used at the model level. In-Line (Snippet) can also be used for custom field renderers, queue item renderers, and table views.

These snippets are declaratively named with the Snippet Name property.

The In-Line (Snippet) resource type also wraps the code snippet in registerSnippet code:

1
2
3
skuid.snippet.registerSnippet(/\* SNIPPET NAME INSERTED BY SKUID \*/,function(){
/\* SKUID ADDS YOUR CODE HERE \*/
});

So how does this contrast with the In-Line option above? You declaratively input your snippet’s name and don’t have to use the skuid.snippet.registerSnippet() API. Doing this also means your snippet is selectable from the snippet picker in Skuid versions 9.5.0 and higher.

This is particularly useful with the Run a Skuid JavaScript snippet action type.

So instead using the following code as an In-Line resource:

1
2
3
skuid.snippet.registerSnippet( "consoleLogMessage", function() {
  console.log('This snippet works!');
});

You can simply insert the following code as an In-Line (Snippet) resource and name the snippet in the Snippet Name property:

1
console.log('This snippet works!');

In-Line (Component)

Note

Using the In-Line (Component) resource type does not mean the component can be used across pages in the same way as static resource-based custom components. If you find yourself using this type of in-line resource for your code, strongly consider whether or not your snippet would be better suited as a fully developed custom component.

The In-Line (Component) resource type wraps the code snippet in registerComponentType code and dynamically inserts the function body based on “Component Name” and “Component Body.” While this type of resource is not for snippets in the strictest sense, you can think of it as a “temporary component.”

To register a custom component, run the following code:

skuid.componentType.register( componentTypeName, function() {
  // Component code goes here
  // "elem" is a reference to the DOM element
  // created by this component
  var elem = arguments[0];
  console.log(elem);
  elem.html('<b>Hello World!</b>');
});

Once registered, you can add this component to to your Skuid page by dragging the “Custom” Component from the Components library.

Integrating JavaScript via Static Resources

In-line snippets are not the only way to integrate JavaScript into Skuid. You can also place the code in a Salesforce Static Resource, and load this by selecting Static Resource as the snippet’s resource location. This would be the most efficient approach if you have several snippets or other custom code that can (or should) be loaded together. Combine them into single Static Resource file and load it using the a Static Resource JavaScript resource.

How to Add JavaScript Snippets using In-Line Resources

  1. In the App Composer’s Elements pane, click the { } JavaScript tab.
  2. Click the fa-plus-circle Add button to add a new Snippet.
  3. In the Properties pane, under Resource Location, select one of the following resource types:
  4. In the Name field, name the snippet. Note: see the comment below about snippet naming recommendations.
  5. In the Body field, define the JavaScript code to be executed when the snippet is run. Skuid will then automatically register this JavaScript Resource as a Snippet using the name you selected.
  6. Your snippet will then be registered for use in your Skuid page—either via registerSnippet API call in your code or boilerplate code for in-line snippets and in-line component.

Note

On naming snippets:

You can register Snippets in a number of locations on multiple pages if you’re dabbling with the Page Include component. However, accidentally re-using a previously-assigned snippet name will cause the original snippet to be overwritten. This can result in unexpected behavior and difficulty in tracing “bugs.” To avoid naming conflicts, Skuid recommends using a “namespace” for your Javascript snippets.

The examples used in Snippets Available for Use in Skuid employ names prefixed with the namespace “SkuidSample.” For your own snippets, choose a unique namespace, such as the name of the page the snippet exists in, to avoid overlap across pages.

Using static resources for larger or reused snippets

Defining in-line snippets is great for rapid development, but overuse of this feature can result in some serious code management headaches. Rather than defining everything as an in-line resource, we recommend that you employ static resources as a more scalable solution, one that provides greater overall efficiency and page performance.

To use a static resource within your page:

  • In the Properties pane, under Resource Location, select Static Resource.

In addition to the ease of sharing snippets between multiple Skuid pages, static resources can be edited in Salesforce’s IDE. This opens up many opportunities for teams, including the ability to search the codebase and use third-party code management/quality assurance tools (including versioning software and linting utilities).

Using static resources means developers can also take full advantage of Javascript’s many features (such as closures) and third-party libraries (such as requireJS).

Sample Static Resource which defines Skuid Snippets using Javascript [[]]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
(function(skuid,$){
  var snippet = skuid.snippet,
    ui = skuid.ui;

  // SHARED VARS (closures)

  // Keep in mind that, while these vars are shared for all snippets defined in
  // this static resource, they are still contained within the parent function,
  // and so are not cluttering up your global variables (which also eliminates
  // the risk of two static resources reusing the same variable name)
  var myClosureVar = 0

  // SNIPPETS

  // Define the MyCountingFieldRenderer snippet
  // Remember to namespace your snippets so that you don't accidentally
  // overwrite snippets defined by other resources (or by the Skuid system)
  snippet.registerSnippet("Namespace.MyCountingFieldRenderer", function(field,value){
    myClosureVar += 1; // increment the closure var by 1 everytime
      // the custom field renderer is called
    ui.renderers[field.displaytype][field.mode](field, value);
    sharedFunction( "MyCountingFieldRenderer" );
  });

  // Define the MyAlertingFieldRenderer snippet
  snippet.registerSnippet("Namespace.MyAlertingFieldRenderer", function(field,value){
    alert(myClosureVar); // report the number of times the
      // MyCountingFieldRenderer has been called so far
    ui.renderers[field.displaytype][field.mode](field, value);
    sharedFunction( "MyAlertingFieldRenderer" );
  });

  // Define the AccountCreatedFieldRenderer snippet
  snippet.registerSnippet("Namespace.AccountCreatedFieldRenderer", function(field,value){
    // use a cached value to speed up rendering of the page and to
    // reduce complexity, rather than having to go fetch a value
    // from a model every single time a field is rendered.
    ui.renderers.DATE.read(field, getAccountCreatedDate());
    sharedFunction( "AccountCreatedFieldRenderer" );
  });

  // Define the AliasedFieldRenderer snippet
  // Note that the second parameter of registerSnippet is a function.
  // You can put any function you want there, including other snippets.
  snippet.registerSnippet("Namespace.AliasedFieldRenderer",
    snippet.getSnippet("Namespace.AccountCreatedFieldRenderer"));

  // SHARED FUNCTIONS

  function getAccountCreatedDate(){
    var someModel = skuid.model.getModel('SomeModel'),
      accountRow = someModel.getFirstRow(),
      accountCreatedDate = someModel.getFieldValue( accountRow, "Account__c.CreatedDate" );
    return accountCreatedDate;
  }
}(skuid,skuid.$));

Using external resources for larger or reused resources

You can also use external resources to avoid copying and pasting JavaScript as in-line resources across multiple pages. Whether this is a tiny snippet or a large expansion of code, external resources are a viable way of including them in your Skuid page.

To use an external resources:

  • In the Properties pane, under Resource Location, select External.

One key point to remember: If your external resources consists of code you are not in charge of maintaining, it could change/break without you knowing.