Class Zapatec.Widget

Object
   |
   +--Zapatec.EventDriven
         |
         +--Zapatec.Widget

Direct Known Subclasses:

Zapatec.ColorPicker, Zapatec.ChildWidget, Zapatec.EditInline, Zapatec.Spinner, Zapatec.ProgressBar

class Zapatec.Widget

extends Zapatec.EventDriven

config

Object config

Zapatec.Widget

Zapatec.Widget(<object> oArg)

Base widget class.

 Defines following config options:

 theme [string] Theme name that will be used to display the widget.
 Corresponding CSS file will be picked and added into the HTML document
 automatically. Case insensitive. Default: "default".
 May also contain relative or absolute URL of themes directory.
 E.g. "../themes/default.css" or "http://my.web.host/themes/default.css".

 themePath [string] Relative or absolute URL to themes directory.
 Trailing slash is required. Default: path to child widget's file +
 "../themes/". You may also include path into "theme" option instead of using
 "themePath" option.

 asyncTheme [boolean] Load theme asynchronously. This means that script
 execution will not be suspended until theme is loaded. Theme will be applied
 once it is loaded. Default: false.

 source Depends on "sourceType" option. Possible sources:
 -----------------------------------------------------------------------------
 sourceType     | source
 ---------------|-------------------------------------------------------------
 1) "html"      | [object or string] HTMLElement or its id.
 2) "html/text" | [string] HTML fragment.
 3) "html/url"  | [string] URL of HTML fragment.
 4) "json"      | [object or string] JSON object or string (http://json.org).
 5) "json/url"  | [string] URL of JSON data source.
 6) "xml"       | [object or string] XMLDocument object or XML string.
 7) "xml/url"   | [string] URL of XML data source.
 -----------------------------------------------------------------------------

 sourceType [string] Used together with "source" option to specify how
 source should be processed. Possible source types:
 "html", "html/text", "html/url", "json", "json/url", "xml", "xml/url".
 JSON format is described at http://www.json.org.

 callbackSource [function] May be used instead of "source" and
 "sourceType" config options to get source depending on passed arguments.
 Receives object with passed arguments. Must return following object:
 {
   source: [object or string] see table above for possible sources,
   sourceType: [string] see table above for possible source types
 }

 asyncSource [boolean] Load source asynchronously. This means that
 script execution will not be suspended until source is loaded. Source will be
 processed once it is loaded. Default: true.

 reliableSource [boolean] Used together with "json" or "json/url"
 sourceType to skip JSON format verification. It saves a lot of time for large
 data sets. Default: true.

 eventListeners [object] Associative array with event listeners:
 {
   [string] event name: [function] event listener,
   ...
 }

 Defines internal property config.
 

Parameters:
oArg - User configuration

addCircularRef

void addCircularRef(<object> oElement, <string> sProperty)

Saves a property that must be set to null on window unload event. Should be used for properties that can't be deleted by garbage collector in IE 6 due to circular references.

 Defines internal property widgetCircularRefs.
 

Parameters:
oElement - DOM object
sProperty - Property name

addStandardEventListeners

void addStandardEventListeners()

Adds standard event listeners.

addUserEventListeners

void addUserEventListeners()

Adds custom event listeners.

configure

void configure(<object> oArg)

Configures widget.

Parameters:
oArg - User configuration

createProperty

void createProperty(<object> oElement, <string> sProperty, <any> val)

Assigns a value to a custom property of DOM object. This property will be set to null on window unload event. Use this function to create properties that can't be deleted by garbage collector in IE 6 due to circular references.

Parameters:
oElement - DOM object
sProperty - Property name
val - Property value

defineConfigOption

void defineConfigOption(<string> sOption, <any> val)

Defines config option if it is not defined yet. Sets default value of new config option. If default value is not specified, it is set to null.

Parameters:
sOption - Config option name
val - Optional. Config option default value

discard

void discard()

Deletes a reference to the object from the internal list and calls method Zapatec.Widget.removeCircularRefs(). This lets JavaScript garbage collector to delete an object uless there are any external references to it. Id of discarded object is reused. When you create new instance of Widget, it obtains id of discarded object.

editData

void editData(<object> oArg)

Loads data passed from other widget to view or edit them. Override this in child class.

 Argument object format:
 {
   data: [any] data in format specific for each widget
 }

 Fires event:
 

 
editData. Listener receives argument object passed to this
 method.
 
 

Parameters:
oArg - Argument object

editDataCancel

void editDataCancel()

Cancels editing. Ususally just hides the widget.

 Fires event:
 

 
editDataCancel before hiding of widget
 
 

editDataGet

any editDataGet()

Returns edited data. Override this in child class.

Returns:
Edited data in format specific for each widget.

editDataReceive

void editDataReceive(<object> oArg)

Receives data back from other widget previosly passed to it using its Zapatec.Widget.editData() method. Override this in child class.

 Argument object format:
 {
   data: [any] data in format specific for each widget
 }

 Fires event:
 

 
editDataReceive. Listener receives argument object passed to this
 method.
 
 

Parameters:
oArg - Argument object

editDataReturn

void editDataReturn(<object> oArg)

Returns edited data back to the widget from which they were received. Passes data to Zapatec.Widget.editDataReceive() method of that widget. Then calls Zapatec.Widget.editDataCancel() to hide this widget.

 Argument object format:
 {
   widget: [object] widget object
 }

 Fires event:
 

 
