What makes up a Widget?

Widgets are designed to be self-contained, light-weight, easy to style and easily modifiable.  Each has the following components:

  • A Generic Render Handler

    • At the heart of each widget is a Generic Render Handler that provides the rendering for the element.  

    • Render Handlers are designed to be simple wherever possible, making them easy to understand and extend if needed. The goal is that in order to style the rendering of the widget to fit your needs, you should start with overrides to the CSS.  You should not have to modify the render handler directly, but if needed we have architected the render handlers to call Widget specific methods in a Widget CFC, which in turn may call common methods in a common CFC. Methods in eith of these CFCs can be overridden.

  • CSS style sheet specific to each render handler

    • Wherever possible modification should be limited to CSS.

    • A default CSS style sheet is provided for each Render Handler. To customize any  styles, you can provide an additional CSS file (with the same name with ‘_custom’ appended to the end), that overrides the default styling.  This stylesheet will automatically be loaded if it exists.

  • Widget Configuration via Custom Metadata Form

    • A default, but easily configurable set of Properties that controls the rendering of each widget is provided via default values in an associated Custom Metadata Form. When the widget is first initialized, these properties derive from that form.

    • Some or all of the properties in the widget’s configuration can be overridden using the new capabilities in CommonSpot 10.5 that allows you to override fields in a locked custom element or metadata form.  For example, a widget might come pre-defined to allow three color options (red, green, blue), but if you want to use your own colors, you can override the 'color' field and provide your own options.

  • Widget Configuration Interface

    • Content Contributors are provided an interface for setting the properties of the widget. If the properties are global to the entire widget, this is typically done by binding a metadata form to the render handler.

    • As part of importing the widget, a Metadata Form will be imported and bound to the widget’s Render Handler(s).  In this Metadata Form will be one or more fields that may be used to control editable aspects of the widget rendering.

  • Custom Element Definition  

    • Each widget contains a pre-defined custom element definition, having the minimal set of fields required by the widget.  However you don’t have to use this Custom Element. You can create your own or use an existing Custom Element as the source for the widget.

    • If you want to use the pre-defined Custom Element that comes with the widget, you can simply import the self-contained Custom Element in the widget.  If not, you may import the Render Handlers into your existing Custom Element directly, and then map the fields for each Generic Render Handler to your Custom Element’s fields. Note in either case you will also need to import the widget’s Metadata Form directly.

  • Optionally, a JavaScript file that is specific to the widget

    • If the widget requires an external JavaScript library, it will come included in the widget packet, and will be registered when importing.   

    • If JavaScript is provided specific to a Render Handler, it will be included as well.

    • You should not need to override the JavaScript files.