Tutorial 7 - Web Snippets

 A full reference for Web Snippets is available in the Web Snippet Documentation.

Web Snippets

Detailed documentation for Web Snippet creation, config settings, and examples is available in the Web Snippet Reference.

Web snippets are blocks of HTML that can be added to the editor.

In the Home Page template we are working on, there are several items we'll convert into web snippets and components.

We'll convert the banner and tiles into components, and we'll convert the Product Features listing and the Quote Block into web snippets.

The difference between components and web snippets, is that components are parameter-based controls, while web snippets are just static HTML.

Web snippets are better for custom layouts, while components are better for items like banners or tiles that you may want to turn into configurable controls.

First, let's make the full-width template editable.  We'll use the techniques from the Page Template tutorial.

We'll add the page config

<cms-page-config>
{
  "title": "Full-width"
}
</cms-page-config>

Since we don't have a title on this page, let's make the title not required:

"options": { "title_element_required": false }

Finally, let's add the "cms-content-editor" tag to the content element

Now we're done with the page template and we can get started on the web snippets

We can either define the web snippets in-line in the page, or in a separate file.

We'll start by defining them in-page, and then we'll move them into a separate file when we're done.

To define the web snippet in-page, we'll just add the "cms-websnippet-template" script tags around the web snippet

<script type="text/cms-websnippet-template">
</script>

We'll do this for the product features block, and the quote block.

Let's also add a cms-websnippet-config section to each web snippet, to give each web snippet a name and description.

<cms-websnippet-config>
  {
    "title": "Product Features",
    "description": "List of product features"
  }
</cms-websnippet-config>

<cms-websnippet-config>
  {
    "title": "Quote",
    "description": "Quote callout"
  }
</cms-websnippet-config>

Now, when we go to edit the page, those two items will no longer show in the body, but they can now be inserted from the Web Snippets menu.

Finally, let's move them into a separate file so that they can be used in any template.

The file must be in the "templates/websnippets" folder.

We'll call the first file product_features.html, and the other file quote.html.

We'll remove the script wrapper when putting the web snippet in its own file.

And now let's use them in the actual page.

You can see that when web snippets are added to the page, they turn into HTML.

This is the difference between the web snippets and components - when you add a component, it does not turn into HTML, but continues to be an editable component.

For components, when you change the source file, any pages that use that component will be updated.

For web snippets, when you change the source file, any places you inserted that web snippet will not be updated.

On the other hand, web snippets let you move the items around and add text directly in the editor, so they provide a little more flexibility for the user.