Introduction

If you are looking to provide and more tailored (or 'guided') experience for your content editors/managers, Aurora provides features to allow you to control what content can be managed via the Page Builder and how.

This includes hiding certain features from your users and even creating your own content Widgets & Objects to use.

Read on below to find out more!

What can you do?

Using this feature, you are able to create your very own selection of Widgets & Objects for your users to drag, drop and configure in your content.

This allows you to provide advanced layouts to all content managers, irrespective of their HTML and Editorial ability.

Furthermore, you can even declare what each of your Widgets can be used for, affecting whihc pages they will appear on, e.g. Products & Snippets or only Blogs? It's your choice!

Please see the following example of the customised Page Builder UI provided as an example by the Aurora Demo store.

Creating your first custom Widget/Object

Finding the Page Builder Widgets/Objects

You manage the Page Builder Widgets/Objects using Smarty Templates in your Front-end Template location(s). Simple upload new files to the following location and see the new items appear in all of Aurora's Page Builders instantly:

/templates/<YOUR_TEMPLATE_DIR>/page_builder/template_blocks

In the Aurora Demo Templates, this is found here:

/templates/example.com/page_builder/template_blocks

These examples are the best way to get started, so download the most recent files from the Aurora Demo Example Templates.

Here one example file for you to see and start experimenting with:

{setPageBuilderBlockProperties title="Image Banner" category="Banners" supportedContentTypes="product-categories" iconSvg='<svg fill="#000000" height="50px" width="50px" version="1.1" id="Capa_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 297 297" xml:space="preserve"><g id="SVGRepo_bgCarrier" stroke-width="0"></g><g id="SVGRepo_tracerCarrier" stroke-linecap="round" stroke-linejoin="round"></g><g id="SVGRepo_iconCarrier"> <g> <polygon points="79.801,180.101 106.091,211.171 106.091,180.101 "></polygon> <polygon points="190.909,180.101 190.909,211.171 217.199,180.101 "></polygon> <path d="M202.577,220.604h86.907c2.864,0,5.478-1.754,6.743-4.322c1.265-2.569,0.96-5.76-0.787-8.03l-17.721-22.996l17.539-20.981 c1.867-2.241,2.268-5.214,1.031-7.855c-1.237-2.641-3.89-4.039-6.806-4.039h-40.796v5.348c0,4.912-1.31,9.527-4.014,13.055 C234.754,183.726,202.577,220.604,202.577,220.604z"></path> <path d="M52.329,170.782c-2.987-3.755-4.599-8.576-4.599-13.63v-4.77H7.516c-2.916,0-5.569,1.398-6.806,4.039 c-1.237,2.641-0.835,5.614,1.031,7.855l17.539,20.981L1.56,208.252c-1.746,2.27-2.051,5.461-0.787,8.03 c1.265,2.569,3.88,4.322,6.743,4.322h86.906C94.423,220.604,62.481,183.542,52.329,170.782z"></path> <path d="M64.64,162.185c1.403,1.678,3.682,2.916,5.895,2.916h156.241c1.79,0,3.922-1.039,5.12-2.368 c1.148-1.275,1.792-3.403,1.792-5.003V84.346c0-4.151-3.654-7.95-7.805-7.95H70.535c-4.151,0-7.805,3.22-7.805,7.371v73.384 C62.73,158.918,63.52,160.845,64.64,162.185z"></path> </g> </g></svg>'}
{addPageBuilderBlockParameter label="Image (URL)" variableName="bannerImageUrl"}
{addPageBuilderBlockParameter label="Link (URL)" variableName="bannerLinkUrl" type="text"}
{addPageBuilderBlockParameter label="Banner Width" variableName="bannerWidth" type="select" options="'Width: Full':100,'Width: Half':50,'Width: Quarter':25"}

<div class="page-builder-image-banner">
  <a href="{$bannerLinkUrl}"><img src="{$bannerImageUrl}" width="{$bannerWidth}%;" /></a>
</div>

📘
This example creates a very simple image banner for use in product category content only, that can be clicked to load another page on your store.

The next example demonstrates how to use 'optional' parameters and even perform logical template decisions on the parameter's values.

