From unroole CMS wiki
Jump to: navigation, search

Layout Editor Widgets.png

The layout editor with a simple asset widget selected and displayed in the sidebar menu.

Widgets are the primary way of adding content to Layouts. In the most basic sense a widget is a consistent element that can be used to display some pre-defined content or add dynamic functionality to a page. This can be anything from adding in simple text or images to communicating with a Point of Sale (POS) system to add items to a user's e-cart. The widget system allows developers to create whatever functionality they need to add to a page without requiring a content editor to have a programming background to use or work with.


Layout editor widget properties panel.png

One of the properties panels for the core asset widget. Each widget has some custom properties along with the general properties (id, classes).

Widget functionality was designed to be extended. Their design allows developers to build in any functionality required for part of a page. Since some functionality may require additional properties each widget is given two types of properties to help configure their functionality.

  • Custom
  • System

Custom properties allow for a content editor to modify the content or functionality of a widget in a pre-defined way. This could include changing the asset used on an asset widget or modifying the text of the text widget. It could also include more complex properties such as configuring api keys for communication with a 3rd party api or adding restrictions to a page based on a user's login credentials. These types of custom properties differ from system properties which include changing some information common to every widget such as HTML ID/Classes. The functionality provided by a widget is only limited by its design.

Editing widgets is a simple process:

  1. Open the widget edit area
    • From the Layout Editor Content area
      1. Click on the widget
      2. Click the orange pencil icon to open up the widget edit panel from the sidebar.
    • From the sidebar
      1. Click the box the widget belongs to in the sidebar list
      2. Click the widget from the box list
      3. Click the 'edit' button
  2. Make appropriate changes to the widget properties.
  3. Click save at the top of the panel to save changes.

Available Widgets

Listing out a variety of widgets available on a page.png

Widgets available for addition to a box in a non-standard installation.

The widgets that are available can varying depending on the engines and plugins used within a particular installation of the CMS. Not all installations will necessarily have the same set of widgets. Their are however some core and extended widgets which are generally provided as part of every installation.


  • Heading - Easy wrapper for consistent headings in a channel.
  • Asset - Provides a simple way to add images/videos or file links to a layout.
  • Gallery - Similar to assets but provides a way of consistently displaying grouped assets managed from the admin panel rather than the Layout Editor.
  • Text - Allows for simple formatted text in a page.
  • HTML - Adds the ability to display any HTML desired in a page.
  • Navigation - Display related site map navigation elements in a consistent structure.
  • Related Links - Displays other pages which are on the same subheading in the navigation tree.
  • Horizontal Divider - Add a consistent divider between two widgets in a box.

Extended Core

  • Information - Structured ways of displaying text/assets and links.
  • Addthis - Provides simple integration with the http://www.addthis.com/ service.
  • MetaTag - Allows for custom meta tags to be added to the layout (ex: open graph meta tags http://ogp.me/)
  • Articles Widgets (various) - Adds in blogging and news functionality similar to other cms' with comment and tagging integration.
  • Flash Message - Used to determine where messages from other widgets will be displayed in a layout.
  • Feedback - Adds in ability for users to provide feedback managed through the admin panel.
  • 360 Widget - Using assets from the asset library create an interactive rotating image.

Custom Widgets

Sometimes the existing widget set cannot be used to provide the functionality required for a particular page or layout. In this case a custom widget can be developed to satisfy the requirement and added to the available list of widgets as an engine.

Common Properties

Every widget in unroole has the following basic properties:

Name Description
Custom Id Type in a custom id. This id can then be used in CSS and Javascript to change the style and behaviour of this widget.
Custom Classes Type in a custom class, or mutiple classes seperated. These classes can then be used in CSS and Javascript to change the style and behaviour of this widget.

Widget Processing (Devs)

Since each layout can potentially contain many widgets each of which may rely on the data provided by other widgets in the layout a simple communication process exists to allow widgets to pass data between them. This could be useful, for example, when process a request on an e-commerce website where one widget manages items in a cart and then provides that information to other widgets on the page for use. This process uses a simple bundling mechanism called a Suitcase which captures some request data and can also be used to store data from other widgets. The widget communications process works as follows:

  1. prepare - Initially process the request data assuming no other data has been added to the suitcase by another widget. Data may be added to the suitcase during this step.
  2. create/update/delete - Depending on the request type create/update/delete data from the system or suitcase
  3. persist - Persist any processed data to permanent data stores.
  4. post - Finish any processing tasks that may have required a previous actions data
  5. persist - Persist any additional changes after the post
  6. respond - Information set in the previous actions is used to generate a response. Sometimes a widget can request a redirect or throw an error rather than simply render.

Since ordering of widget processing is not guaranteed all widgets are designed to be processed in any order.