This document represent the guidelines useful to implement event attribute support on new widgets.

• In General
• Publish Chain Table
• Javascript Shared API
• Use of html classes
• Use of gwAttribute dojo widget properties/function

gwClass detail structure (from general/outer to specific/inner):

• gwClassDetail (one, typically identified with the variable detailContainer: may be a 'tab', a 'floatingPane' or a 'dialog')
• gwAttributeGroup (zero or more, it's an aggregation of gwAttribute)
• gwAttribute (zero or more)

Every gwWidget (aka gwAttribute dojo widget) has got, in general, two model representation: one for the gwClassDetail in 'edit' mode, and one for the 'visualization' mode. All gwWidgets marked with gwAttributeId_* should implement a specific shared js API to allow configuration user to configure the desired dynamic behavior inside gwClassDetail.

Developers should to provide to every gwAttribute dojo widget (marked with class 'gwAttributeId_*', see below):

1. commons shared properties (and, eventually, all needed JS API implementation, see below)
2. a publish of the event 'gwClassDetail/gwAttributeReady' (typically inside startup function, see below)

Providing the 'gwClassDetail/gwAttributeReady' publish it's very important to make all gwClassDetail logics to work:

• a gwAttributeGroup element waits for the 'gwClassDetail/gwAttributeReady' publish of all it's gwAttribute components, before doing

it's own 'gwClassDetail/formManagerReady' publish (and 'gwClassDetail/formManagerStarted' publish, see below)

• a gwClassDetail element waits for the 'gwClassDetail/formManagerReady' publish of all it's gwAttributeGroup components, before doing

it's own 'gwClassDetail/ready' publish (and 'gwClassDetail/allFormManagerStarted' publish, see below)

Maintaining the publish chain will grant the publish of the 'gwClassDetail/ready' event. This is very important because on it is based the execution of all gwAction of type onDetailReady, and the correct execution of all the gwAttribute event handlers configured in gwAdmin.

In addiction 'gwClassDetail/gwAttributeReady' publish it's important to allow the fire of 'gwClassDetail/formManagerStarted' from the parent gwAttributeGroup (that will trigger the publish of the 'gwClassDetail/allFormManagerStarted' event id the gwClassDetail) This is a publish mechanism parallel to the 'gwClassDetail/formManagerReady'/'gwClassDetail/ready' publish. This is useful for some gwWidgets (like dbComboBox) that, before be able to publish their 'gwClassDetail/gwAttributeReady' event, needs to compute their value basing on current values of the others gwWidgets in the form (because, for example, they have a queryClause with some #{} expressions that depends on it). These gwWidgets typically waits for 'gwClassDetail/allFormManagerStarted' event before performing it's own 'gwClassDetail/gwAttributeReady' publish.

A direct consequence of this is that if even only one gwWidget do not publish it's 'gwClassDetail/gwAttributeReady' event, the behavior of all gwWidgets (like dbComboBox) depending on 'gwClassDetail/allFormManagerStarted' publish, belonging to the same gwClassDetail, will be 'broken'.

This js API can be used in all configurable js on Geoweb. Typically they should be used in:

• gwClassDetailReady gwActions type
• eventHandler for gwWidget events

Available incoming parameters: /*Object*/ widget /*Object*/ eventWidget /*String*/ eventType /*String*/ gwClassName /*String*/ itemId /*Object*/ item /*Object*/ data /*Object*/ detailContainer /*String*/ detailContainerId /*Object, optional*/ eventChain

Available js api on widget/eventWidget (see all js API here)

• gwSetValue(/*Object*/ value, /*Object, optional*/ eventChain)
• gwGetValue()
• gwSetReadonly(/*Boolean*/ readonly, /*Object, optional*/ eventChain)
• gwGetReadonly()
• gwSetRequired(/*Boolean*/ required, /*Object, optional*/ eventChain)
• gwGetRequired()
• gwSetDisabled(/*Boolean*/ disabled, /*Object, optional*/ eventChain)
• gwGetDisabled()
• gwSetHidden(/*Boolean*/ hidden, /*Object, optional*/ eventChain)
• gwGetHidden()
• gwIsHidden()
• gwHide(/*Object, optional*/ eventChain)
• gwShow(/*Object, optional*/ eventChain)
• gwToggleHidden(/*Object, optional*/ eventChain)

Available js api on detailContainer (see all js API here):

• setFormValues(/*Object*/ mapWithNameAsKey)
• getFormValues(/*Boolean, optional*/ onlyModified)
• getFormValuesToShow(/*Boolean, optional*/ onlyModified)
• getGwWidget(/*Object, done so {name: \'att_name\'} or so {gwid: 123}*/ params)

This applies only in eventHandler for gwWidget events: Parameter 'eventChain' is useful to prevent cycles in event handler functions configured by configurator user. To allow the system to perform all needed checks, this parameter had to be propagated when using the use js gwWidget shared API. It should to be provided to API function that support it every time gwWidget API js function are used inside an event handler function. In all event handler functions parameter 'eventChain' should be always available as incoming argument. When a cycle is discovered a warning is logged in console e the cycle is stopped. Sometime configurator user could intentionally create cycles the bond more than one widget one to each other: this is an allowed configuration.

Example of allowed and handled cycles (Letters 'A', 'B', .. symbolize gwWidgets, '⇒' symbolizes an event handler bondind somehow them):

1. A ⇒ B and B ⇒ A

1. A ⇒ C and C ⇒ D and D ⇒ A

1. A ⇒ E and E ⇒ F and G ⇒ H and H ⇒ A

Note that all the 3 cycle example above can to be configured at the same time and are handled each one separately from the others. This means that when the cycle 1 is releaved and stopped, cycle 2 and 3 continues to run until it return wo widget A.

If gwWidget js API are used outside eventHandler for gwWidget events, 'eventChain' cannot to be pass, but it will be generated internally and passed automatically to all the eventually configured event handlers (that should be written in aim to propagate the event chain!!)

All js API are added to very gwAttribute dojo widget (marked with class 'gwAttributeId_*', see below) in an automatic and centralized way Every gwAttribute widget can customize each function following it's needs.

All gwSet*() function must publish, depending on the *, a specific topic:

function topic:

• .gwSetValue() 'gwClassDetail/gwset/value'
• .gwSetHidden() 'gwClassDetail/gwset/hidden' and 'gwClassDetail/changed/hidden'
• .gwSetReadonly() 'gwClassDetail/gwset/readonly' and 'gwClassDetail/changed/readonly'
• .gwSetRequired() 'gwClassDetail/gwset/required' and 'gwClassDetail/changed/required'
• .gwSetDisabled() 'gwClassDetail/gwset/disabled' and 'gwClassDetail/changed/disabled'

.gwSetValue() publish only 'gwClassDetail/gwset/value' because the 'gwClassDetail/changed/value' is published after the onChange(). onChange() is a hook function exposed by all dojo widget that somehow holds a value, and it's automatically called on every change of value Geoweb by default, if a onChange() function exist, tries to use dojo aspect after to hook the code that makes the 'gwClassDetail/changed/value' published.

All publish are fired with an object passed as argument done like this, that will be available as incoming parameters in all subscriptor's callbacks.

 var params = {
	 gwClassName: detailContainer.gwClassName,
 	itemId: detailContainer.itemId,
 	detailContainer: detailContainer,
 	detailContainerId: detailContainerId,
 	data: detailContainer._gwClassDetail_data,
 	gwAttributeName: this.gwAttributeName,
 	gwAttributeGwid: this.gwAttributeGwid,
 	eventGwWidget: this,
 	value: value, //or hidden: hidden, etc..
 	eventChain: eventChain
 };

If a particular function has no meaning for the particular gwWidget, or it had not been deliberately implemented, developer user should however to override the function using the correspondent pattern below. This in aim to notify configuration user that he is eventually using an API function with no meaning for the specific gwWidget (or deliberately not yet implemented).

 gwGetValue: function(){
 	console.log((this._gwWidgetType ? this._gwWidgetType : 'gwWidget')+' - gwGetReadonly()');
 
 	console.error('gwGetValue() function not implemented for '+this._gwWidgetType+': \'value\' parameter has no meaning for this widget');
 },
 gwSetValue: function(/*Object*/ value, /*Object, optional*/ eventChain){
 	console.log((this._gwWidgetType ? this._gwWidgetType : 'gwWidget')+' - gwSetRequired()');
 
 	console.error('gwSetValue() function not implemented for '+this._gwWidgetType+': \'value\' parameter has no meaning for this widget');
 },
 gwGetReadonly: function(){
 	console.log((this._gwWidgetType ? this._gwWidgetType : 'gwWidget')+' - gwGetReadonly()');
 
 	console.error('gwGetReadonly() function not implemented for '+this._gwWidgetType+': \'readonly\' parameter has no meaning for this widget');
 },
 gwSetReadonly: function(/*Boolean*/ readonly, /*Object, optional*/ eventChain){
 	console.log((this._gwWidgetType ? this._gwWidgetType : 'gwWidget')+' - gwSetRequired()');
 
 	console.error('gwSetReadonly() function not implemented for '+this._gwWidgetType+': \'readonly\' parameter has no meaning for this widget');
 },
 gwGetRequired: function(){
 	console.log((this._gwWidgetType ? this._gwWidgetType : 'gwWidget')+' - gwGetRequired()');
 
 	console.error('gwGetRequired() function not implemented for '+this._gwWidgetType+': \'required\' parameter has no meaning for this widget');
 },
 gwSetRequired: function(/*Boolean*/ required, /*Object, optional*/ eventChain){
 	console.log((this._gwWidgetType ? this._gwWidgetType : 'gwWidget')+' - gwSetRequired()');
 
 	console.error('gwSetRequired() function not implemented for '+this._gwWidgetType+': \'required\' parameter has no meaning for this widget');
 },
 gwGetDisabled: function(){
 	console.log((this._gwWidgetType ? this._gwWidgetType : 'gwWidget')+' - gwGetDisabled');
 
 	console.error('gwGetDisabled() function not implemented for '+this._gwWidgetType+': \'disabled\' parameter has no meaning for this widget');
 },
 gwSetDisabled: function(/*Boolean*/ disabled, /*Object, optional*/ eventChain){
 	console.log((this._gwWidgetType ? this._gwWidgetType : 'gwWidget')+' - gwSetDisabled()');
 
 	console.error('gwSetDisabled() function not implemented for '+this._gwWidgetType+': \'diabled\' parameter has no meaning for this widget');
 },

In general the following js API should not be overridden directly, because are always automatically added and they leverage on the implementation of .gwGetHidden() and .gwSetHidden() functions (custom or the default one).

• .gwIsHidden()
• .gwHide(/*Object, optional*/ eventChain)
• .gwShow(/*Object, optional*/ eventChain)
• .gwToggleHidden(/*Object, optional*/ eventChain)

• gwAttributeId_[gwid] The [gwid] section had to be dynamically populated, and it's the gwAttribute gwid. It is used for logic purpose: in the inner mechanism of js detailContainer API function .getGwWidgets(..). It works in conjuntion with css class 'gwAttributeWidget'. All the gwWdgets that hold shared functions are marked with css class and not with custom html tag attribute, because tags, in general, are not preserved by dojo when building the widget domNode form declarative text (id and class tags excluded) [Even the 'name' html attribute it's somehow preserved, during dojo build process, but may change it's position (typically inner and hidden) In that case, the relevant thing it's that name=“attributeGwid” is already used by method that retrieves gwClassDetail form values (and only for attribute in edit!]
• gwAttributeLabel Used to recognize the main dom node that contains the widget's 'label' section. Is used by the js API function that handles the visibility ('hidden' property) of the widget. For some gwWidget may not be provided a dom node with that css class (Grid style gwWidget in general, and all other with coolspan=“2”)
• gwAttributeWidget Used to recognize the main dom node that contains the widget's content section (sibling of the 'label', if existing). Is used by the js API function that handles the visibility ('hidden' property) of the widget. In a tipical simple widget it can to be set to the same dom node that holds gwAttributeId_[gwid] css class. In other complex (structured) widgets, it should be generally set only in the outer widget (typically a layout dojo widget), using the gwAttributeId_[gwid] css class in an inner (typically input) widget
• gwEditable Must be used in edit version jsp widget (if the edit and visualization .jsp file are the same, it had to be dynamically added or not). It is used for logic purpose: in the inner mechanism of js detailContainer API function .getGwWidgets(..) that, by default, return only widgets of gwClassDetail in 'edit' mode, and for this reason it looks for css class 'gwEditable'. All the gwWdgets that hold shared functions are marked with css class and not with custom html tag attribute, because tags, in general, are not preserved by dojo when building the widget domNode form declarative text (id and class tags excluded) [Even the 'name' html attribute it's somehow preserved, during dojo build process, but may change it's position (typically inner and hidden) In that case, the relevant thing it's that name=“attributeGwid” is already used by method that retrieves gwClassDetail form values (and only for attribute in edit!]
• gwNotEditable Should be used in 'visualization' version jsp widget (if the edit and visualization .jsp file are the same, it had to be dynamically added or not). It's not actually used, but is important to use it where appropriate, in aim to make in future logics upon it.
• gwWidget Used for styling purpose (linked to some css rules). Use it in gwWidget inner parts, that are input or will to become input after dojo build (Textbox, Select, Combo, etc..)
• gwWidgetEdit Used for styling purpose (linked to some css rules). Use it in gwWidget inner parts, that are input or will to become input after dojo build (Textbox, Select, Combo, etc..)
• gwWidgetVisualize Used for styling purpose (linked to some css rules). Use it in gwWidget inner parts, that are input or will to become input after dojo build (Textbox, Select, Combo, etc..)
• displayNone This predefined rule, existing in Geoweb commons .css, set the style=“display: none;” at the targeted domNode. Should to be dynamically added when necessary. This should to be done checking if the widget starts with property 'hidden' at true. This check is typically done in this way: ${not empty param.attributeIsHidden and param.attributeIsHidden ? 'displayNone' : ''}. Is important to populate correctly this css class, because on this all js shared API that modify directly or indirectly the gwAttribtue 'hidden' property, make leverage on it

Every gwAttribute dojo widget should provide this properties:

//ALWAYS
_gwWidgetType: 'widgetBaseWidget',
gwAttributeName: '${attributeList[param.index].name}',
gwAttributeGwid: ${attributeList[param.index].gwid},
_gwEventChain: [], //used internally to temporally pass eventChain parameter in the time intercurring between 'gwClassDetail/gwset/value' publish and 'gwClassDetail/changed/value' publish
 
...
 
//EVENTUALLY
//some custom implementation of function of the shared API (gwGetValue(), gwSetValue(), gwGetReadonly(), etc...)
gwGetValue: function(){
	...
},
...
 
//ALWAYS, or an alternative way to make the 'gwClassDetail/gwAttributeReady' publish
startup: function(){
	console.log((this._gwWidgetType ? this._gwWidgetType : 'gwWidget')+' - startup()');
 
	...
 
 	//XXX
	//IMPORTANT: the next publish must be done in all widget's startup()
 	var detailContainerId = '${detailContainerId}';
 	var gwClassName = '${currentClass.className}';
 	var itemId = '${itemId}';
 	var attributeGwid = '${attributeList[param.index].gwid}';
 	var formManagerId = '${param.formManagerId}';
 	var params = {
 		detailContainerId: detailContainerId,
 		gwClassName: gwClassName,
 		itemId: itemId,
 		attributeGwid: attributeGwid,
 		formManagerId: formManagerId
 	};
	topic.publish('gwClassDetail/gwAttributeReady', params);
 }

For now the convention is to implement the properties marked as ALWAYS in both 'edit' and 'visualization' gwWidget jsp implementation Even the 'gwClassDetail/gwAttributeReady' must be implemented in both. The js API are actually only implemented in 'edit' jsp, because only these jsp are inside a dynamic layout context. If a gwSet*() generic function is overridden the important thing is to publish the related event (see above).