The Widget Builder is intended to provide a browser based tool to build Widgets for use in the CMS. The tool is meant to be simple enough for a relatively non-technical to build Custom Widgets. Advanced Widgets differ from Widget Builder Widgets in that they are constructed by hand by the developer, and using the Workbench tool.
About Widgets
A widget is an object that defines reusable data and how to render it as an html fragment for use in a Page. A widget has its own properties (e.g. name and description,) definition of shareable content, definition of user instance properties (that control how the content is rendered in a particular page) and a template (currently using the Apache Velocity template engine).
A widget definition is stored in an xml file that conforms to the Widget XML schema. The basic widget properties, user property definitions and template are specified in this file. A content type is used to define the content associated with the widget. A widget is not required to have user properties or content (e.g. a ‘share this’ widget may only have a chunk of html.) A widget can have additional resources such as files, images, etc. These can be used during Preview, Publish time, or both. Those used for publish time will be automatically managed so they are available on the published site.
Types of Widgets
There are two types of Advanced Widgets that can be created:
- Content Widgets
- Feature Widgets
Content Widgets are backed by a Content Type and typically used on Templates to capture & then format structured data All Content is managed by the Workflow engine, with full version tracking once the Widget is approved. Content Widgets become Asset types in the CM1 user interface.
Feature Widgets are not backed by a Content Type. They provide Layout properties only in the user interface and are typically used to package a specific behavior or a set of functionality for use on the published Web Site. Feature Widget's are lighter weight than Content Widgets as they do not have a dedicated Content Type in the Content Repository. It is not currently possible to create Feature Widgets with the Widget Builder, meaning that all Feature Widgets are Advanced Widgets.
A widget controls the following:
- How an area of a page is rendered for preview. There may be 0 or more properties that are exposed to the user that affect the rendering. The actual rendering is done by the server using the widget assembler.
- How an area of a page is rendered for editing. The editor is usually a form based editor that uses the same controls as when adding assets directly to the system.
- Retrieval and persistence of the user data during editing.
- May control how the widget properties are rendered.
- Exposes a set of fields for editing that have been defined as the ‘meta data’ for its associated content. These may be rendered when the other content is edited, or they could be rendered in their own window. The widget writer determines what fields are considered meta data and the appropriate presentation. The content type definition will be modified by adding a flag to the field to indicate whether it is meta data or not.
Widget Layout
The standard layout and naming convention for the files that make up a Widget is defined below:
| Location / File | Description |
| rx_resources/widgets/(widget name)/css/(widget name).css | Contains the primary widget definition. |
| rx_resources/widgets/<Widget Name>/[js | css | images] | Contains resources used to render the Widget in the Percussion User Interface |
| web_resources/widgets/<Widget Name>/[js | css | images] | Contains resources used by the Widget when it is rendered on the Published or Preview site. |
| ObjectStore/psx_ce<Widget Name>.xml (for Content Widgets only) | The Content Type definition. Typically edited using the Content Type editor in the Workbench |
| Any custom CMS Design Objects required by the Widget | XML Applications, Keywords, or other resources used by the Widget for it's functionality |
| rx_resources/stylesheets/<custom control>.xsl | Any custom Content Editor controls used by the Widget. |
| rxconfig/Resources/(widgetName)Resources.xml | Contains references to resources used by the widget. |
The primary file for defining a widget is the Widget Definition file.
Widget Builder Widget Definition
The Widget Builder tool generates a pre-defined set of Widget Definition files from the "Widget Builder Widget Definition". This definition is stored in the PSX_WIDGETBUILDERDEFINITION table in the backing Content Repository database. For this reason, when deploying Widget Builder Widgets that have been customized using the Advanced Tools, any changes are overwritten and lost when someone deploys the Widget via the Widget Builder feature..
Converting a Widget Builder widget to an advanced widget
Often Widget's may be prototyped or start out as Widget Builder widgets, and then need to be converted to Advanced Widgets. Converting a Widget Builder Widget to an Advanced Widget involves removing the Widget from the Widget Builder. If the Widget is not in use on the Web site this can be done by deleting the Widget from the Widget Builder tool and uninstalling the Widget with the Package Manager tool.
If the Widget has content on the system associated with it, and can't be deleted through the Widget builder, you will need to manually convert the Widget Builder widget to an Advanced Widget. With CM1 5.3 this requires a few manual steps, this will be automated in a future release. You must be an Admin or have access the SQL back-end in order to execute these steps. Backup your Display Template, and screen shot your Widget before executing these steps.
1. Remove the definition. Execute the following SQL to remove the Widget Builder Definition for the Widget. The SQL tool can be used for this if you are in the Admin role. http://your cm1 server:9992/Rhythmyx/test/sql.jsp.
DELETE FROM PSX_WIDGETBUILDERDEFINITION WHERE LABEL='MyCustomWidgetName'
2. Flush cache. Following this deletion the "flush cache" command must be run in the Admin Console to remove any cached references to the Widget Definition.
The Admin Console is accessible at the following URL:
http://percussionserver:9992/Rhythmyx/ui/admin/console.faces
The files for your Widget will still be on the file system.
Using the Workbench -> System view you can now edit the source of the Widget for Packaging.