Zapatec.Widget

Overview | File | Class | Tree | Index | Help

Zapatec Utils

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

Defined in zpwidget.js

Field Summary
`Object` | `config`

Constructor Summary
`Zapatec.Widget(<object> oArg)` Base widget class.

Method Summary
`void` | `acceptData(<object> oArg)` Receives data back from other widget previously passed to it using its Zapatec.Widget.receiveData() method.
`void` | `addCircularRef(<object> oElement, <string> sProperty)` Saves a property that must be set to null on window unload event.
`void` | `addStandardEventListeners()` Adds standard event listeners.
`void` | `addUserEventListeners()` Adds custom event listeners.
`void` | `configure(<object> oArg)` Configures widget.
`void` | `createProperty(<object> oElement, <string> sProperty, <any> val)` Assigns a value to a custom property of DOM object.
`void` | `defineConfigOption(<string> sOption, <any> val)` Defines config option if it is not defined yet.
`void` | `discard()` Deletes a reference to the object from the internal list and calls method Zapatec.Widget.removeCircularRefs().
`string` | `formElementId(oArg)` Forms unique element id from widget id, unique counter and provided prefix and suffix.
`string` | `getClassName(oArg)` Forms class name from theme name and provided prefix and suffix.
`object` | `getConfiguration()` Returns current configuration of the widget.
`Object` | `getMessage(key)` Get message for given key, make substitutions and return.
`Object` | `hideContainer(<object> effects, <number> animSpeed, onFinish)` Hides widget using given effects and animation speed.
`void` | `init(<object> oArg)` Initializes object.
`void` | `loadData(<object> oArg)` Loads data from the specified source.
`void` | `loadDataHtml(<object> oSource)` Loads data from the HTML source.
`void` | `loadDataHtmlText(<string> sSource)` Loads data from the HTML fragment source.
`void` | `loadDataJson(<object> oSource)` Loads data from the JSON source.
`void` | `loadDataXml(<object> oSource)` Loads data from the XML source.
`void` | `loadTheme()` Loads specified theme.
`void` | `receiveData(<object> oArg)` Loads data passed from other widget for example to view or edit them.
`void` | `reconfigure(<object> oArg)` Reconfigures the widget with new config options after it was initialized.
`any` | `replyData()` Prepares processed data to return them back to the sender in the same format as they were received in Zapatec.Widget.receiveData().
`void` | `replyDataCancel()` Cancels processing of the data received from the sender in Zapatec.Widget.receiveData().
`void` | `replyDataReturn(<object> oArg)` Returns processed data back to the specified widget (not necessarily to the same widget from which they were received in Zapatec.Widget.receiveData()).
`Object` | `showContainer(<object> effects, <number> animSpeed, <function> onFinish)` Shows widget using given effects and animation speed.
`Object` | `showHideContainer(<object> effects, <number> animSpeed, onFinish, <boolean> show)` Show/hides widget using given effects and animation speed.
`<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.
`<static> object` | `getElementById(<string> element)` Converts element id to reference.
`<static> string` | `getStyle(<object> element)` Returns style attribute of the specified element.
`<static> object` | `getWidgetById(iId)` Finds a widget by id.

Methods inherited from class Zapatec.EventDriven
`addEventListener, unshiftEventListener, removeEventListener, getEventListeners, isEventListener, isEvent, removeEvent, fireEvent`

Field Detail

### config

    Object config

Constructor Detail

### 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".

     Special theme "auto" is used to detect theme automatically depending from OS.
     It is replaced automatically with one of the following values:

     winvista for Windows Vista
     winxp for Windows XP
     win2k for other Windows
     macosx for Mac OSX
     default for other OS

     Make sure all these themes exist before using "auto" theme for the widget.

     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.

     callbackConvertSource [function] May be used to convert input data
     passed with "source" config option from custom format into internal format of
     the widget. Must return converted source.

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

     Defines internal property config.

Parameters:

`oArg` - User configuration

Method Detail

### acceptData

    void acceptData(<object> oArg)

Receives data back from other widget previously passed to it using its Zapatec.Widget.receiveData() method. Extend this in child class.

     Argument object format:
     {
       widget: [object] Caller widget instance,
       data: [any] Data in format specific for each widget
     }

     Fires event:

     acceptData. Listener receives argument object passed to this
     method.

Parameters:

`oArg` - Argument object

### 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 unless 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.

### 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

### getMessage

    Object getMessage(key)

Get message for given key, make substitutions and return. If more then 1 argument given - method will replace %1, .. %N with corresponding argument value

Parameters:

`key` - {Object} String, object or anything else that can be treated as array key in Javascript. Required.

`substitution1` - {String} First substitution to the string. Optional. ...

`substitutionN` - {String} Last substitution to the string. Optional.

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

### receiveData

    void receiveData(<object> oArg)

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

     Argument object format:
     {
       widget: [object] Optional. Sender widget instance,
       data: [any] Data in format specific for each widget
     }

     Saves passed widget in private property dataSender for later use in
     Zapatec.Widget.replyDataReturn().

     Fires event:

     receiveData. Listener receives argument object passed to this
     method.

Parameters:

`oArg` - Argument object

### 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

### replyData

    any replyData()

Prepares processed data to return them back to the sender in the same format as they were received in Zapatec.Widget.receiveData(). Extend this in child class.

Returns:

Processed data in format specific for each widget.

### replyDataCancel

    void replyDataCancel()

Cancels processing of the data received from the sender in Zapatec.Widget.receiveData(). Ususally just hides the widget (calls hide method of the widget if it is defined).

     Removes private property dataSender.

     Fires event:

     replyDataCancel before the widget is hidden

### replyDataReturn

    void replyDataReturn(<object> oArg)

Returns processed data back to the specified widget (not necessarily to the same widget from which they were received in Zapatec.Widget.receiveData()). Passes data to Zapatec.Widget.acceptData() method of that widget. Then calls Zapatec.Widget.replyDataCancel() to hide this widget.

     Argument object format:
     {
       widget: [object] Optional. Receiver widget instance
     }

     If receiver widget was not specified, uses widget passed to
     Zapatec.Widget.receiveData() and saved in private property
     dataSender.

     Fires event:

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

Parameters:

`oArg` - Argument object

### 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

Overview | File | Class | Tree | Index | Help

Zapatec Utils

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Documentation generated by JSDoc on Thu Aug 16 12:18:39 2007