To support a greater range of widgets without the need to customize the application, Percussion has developed a Widget Builder that will allow users with HTML, CSS and Javascript skills to create their own custom widgets while ensuring they are compatible with future releases of the Percussion CMS.
Widget Builder servers two main purposes:
- It allows designers to build custom widgets such as panel sliders or tabbed displays, that will allow content contributors to easily add content.
- It supports the ability to create structured content comprised of multiple fields, similar to a blog post. For example, an Article widget could contain an author field, a title, a release date, a summary and the main body post.
Widget Builder is enabled by default as of CM1 version 4.4, but for versions prior you will need to enable this feature. To do this you will need to open 'server.properties' located in:
<PercussionRootdirectory> -> rxconfig -> Server.
Add the line 'isWidgetBuilderActive=true' to the document and restart the CM1 service.
Creating a custom widget
Creating a custom widget involves uploading the appropriate CSS and javascript files, and then defining the widget through the Widget Builder UI. Below are the general steps that must be followed to create a custom widget.
- Upload CSS and Javascript files into the Design folder of the Finder. We recommend that you place them in the same folder as your site theme, but it is not required. Make sure you note the location of the files.
- Click the 'create new widget' icon located in the top-right portion of the screen. Create your widget metadata. This will include the name, description, widget prefix , author, publisher URL, version, and whether the widget is responsive.
- When naming a field, the field name cannot be an exact match of any of the Reserved Field Names. You will not be able to save the widget if a field name matches one of these fields.
- The widget prefix is a means of uniquely identifying your widgets. Percussion uses the prefix 'perc'.
- The version must be in the format 1.2.3
- Note: The "Is Responsive" flag is for widget designers to indicate whether or not the widget is responsive for the content contributor. Selecting it does NOT cause the widget to become responsive.
- Define the fields that will be used by contributors to enter content. Widget Builder support text, rich text, image, file, text area and date fields.
- Link to the CSS and Javascript files that you uploaded in step 1 (i.e., /web_resources/themes/PanelSlider/PanelSliderCss.css).
- Create the widget HTML.
Syntax for creating the widget HTML
When you are creating the widget HTML, you can insert any field you've defined for the widget by using the syntax '$fieldname'. For example, assume you have created an article widget with three fields:
| Name | Label | Type |
| articleTitle | Title | text |
| articleBody | Content | rich text |
| articleImage | Picture | image |
To define the HTML for these fields you can click the Auto Generate link on the Display tab to create sample code that would render this widget.
<div>
<div>$articleTitle</div>
<div>$articleBody</div>
</div>
You can then modify the HTML to whatever format you would like. Widget Builder uses Velocity as it's template engine, a full reference of the available Velocity commands can be found here.
Deploying a widget
Once you have defined your widget you can deploy it for use in templates and pages. To deploy the widget you select the widget and click the Deploy button. For the initial release of Widget Builder, once widgets are deployed they cannot be "un-deployed."
Once a widget it deployed, it will be visible in the "Add Widget" tray as a Custom type. Once deployed, widgets can be used in the same manner as any other widget. They can be added to a page or template, and content can be saved as a shared asset for reuse.
Disabling a widget
Once a widget has been deployed, if you no longer wish that widget to be used, you can disable it using the Widget Configuration Gadget on the Percussion Dashboard. This gadget lists all widgets in the system, both Percussion and custom. You can enable or disable any widget. Disabling a widget will prevent users from adding a widget to a page or template and will prevent users from being able to create a shared asset using that widget. It will not affect any pages or templates that already have that widget in use.
Sample Widgets
Below are sample configurations of widgets built using the Widget Builder