Custom Elements Tutorial Guide
Guidelines for Using Custom Elements
- Avoid using ids as custom elements can be reused multiple times on the same page.
- If you add CSS using the CSS tab, the styles will be included in a css link tag on the live page. The styles from multiple custom elements are concatenated together and served in a single minified file. Make any styles specific to the template using classes if possible.
The Custom Element Editor
When you stop typing into the liquid editor, Shogun will parse the variables and configuration options (explained below) will appear.
How to Configure Custom Elements
Every liquid variable in your template should appear in the right sidebar allowing additional configuration. There are 3 things to configure for each variable, and they control how users will interact with your templates inside of the editor.
Should this variable be controlled by user input, or from a Data Collection?
When controlled by User Input, users will get to fill in values for the variables when they drag the template into the editor. For Data Collection, users will either get to pick a single Entry from your chosen Data Collection, or in the case of a multi variable (more below) all of the collection entries will be used in place of the variable. For more on Data Collections, see the Data Collections Tutorial.
What type of value should the user provide for each variable?
Plain Text: plain text with no formatting controls
Dropzone: a variable that allows nesting other elements by dragging and dropping inside of this element in the editor
Rich Text: text with formatting controls (output as html)
Image (HTML): a HTML image (the <img> tag will be generated for you)
Image (URL): just the URL from an uploaded image
Markdown: a variable that receives markdown and outputs html
HTML: a variable that receives and outputs html
Integer: a number only variable
Boolean: a checkbox (true/false)
How should the user enter a value for this variable?
Inline: the variable can be edited inline in the editor, e.g., with a contenteditable region for text
Multi: the user should provide multiple values for this variable in the sidebar
Sidebar: the user should provide a single value for this variable in the sidebar
You should avoid using Inline variables for anything that the user cannot see on the page. For example, a variable that sets some attributes on an HTML element should never be Inline:
Custom Element Examples
The first 3 examples below illustrate the description of configuration above.
Custom Element Versioning
Each time you save a template in Shogun, a new version is created. New versions of pages that are using the template are also created, but those aren't published automatically.