Shogun’s template editor lets you create reusable custom elements using HTML/Liquid, CSS and JavaScript. If you haven't already, please read our introduction guide on Custom Elements to get an overview of how they function.
The option to create custom elements is only available on select Shogun plans. Please check the Plans section of your Shogun settings for availability.
Should you be having trouble creating your Custom Elements, note, that Shogun has introduced an in-app AI helper function: Code with AI; only available on the current Advanced plan.
If you are on a legacy plan which offers the ability to build custom elements, you would need to transition to Advanced, in order to see and use Code with AI.
Guidelines for Creating Custom Elements
Avoid using IDs in the element's markup. 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
<link>tag on the live page. The styles from multiple custom elements are concatenated together and served in a single file. Apply any styles specific to the template using classes, if possible. If you prefer, you can add the CSS into the theme's stylesheets instead.JavaScript is included in an async
<script>tag on the live page. Any JS should handle multiple instances of the template - the script will only be rendered once.While its enabled by default, JavaScript can be disabled in Shogun Settings - if you do this it may cause Custom Elements using JavaScript to display incorrectly in the editor.
Liquid in Custom Elements
Liquid is a templating language that makes it possible to create re-usable custom elements in Shogun with dynamic content. You can read more about usage of Liquid here: http://liquidmarkup.org
If your ecommerce platform also uses Liquid, it is important to note that the Liquid used in custom elements operates in a separate context than the theme. Custom Elements use Liquid as a templating language for the element's selected CMS collection. Liquid copied from the theme will not function as-is when pasted into a custom element.
Best Practices for Liquid in Custom Elements
Using the whitespace control syntax of Liquid tags is not recommended in custom elements. If your Liquid tags contain hyphens, such as
{{-,-}},{%-, and-%}, please remove the hyphens to avoid any syntax conflicts.Use
blankwhen comparing to an empty value, such as{% if var == blank %}
Creating and Configuring Liquid Variables
When you stop typing in the Liquid editor, Shogun will parse the variables and configuration options will appear in the sidebar. These config options determine the source of the data, the value type of the content, and type of input that the data will be provided through (if applicable).
How to Configure Custom Elements
Every Liquid variable in your template should appear in the right sidebar allowing additional configuration. There are 3 settings to configure for each variable. They control how users will interact with your templates inside of the Shogun editor.
Data Source
The data source determines whether the variable's content will be provided by the end user or populated by a CMS 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 Collection, users will either get to pick a single Entry from your chosen CMS 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 CMS Collections, see the CMS Collections Tutorial.
Value Type
The value type defines what sort of content the user will be providing for this variable. It also determines what kind of input field they will see in the editor.
Plain Text: plain text with no formatting controls
Dropzone: a variable that allows dragging other elements into the custom element from the editor sidebar
Rich Text: text with formatting controls (output as html)
Image (HTML): an 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/Checkbox: a checkbox representing
trueandfalsevalues
Input Type
The input type type determines how the user will provide the content within the Shogun editor.
Sidebar: the user will be able to provide a single value for this variable in the sidebar of the Shogun editor.
Multi: the user will be able to provide multiple values for this variable in the sidebar of the Shogun editor.
Inline: the variable can be edited inline in the editor, e.g., a content editable region for text in the main page editor.
Note: You should avoid using Inline variables for anything that the user cannot see on the page. For example, a variable that sets attributes on an HTML element should never be Inline because the user will be unable to add content:
<h2 class="{{never_inline}}">{{inline_optional}}</h2>
Example Custom Element
Below is an example of using Liquid to loop through a list of user-provided items. Setting the Input Type to Multi allows the length of the list to be determined by how many items they choose to add in the editor.
Custom Element Versioning
Each time you save a custom element in Shogun, a new version is created. New versions of pages that contain the custom element are also created, but those aren't published automatically. In the Shogun dashboard, an "Outdated" label will appear next to pages that required republishing.
How can I access my CMS Collection?
To learn about working CMS Collections into your Custom Elements, check out our guide on CMS Collections.