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 Detail

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

 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

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