editDataReturn before passing data to the specified widget.
 Listener receives argument object passed to this method.
 
 

Parameters:
oArg - Argument object

formElementId

string formElementId(oArg)

Forms unique element id from widget id, unique counter and provided prefix and suffix.

 Arguments object format:
 {
   prefix: [string, optional] prefix, default: 'zpWidget',
   suffix: [string, optional] suffix, default: '-'
 }
 E.g. if widget id is 0, unique counter is 1 and following object provided
 {
   prefix: 'zpWidget',
   suffix: 'Item'
 },
 id will be 'zpWidget0Item1'.

 Defines internal property widgetUniqueIdCounter.
 

Parameters:
oArg - [object] Arguments object

Returns:
Element id

getClassName

string getClassName(oArg)

Forms class name from theme name and provided prefix and suffix.

 Arguments object format:
 {
   prefix: [string, optional] prefix,
   suffix: [string, optional] suffix
 }
 E.g. if this.config.theme == 'default' and following object provided
 {
   prefix: 'zpWidget',
   suffix: 'Container'
 },
 class name will be 'zpWidgetDefaultContainer'.
 

Parameters:
oArg - [object] Arguments object

Returns:
Class name

getConfiguration

object getConfiguration()

Returns current configuration of the widget.

Returns:
Current configuration

hideContainer

Object hideContainer(<object> effects, <number> animSpeed, onFinish)

Hides widget using given effects and animation speed. You need to define this.container to use this method.

Parameters:
effects - list of effects to apply
animSpeed - possible values - 1..100. Bigger value - more fast animation.

init

void init(<object> oArg)

Initializes object.

 Important: Before calling this method, define config options for the widget.
 Initially "this.config" object should contain all config options with their
 default values. Then values of config options will be changed with user
 configuration in this method. Config options provided by user that were not
 found in "this.config" object will be ignored.

 Defines internal property id.
 

Parameters:
oArg - User configuration

loadData

void loadData(<object> oArg)

Loads data from the specified source.

 If source is URL, fires events:
 

 
fetchSourceStart before fetching of source
 
fetchSourceError if fetch failed. Passes one argument to the
 listener: error object received from Zapatec.Transport.fetch().
 
fetchSourceEnd after source is fetched or fetch failed
 

 Fires events:
 

 
loadDataStart before parsing of data
 
loadDataEnd after data are parsed or error occured during
 fetch
 

 fetchSourceError is fired before fetchSourceEnd and
 loadDataEnd.
 

Parameters:
oArg - Arguments object passed to callbackSource function

loadDataHtml

void loadDataHtml(<object> oSource)

Loads data from the HTML source. Override this in child class.

Parameters:
oSource - Source HTMLElement object

loadDataHtmlText

void loadDataHtmlText(<string> sSource)

Loads data from the HTML fragment source.

Parameters:
sSource - Source HTML fragment

loadDataJson

void loadDataJson(<object> oSource)

Loads data from the JSON source. Override this in child class.

Parameters:
oSource - Source JSON object

loadDataXml

void loadDataXml(<object> oSource)

Loads data from the XML source. Override this in child class.

Parameters:
oSource - Source XMLDocument object

loadTheme

void loadTheme()

Loads specified theme.

 Fires events:
 

 
loadThemeStart before starting to load theme
 
loadThemeEnd after theme is loaded or theme load failed
 
loadThemeError after theme load failed. Passes one argument to the
 listener: error object received from Zapatec.Transport.loadCss().
 

 Defines internal property themeLoaded.
 

reconfigure

void reconfigure(<object> oArg)

Reconfigures the widget with new config options after it was initialized. May be used to change look or behavior of the widget after it has loaded the data. In the argument pass only values for changed config options. There is no need to pass config options that were not changed.

 Note: "eventListeners" config option is ignored by this method because it is
 useful only on initialization. To add event listener after the widget was
 initialized, use addEventListener method instead.
 

Parameters:
oArg - Changes to user configuration

showContainer

Object showContainer(<object> effects, <number> animSpeed, <function> onFinish)

Shows widget using given effects and animation speed. You need to define this.container to use this method.

Parameters:
effects - list of effects to apply
animSpeed - possible values - 1..100. Bigger value - more fast animation.
onFinish - Function to call on effect end.

showHideContainer

Object showHideContainer(<object> effects, <number> animSpeed, onFinish, <boolean> show)

Show/hides widget using given effects and animation speed. You need to define this.container to use this method.

Parameters:
effects - list of effects to apply
animSpeed - possible values - 1..100. Bigger value - more fast animation.
show - if true - show widget. Otherwise - hide.

callMethod

<static> any callMethod(<number> iWidgetId, <string> sMethod)

Finds a widget by id and calls specified method with specified arguments and returns value from that method.

Parameters:
iWidgetId - Widget id
sMethod - Method name
any - Any number of arguments

Returns:
Value returned from the method

getElementById

<static> object getElementById(<string> element)

Converts element id to reference.

Parameters:
element - Element id

Returns:
Reference to element

getStyle

<static> string getStyle(<object> element)

Returns style attribute of the specified element.

Parameters:
element - Element

Returns:
Style attribute value

getWidgetById

<static> object getWidgetById(iId)

Finds a widget by id.

Parameters:
Widget - id

Returns:
Widget or undefined if not found