{setPageBuilderBlockProperties title="Paramiter Logic Example" category="Examples" iconSvg='<svg fill="#000000" height="50px" width="50px" version="1.1" id="Capa_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 297 297" xml:space="preserve"><g id="SVGRepo_bgCarrier" stroke-width="0"></g><g id="SVGRepo_tracerCarrier" stroke-linecap="round" stroke-linejoin="round"></g><g id="SVGRepo_iconCarrier"> <g> <polygon points="79.801,180.101 106.091,211.171 106.091,180.101 "></polygon> <polygon points="190.909,180.101 190.909,211.171 217.199,180.101 "></polygon> <path d="M202.577,220.604h86.907c2.864,0,5.478-1.754,6.743-4.322c1.265-2.569,0.96-5.76-0.787-8.03l-17.721-22.996l17.539-20.981 c1.867-2.241,2.268-5.214,1.031-7.855c-1.237-2.641-3.89-4.039-6.806-4.039h-40.796v5.348c0,4.912-1.31,9.527-4.014,13.055 C234.754,183.726,202.577,220.604,202.577,220.604z"></path> <path d="M52.329,170.782c-2.987-3.755-4.599-8.576-4.599-13.63v-4.77H7.516c-2.916,0-5.569,1.398-6.806,4.039 c-1.237,2.641-0.835,5.614,1.031,7.855l17.539,20.981L1.56,208.252c-1.746,2.27-2.051,5.461-0.787,8.03 c1.265,2.569,3.88,4.322,6.743,4.322h86.906C94.423,220.604,62.481,183.542,52.329,170.782z"></path> <path d="M64.64,162.185c1.403,1.678,3.682,2.916,5.895,2.916h156.241c1.79,0,3.922-1.039,5.12-2.368 c1.148-1.275,1.792-3.403,1.792-5.003V84.346c0-4.151-3.654-7.95-7.805-7.95H70.535c-4.151,0-7.805,3.22-7.805,7.371v73.384 C62.73,158.918,63.52,160.845,64.64,162.185z"></path> </g> </g></svg>'}
{addPageBuilderBlockParameter label="Optional Value" variableName="optionalValue" type="text"}
{addPageBuilderBlockParameter label="Logical Value" variableName="logicalValue" type="select" options="'On':'on','Off':'off'"}

<div class="page-builder-rich-test">
    -{$logicalValue}/{$optionalValue}-<br />
    {if "{$logicalValue}" == "on"}
    Setting is ON<br />
    {else}
    Setting is OFF<br />
    {/if}
    {if "{$optionalValue}"}
    Optional Value is set to "{$optionalValue}".<br />
    {/if}
</div>

Configuring your Widget/Object

It is possible to configure a range of things for a Widget. You should do this using the following two methods:

setPageBuilderBlockProperties - This configures the way the Widget/Object appears in the Page Builder.
addPageBuilderBlockParameter - This allows you to add and then configure parameters for your Widget/Object for the use to configure.

Using setPageBuilderBlockProperties

This configures the way the Widget/Object appears in the Page Builder and accepts the following parameters.

Parameter Name	Type	Validation	Notes
title	String	- Max length: 32 characters	This will default to the filename of the block.
category	String	- Min length: 3 characters - Max length: 16 characters	This will set the group in the Page Builder UI under which this Widget/Object will appear. This defaults to “Aurora” if not set.
supportedContentTypes	Pipe Delimited String	One or more of: - product - product-category - blog - filter-header - snippet	If not provided (or blank), the Widget will appear in all Page Builders across Aurora.
iconSvg	String	None, however speachmarkes (“) will automatically be escaped.	Aurora will use a default icon if one is not provided.

📘
All parameters are completely optional.

Using addPageBuilderBlockParameter

This configures the way the Widget/Object appears in the Page Builder and accepts the following parameters.

Parameter Name	Type	Validation	Notes
label	String	- Min length: 3 characters - Max length: 32 characters	This sets the label/name that will be displayed for this Widget/Object in the Page Builder UI.
variableName	String	My only contain: - Alphanumeric Characters - Underscores	All parameters are made available to you in your Template file. This sets the name of the variable that will be made available to you containing the value configured by the user.
type	String	Must be “text” or “select”. If it is not one of these two, then “text” will be transparently used instead.	This tells Aurora what type of input you want this to accept.
options	String	This will be validated by attempting to decode the string as JSON. If a parameter fails validation, then the parameter will not be rendered to the PB UI and instead and error will be output to the UI in its place.	This is only used when type is set to 'select' and controls what options should be presented in the list of options. Please see the following valid example: 'Width: Full':100,'Width: Half':50,'Width: Quarter':25

📘
All parameters are completely optional.
If this method is not called at all, then no custom parameters will be displayed in the UI.

Viewing Errors and Notices

It is very common to run into problems when configuring your Widgets and so it is important to understand how to find out more information when things go wrong.

In the event that Aurora is unable to render some aspect of your Widget, it will include ad much detail as it can in the Widgets configuration panel.

Please see the following example and notice the "Show Errors" link that can be clicked in order to expose a dialogue that contains the details required. In the example the label given to one of the Widget's parameters is too short: