Writing JavaScript Block Template


JSr Blocks are written as HTML templates using Mustache syntax to access the block's settings. For more information on Mustache syntax, click here. Let's take a look at a couple of examples to see how this works. In both cases, we will render an unordered list of text items. In our first example, the list will come from a data source. In our second example, we will let the user choose how many items to display in the list and enter each list item in the block's settings.


In either example, our template will result in HTML that looks like the following:

<!DOCTYPE html>
<html>
  <head>
    <title>Unordered List</title>
  </head>
  <body>
    <h2>List Title</h2>
    <ul>
      <li>First List Item</li>
      <li>Second List Item</li>
      ...
    </ul>
  </body>
</html>

Example 1 - Data Source List

Writing the Descriptor

Before we can start writing the template, let's define the fields that will appear in the block settings. For more information on writing block descriptors, see the Descriptor How-To tab on the Edit page of your Master Block. For our block, we will need a title, a data source and a field in the data source to display in the list. On the Definition tab, in the Raw descriptor field, we enter:

List Title: text
Data Source: feed
List Item: feed_field

Writing the Template

Now let's go to the Advanced tab to write our template. We won't be using javascript in this block, so we'll leave the Code to Obfuscate field blank. For the Iterating data source field, we'll enter the label for our "feed" type field, where the user selects a data source. For our block, we called this field "Data Source":

Now let's start writing the Mustache template. Since we're using an Iterating data source, we'll need to use the Prologue, Body and Epilogue fields. Since the <li> tag is what we will want to repeat for each record in our data source, we'll put everything before the <li> tag in the Prologue, and everything after the </li> tag in the Epilogue, with the <li>...</li> portion in the body. When we want to reference a field from the block's settings, we take the field name and convert it to lower camel case, and surround it with Mustache's double-braces.:

Prologue:

<!DOCTYPE html>
<html>
  <head>
    <title>Data Source List</title>
  </head>
  <body>
    <h2>{{listTitle}}</h2>

    <ul>

Body:

      <li>{{listItem}}</li>

Epilogue:

    </ul>
  </body>
</html>

That's it! Just click Update to save your changes and your block is ready to use. When we generate an app that uses our block, the fields referenced in the double-braces will be replaced by the settings a producer entered for the block.

Example 2 - Form-based List

Writing the Descriptor

Once again, let's define the fields that will appear in the block settings. For more information on writing block descriptors, see the Descriptor How-To tab on the Edit page of your Master Block. For this version of the block, we also need a list title, but instead of the data source field, we'll need a range field for the user to select the number of items in the list, and a text field that will be repeated the selected number of times:

List Title: text
List Items: 0-20
[List Item: text](List Items)

Now when a user selects a value for List Items, that number of List Item fields will dynamically appear in the block settings. In our template, we'll iterate over the List Item fields in the List Items array to build our list.

Writing the Template

Now let's go to the Advanced tab to write our template. We won't be using javascript in this block, so we'll leave the Code to Obfuscate field blank. We also won't be using a data source, so we can leave the Iterating data source field blank as well.


Now let's start writing the Mustache template. Since we're not using a data source, we can write our template in any of the 3 HTML Template fields, or spread our code out among all 3. For simplicity, we will just use the Prologue field in this example:

Prologue:

<!DOCTYPE html>
<html>
  <head>
    <title>Data Source List</title>
  </head>
  <body>
    <h2>{{listTitle}}</h2>
    <ul>
      {{#listItems}}
      <li>{{listItem}}</li>
      {{/listItems}}
    </ul>
  </body>
</html>

Notice how we surround the <li> tag with {{#listItems}}..{{/listItems}}. This tells the template system that the listItems field is an array, and we want to render the <li> tag for each item in the array.

Once you have entered the template, click Update, and you are ready to use your block.
 

A note on descriptor types:

Most descriptor types represent single values, and are accessed in the template as {{fieldName}}. However, some types, including all image-type fields, and "rose", produce compound values. Let's look at how to access these values:

Let's say our descriptor contains the following:

Image: image
Margins: rose

Image fields will have 1 or 2 subfields, depending on whether the image type you are using supports scaling options. All images will have a "source" subfield, and images that support selecting scaling ("fit" or "fill") will have a "crop" subfield. Rose-type fields will have 4 subfields: "top", "left", "right" and "bottom". Here's how we access the subfields:

{{#image}}
<img src="{{source}}">
{{/image}}

{{#margins}}
  <div style="margin: {{top}} {{right}} {{bottom}} {{left}}">
{{/margins}}

Notice that this syntax is similar to the syntax for iterating over the array of a range field in Example 2: we surround the section where we want to access the subfields with a container tag ({{#<field>}}..{{/<field>}}), and between the open and close container tags we simply refer to the name of the subfield we want to use.