Difference between revisions of "Widgets"

From unroole CMS wiki
Jump to: navigation, search
m
 
(4 intermediate revisions by one user not shown)
Line 65: Line 65:
 
* [[Text Widget|Text]] - Allows for simple formatted text in a page.
 
* [[Text Widget|Text]] - Allows for simple formatted text in a page.
 
* [[Html Widget|HTML]] - Adds the ability to display any HTML desired in a page.
 
* [[Html Widget|HTML]] - Adds the ability to display any HTML desired in a page.
* Navigation - Display related site map navigation elements in a consistent structure.
+
* [[Navigation Widget|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.
+
* [[Related Links Widget|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.
+
* [[Horizontal Divider Widget|Horizontal Divider]] - Add a consistent divider between two widgets in a box.
  
 
=== Extended Core ===
 
=== Extended Core ===
  
* Information/Section - Structured ways of displaying text/assets and links.
+
* [[Information Widget|Information]] - Structured ways of displaying text/assets and links.
* Addthis - Provides simple integration with the http://www.addthis.com/ service.
+
* [[Addthis Widget|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/)
+
* [[MetaTag Widget|MetaTag]] - Allows for custom meta tags to be added to the layout (ex: open graph meta tags http://ogp.me/)
 
* [[Article Widget|Articles Widgets (various)]] - Adds in blogging and news functionality similar to other cms' with comment and tagging integration.
 
* [[Article Widget|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.
+
* [[Flash Message Widget|Flash Message]] - Used to determine where messages from other widgets will be displayed in a layout.
 
* [[Feedback Widget|Feedback]] - Adds in ability for users to provide feedback managed through the admin panel.
 
* [[Feedback Widget|Feedback]] - Adds in ability for users to provide feedback managed through the admin panel.
 +
* [[360 Widget|360 Widget]] - Using assets from the asset library create an interactive rotating image.
  
 
=== Custom Widgets ===
 
=== 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.
 
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.
 +
 +
{{clear}}
 +
 +
== Common Properties ==
 +
 +
Every widget in unroole has the following basic properties:
 +
 +
{| class="wikitable"
 +
|-
 +
! 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.
 +
|}
  
 
{{clear}}
 
{{clear}}

Latest revision as of 09:30, 31 October 2012

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.

Functionality

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.

Core

  • 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.