Skip to content

Block syntax

There are five different syntactical expressions for a block in your page. Each syntax is complete, there is nothing that can be expressed in one syntax that cannot be expressed in another. Choosing one syntax in favour of another is a matter of taste and readability.

Note that the use of custom blocks, may make it easier to use the recommended approach (option 1) as the complexity is hidden from the expression in the page.

This is the preferred option for describing a block if the amount of parameters and their values are reasonably small.

<span data-entryscape="text" 
      data-entryscape-entry="1"
      data-entryscape-context="1"
      data-entryscape-entrystore="http://example.com/store"></span>

Option 2: Single attribute as JSON - Use for plugins / integrations

This option is more compact, but it can be complicated to get all the quotes right. The value has to be correct json.

<span data-entryscape='{"block": "text", "entry": "1", "context": "1",
                        "entrystore": "http://example.com/store"}'></span>

Option 3: Block JSON script - Use for many parameters

This option is a good approach when the block requires many or large values of the parameters.

<script type="text/x-entryscape-json">
  {
     "block": "text",
     "entry": "1",
     "context": "1",
     "entrystore": "http://example.com/store"
  }
</script>

Option 4: Block handlebar script - use for large templates

In situations where blocks takes templates as parameters the template may become large and awkward to maintain as data attributes or as part of a JSON expressions inside of a single parameter (especially when trying to correctly escape quotes). The following example shows how to use the script type text/x-entryscape-handlebar for the block template (which is the easiest block that uses a single handlebar template).

<script type="text/x-entryscape-handlebar" data-entryscape="template">
  <h4>{{text}}</h4>
  <div class="description">{{text content="${dcterms:description}"}}</div>
</script>

Note that the template in turn uses two instances of the text block.

Option 5: Shortcodes in Wordpress

This option is currently only available in Wordpress if the EntryScape plugin has been installed.
The EntryScape wordpress plugin makes it possible to provide blocks using the shortcode syntax which is translated to the expressions described in option 2. For example, the following shortcode:

[entryscape block="text" entry="1" context="1"
            entrystore="http://example.com/store"]

For blocks that requires expressing handlebar templates we also need a closing shortcode, below is the example from option 4 expressed as a shortcode:

[entryscape block="template"]
  <h4>{{text}}</h4>
  <div class="description">{{text content="${dcterms:description}"}}</div>
[/entryscape]

The plugin can be downloaded here.

Note 1: Wordpress has a function called auto-p which translates all newlines to new paragraphs. Since the shortcodes above have newlines in them they would be destroyed by auto-p. For smaller shortcode expressions this can be solved by simply writing them in one line. However this does not scale for larger expressions, especially not with big handlebar templates. In versions of Wordpress before 5.0 the problem could be alleviated by a plugin, like toggle wpautop that lets you disable auto-p per page.

Note 2: In Wordpress 5.0 and forward the gutenberg editor is used which is based on the princple of adding "blocks" (yes the name is the same). There is a special shortcode block, however, it seems that this somehow still inserts p and br tags on a whim, especially in more complex templates with headings and divs. The solution here is to either externalize the complexity by writing custom blocks which allows you to use the shortcode block as it is intended or stick with classical mode editor. Observe that it is not enough with the classical editor, you have to be in source mode (HTML) as otherwise the frontend WYSIWYG editor makes things really weird.

Note 3: The EntryScape Blocks Wordpress plugin is a convenience, not a neccessity. With Wordpress 5.0 there is the block raw html that can be used to insert all required html tags. It also seems that the preferred solution is to develop blocks or inline blocks for the Gutenberg editor rather than rely on shortcodes. Hence, it is unclear what the status of the entryscape plugin will be in the future. Clearly it will depend on the capacity of the shortcode block which currently is effectively broken for the needs of EntryScape Blocks.