Widget Definition XML File

Widget Definition XML File

The Widget Definition XML file is the main configuration for a Widget.  This file defines the Widget's properties, resources, code, and the template for rendering content. 

Widget Definition files are stored in the rxconfig/Widgets folder. All well formed files in this directory are made available as Widgets on the Widget tray. 

File Format

The Widget Definition file is composed of the following blocks.  The example markup below is the source code for the Percussion IFrame Widget.


XML Preamble

The XML Preamble identifies the file as an XML document.  It is best practice to place a comment describing the Widget under the XML declaration.

Widget Definition File Pre-Amble

Widget Preferences

The Widget Preferences block defines the main attributes for a Widget.

titleThe title of the Widget to be displayed in the Percussion UI.
contenttype_nameThis is the name of the backing content type for the Widget.  This should be left empty for Feature widgets. 
categorySpecifies the Category that this Widget belongs to in the Widget tray
descriptionA business user friendly description of this widget.  This should describe what the Widget does.
authorThe individual or organization that developed the Widget
thumbnail The icon that is used to represent the widget in the Widget Tray. 
is_responsive If true indicates that this Widget relies on the systems Responsive framework.
preferred_editor_height A pixel based setting for the preferred editor height
preferred_editor_widthA pixel based setting for the preferred editor width
create_shared_assetWhen true, this Widget can be created as a Shared Asset.  When false it will only be displayed as an option in the Template or Page Layout Editor.  Defaults to true.
is_editable_on_templateWhen true, the Widget may be Edited on the Content tab of the Template, when false the Content will only be editable at the Page level.  Defaults to true.

 An example WidgetPrefs block is pictured below:

Widget Preferences


User Preferences

User Preferences are the Layout properties of the widget. A Widget can have a number of Layout Properties defined. 

nameThe Widget unique name to use for the property.
display_nameA business user friendly name for the property.
default_valueThe default value for the property.
data_typestring, date, number,bool, enum
requiredtrue or false indicating that the property is required.

The example below shows an example Layout property block.

Widget User Preferences

The "enum" data type allows for lists to be defined within a UserPref.  When the enum data type is selected, a drop down list will be displayed for the property that is based on the <EnumValue> elements within the <UserPref> element.

valueThe value that should be stored when this element is selected for the Layout property.
display_valueA business user friendly string that will be displayed to the end user in the drop down list.

An example <EnumValue> setup is listed below.

Enum Data Type Example

CSS Preferences

The CSS Preferences block corresponds to the Style tab in the Template and Page editor.  One or more CssPref elements may be defined to provide the user with configurable CSS style properties on the Widget.  By convention, all Percussion Widgets must include the rootclass <CssPref>

nameA Widget unique name for this Style Property.
display_nameA business user friendly name for this Style property.

datatypestring, number, bool, date, enum


An example <CssPref> element is pictured below:

Widget CSS Preferences

Code Block

The <Code> element contains A JEXL script that is responsible for setting up variables for use in the Content block.  JEXL is a JavaScript like scripting language that allows the developer to set up the various variables and properties associated with a Widget so that they can be used in the Widgets Display Template (or <Content> block). Refer to the JEXL Syntax Reference for more information on JEXL syntax.  NOTE: The Code Block must be contained in a <![CDATA[ element.


typeThe programming language used in the Code block.  Currently "jexl" is the only option.

 A snipped example Code Block is displayed below:

Widget Code

Content Block

Also known as the Display Template for a Widget, the <Content> element contains the Template responsible for Rendering the Widget contents at Edit, Preview, and Publish.  Templates use the Velocity markup language, a reference on Velocity syntax can be found here. NOTE: The Content Block must be contained in a <![CDATA[ element.

typeThe template engine used to render the content.  Currently "velocity" is the only option.

Widget Template

End Widget


Leave a comment