SwatObject
└─SwatUIObject
└─SiteGadget
public abstract class SiteGadget
extends SwatUIObject
| Field Summary | |
|---|---|
| protected SiteApplication | The application in which this gadget exists. |
| Fields inherited from Swat.SwatUIObject | |
|---|---|
| classes, html_head_entry_set, parent, visible | |
| Constructor Summary | |
|---|---|
SiteGadget(SiteApplication app, SiteGadgetInstance instance) Instantiates this gadget. |
|
| Method Summary | |
|---|---|
| protected void | define() Provides a location for gadget subclasses to define settings; define the default title; and to add external style-sheet and JavaScript resources to this gadget. |
| protected void | defineAjaxProxyMapping(string from, string to) Defines an AJAX proxy mapping for this gadget. |
| protected void | defineDefaultTitle(string title) Defines the default title of this gadget. |
| protected void | defineDescription(string description) Defines the description of this gadget. |
| protected final void | defineSetting(string name, string title, string type, mixed default) Defines a setting for this gadget. |
| void | display() Displays this gadget. |
| protected void | Displays content for this gadget. |
| protected void | Displays the title of this gadget. |
| protected void | Wraps the content of this gadget in a div for final display. |
| final array | Gets all defined AJAX proxy mappings of this gadget. |
| protected mixed | getDefaultValue(string name) Gets the default value of a setting. |
| string | Gets the description of this gadget. |
| final array | Gets all defined settings of this gadget. |
| string | getTitle() Gets the title of this gadget. |
| protected mixed | getValue(string name) Gets a setting value for this gadget. |
| protected boolean | hasSetting(string name) Gets whether or not this gadget has the specified setting. |
| protected boolean | hasValue(string name) Gets whether or not a setting value exists for a setting of this gadget. |
| void | init() Initializes this gadget. |
| private void | Lazily loads all instance setting values for this gadget. |
| void | process() Processes this gadget. |
| Methods inherited from Swat.SwatUIObject | |
|---|---|
| addComment, addJavaScript, addStyleSheet, addTangoAttribution, copy, getCSSClassNames, getCSSClassString, getFirstAncestor, getHtmlHeadEntrySet, getInlineJavaScript, getUniqueId, isVisible | |
protected SiteApplication $app
The application in which this gadget exists
public SiteGadget(SiteApplication app, SiteGadgetInstance instance)
Instantiates this gadget
Developers should use the SiteGadgetFactory::get() method
rather than instantiating gadgets directly. The factory will resolve
and instantiate the correct gadget class automatically.
app - the application in which this gadget exists.instance - the gadget instance used to bind setting values to this gadget.protected void define()
Provides a location for gadget subclasses to define settings; define the default title; and to add external style-sheet and JavaScript resources to this gadget
protected void defineAjaxProxyMapping(string from, string to)
Defines an AJAX proxy mapping for this gadget
An AJAX proxy is used to load third-party content from other domains using JavaScript. If this gadget needs to load third-party content from another domain in JavaScript, it should define an AJAX proxy mapping.
from - the source string from which the $to is mapped.to - the URI to which to map the source string. This may contain regular expression replacement markers of the form \1, \2, etc.protected void defineDefaultTitle(string title)
Defines the default title of this gadget
The default title is used as the title of this gadget when selecting the gadget from a list or when no title value is set in the gadget instance.
title - the default title of this gadget.protected void defineDescription(string description)
Defines the description of this gadget
The description is used on the gadget selection page in the admin and provides a short description of this gadget above and beyond the title.
For example, an Arbitrary Content gadget may have the following description:
Provides a place to place arbitrary content in the sidebar. Content may include custom XHTML by specifying the 'content_type' setting.
description - the description of this gadget.protected final void defineSetting(string name, string title, string type, mixed default)
Defines a setting for this gadget
name - the programmatic name of the setting. This should follow the naming rules for PHP variables.title - the title of the setting. This may be used for display in a settings editor, for example.type - optional. the type. Should be one of: 'boolean', 'integer', 'float', 'date', 'string' or 'text'. Text and string are equivalent except they may be edited differently in a settings editor. If not specified, 'string' is used.default - optional. The default value of the setting. If not specified, null is used.public void display()
Displays this gadget
Provides a hook into the SwatWidget::display() step of the
Swat UI tree.
In the default implementation, the gadget title is displayed, followed by the gadget content wrapped in a div.
protected void displayContent()
Displays content for this gadget
This method is provided for gadget authors. The default implementation is empty.
protected void displayTitle()
Displays the title of this gadget
The title is displayed in a h3 element with the CSS class 'site-gadget-title'.
protected void displayWrappedContent()
Wraps the content of this gadget in a div for final display
If the SiteGadget::displayContent() method displays any content,
the content is wrapped in a div with the CSS class 'site-gadget-content'
by this method.
The default implementation frees gadget authors from having to remember to wrap their content in a special div for themes to work properly.
public final array getAjaxProxyMap()
Gets all defined AJAX proxy mappings of this gadget
protected mixed getDefaultValue(string name)
Gets the default value of a setting
name - the name of the setting.$name is not a valid setting name for this gadget.public string getDescription()
Gets the description of this gadget
public final array getSettings()
Gets all defined settings of this gadget
This is intended for use in a gadget editor.
public string getTitle()
Gets the title of this gadget
If the setting title does not have a value, the default
title is returned.
protected mixed getValue(string name)
Gets a setting value for this gadget
name - the name of the setting.protected boolean hasSetting(string name)
Gets whether or not this gadget has the specified setting
name - the name of the setting.protected boolean hasValue(string name)
Gets whether or not a setting value exists for a setting of this gadget
name - the name of the setting.public void init()
Initializes this gadget
Provides a hook into the SwatWidget::init() step of the Swat UI
tree.
private void lazyLoadValues()
Lazily loads all instance setting values for this gadget
public void process()
Processes this gadget
Provides a hook into the SwatWidget::process() step of the Swat
UI tree.
Base class for creating sidebar gadgets
All sidebar gadgets are instantiated with a
SiteGadgetInstance, which binds setting values to the gadget; and with a reference to the application.Sidebar gadgets are instances of
SwatUIObjectand may be added to aSiteSidebarparent widget.Gadgets have settings. Settings consist of a name, title, type and default value. Setting values come from the
SiteGadgetInstance.The settings available to all gadgets are:
string title- the title of this gadget. Gadgets may display this title using theSiteGadget::displayTitle()method. The default title as specified by theSiteGadget::defineDefaultTitle()method is used by default.Creating a gadget involves two main tasks:
SiteGadget::define()method.SiteGadget::init(),SiteGadget::process()andSiteGadget::display()methods where necessary. Most gadgets will only have to implement one or more of thedisplay()methods. Theinit()andprocess()methods are hooks into the Swat UI tree initilization and processing methods.