Installation

The widget engine will have an installation routine that creates the necessary directories where the widgets will reside.

Startup

On startup, the plugin needs to perform the following actions:

• Add the #widget method to the application helper
• Load the Widget base class

Widget loading

Widget classes are only loaded into memory when they are needed. The Rails configuration setting for reloading classes is used to determine whether the classes are reloaded on each access (development) or required only once (production).

Widget rendering sequence

The widget is rendered by calling the #widget(widget, options = {}) helper. This will perform the following steps:

• Lookup the widget class that belongs to the widget given as the first parameter
• Fetch the session info/context for the widget
• Create the widget object, passing the options and the context
• Run the #widget_setup
• Render the widget partial

Widget state

The widget state is stored in the session. There will be one entry for the on-page-state and one for the permanent state information.

Naming: The widget entries will internally be name using the convention of widget_<widget_name>_<widget_id>_{permanent|onpage}.

# Just an example to show the 
@session = {
...
  :widget_sidebar_sidebar1_permanent => {
    :foo => "bar"
  }
  :widget_sidebar_sidebar1_onpage => {
    :foo => "bar"
  }

Accessing the state

The widget state will be accessed using the two methods Widget#permanent_state and Widget#on_page_state. Each will return a Hash with the state values. If no state exists, an empty Hash is created.

As long as these methods are not called, nothing will be written into the session hash.

The on_page_state will be cleared when a page is reloaded, the widget system must ensure that it is cleaned when the before_render method is called. The on-page state will not be cleared if the widget system knows that the user is still on the same page.

Widget callbacks

To interact with each widget, URL-base parameter passing is not likely going to work. Ideally, the approach would use AJAX and fall back to another method when Javascript is not available.

The system is described in the WidgetApi document. The sequence will be the following:

AJAX callback

• The link will call a special controller for the Widget AJAX callback. The AJAX call contains the information for the further handling:
  • The widget's name
  • The widget's id
  • The name of the handler method in the widget
  • The options for the call
• The controller creates a new widget object, using the name and id from the call
• The state information is available on the widget
• The controller calls the given handler method on the widgets, passing the parameters from the AJAX call
• The controller calls the before_render method on the widget
• The widget template is rendered
• The new widget content is sent back to the user, and replaced in the <div> of the widget instance

Installation for callbacks

The widget installation will automatically install the controller for the AJAX callbacks.

Configuration Files

The widget helper will accept an option that takes the name of a YAML configuration file. The contents of that file will be added to the option hash that is passed to the widget. Attention: In production mode, the options from the file must be cached, to avoid unnecessary file io load. (Example: widget(:foo, :config_file => "bar")

The file will be found in the widget's folder, using the given name plus the .yml extension.