You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by st...@outerthought.org on 2004/03/03 23:00:06 UTC
[WIKI-UPDATE] WoodyBinding Wed Mar 3 23:00:05 2004
Page: http://wiki.cocoondev.org/Wiki.jsp?page=WoodyBinding , version: 32 on Tue Mar 3 21:15:14 2004 by JoergHeinicke
-
- The binding is configured using an XML file. This XML file contains elements in the __wb__ namesspace (Woody Binding):
? ^^ ^^
+ The binding is configured using an XML file. This XML file contains elements in the {{wb}} namesspace (Woody Binding):
? ^^ ^^
- The __id__ attribute identifies the [widget|WoodyWidgetReference].
? ^^ ^^
+ The {{id}} attribute identifies the [widget|WoodyWidgetReference].
? ^^ ^^
- The __path__ attribute is the address of the items in the target object (a Javabean or an XML document). The paths can be arbitrary JXPath expressions.
? ^^ ^^
+ The {{path}} attribute is the address of the items in the target object (a Javabean or an XML document). The paths can be arbitrary JXPath expressions.
? ^^ ^^
- [[Convention] Let's call all elements in the wb: namespace "binding elements". They all cause a binding-related action to be performed.
? ^
+ [[Convention] Let's call all elements in the {{wb}} namespace "binding elements". They all cause a binding-related action to be performed.
? ++ ^^
- The __wb:context__ element changes the [JXPath context|http://jakarta.apache.org/commons/jxpath/apidocs/org/apache/commons/jxpath/JXPathContext.html] to the specified path. The path expressions on the binding elements occuring inside the context element will then be evaluated in this context, thus relative to the path specified on the wb:context element.
? ^^ ^^
+ The {{wb:context}} element changes the [JXPath context|http://jakarta.apache.org/commons/jxpath/apidocs/org/apache/commons/jxpath/JXPathContext.html] to the specified path. The path expressions on the binding elements occuring inside the context element will then be evaluated in this context, thus relative to the path specified on the wb:context element.
? ^^ ^^
- The __wb:value__ element is used to bind the value of a widget.
? ^^ ^^
+ The {{wb:value}} element is used to bind the value of a widget.
? ^^ ^^
- |wb:repeater|binds repeater widgets|id, parent-path, row-path, unique-row-id (deprecated), unique-path (deprecated)| wd:convertor, wb:on-bind, wb:on-delete-row, wb:on-insert-row, wb:unique-row
+ |wb:repeater|binds repeater widgets|id, parent-path, row-path, unique-row-id (deprecated), unique-path (deprecated)| wd:convertor (deprecated), wb:on-bind, wb:on-delete-row, wb:on-insert-row, wb:unique-row
? +++++++++++++
+ |wb:unique-row|specifies unique fields for a repeater row|none|wb:unique-field
+ |wb:unique-field|specifies unique field for a repeater row|id, path|wd:convertor
- |wb:insert-node|insert a node in an XML document|src, xpath|piece of XML that should be inserted|
? -
+ |wb:insert-node|insert a node in an XML document|src, xpath|piece of XML that should be inserted
- |wb:insert-bean|inserts an object in a list-type bean property|classname, addmethod|
? ^
+ |wb:insert-bean|inserts an object in a list-type bean property|classname, addmethod|none
? ^^^^
- |wb:unique-field|specifies unique fields in a repeater row|id, path|wd:convertor
- ''NOTE: this setting replaces the @readonly attribute that was available only on selected bindings.''
? ^^ --
+ __NOTE__: this setting replaces the @readonly attribute that was available only on selected bindings.
? ^^ ++
- The wb:context element changes the JXPath context to the specified path. The path expressions on the binding elements occuring inside the context element will then be evaluated in this context, thus relative to the path specified on the wb:context element.
+ The {{wb:context}} element changes the JXPath context to the specified path. The path expressions on the binding elements occuring inside the context element will then be evaluated in this context, thus relative to the path specified on the {{wb:context}} element.
? ++ ++ ++ ++
- The wb:context element is usually used in two occasions. First of all, it is used as the root element of the binding file; because an XML file must always have one root element, and you will usually want to perform more than one binding action.
+ The {{wb:context}} element is usually used in two occasions. First of all, it is used as the root element of the binding file; because an XML file must always have one root element, and you will usually want to perform more than one binding action.
? ++ ++
- Secondly, you use wb:context if you need to address multiple items having a common base path. On the one hand, this saves you on typing and helps readability, and on the other hand, this improves the performance of the binding. To illustrate this with an example, instead of doing this:
+ Secondly, you use {{wb:context}} if you need to address multiple items having a common base path. On the one hand, this saves you on typing and helps readability, and on the other hand, this improves the performance of the binding. To illustrate this with an example, instead of doing this:
? ++ ++
- The wb:on-update element (which itself has no attributes), can contain one or more binding elements that will be executed if the value of the widget has changed, and thus if the object has been updated. For example, you could use the wb:set-attribute binding to set the value of an attribute "changed" to "true".
? ^ ^ ^ ^
+ The {{wb:on-update}} element (which itself has no attributes), can contain one or more binding elements that will be executed if the value of the widget has changed, and thus if the object has been updated. For example, you could use the {{wb:set-attribute}} binding to set the value of an attribute {{changed}} to {{true}}.
? ++ ++ ++ ++ ^^ ^^ ^^ ^^
- The wd:convertor element has the same purpose as the wd:convertor element in the form definition: it converts between objects (numbers, dates) and strings. This is mostly used when binding to XML documents. Suppose you have defined a certain widget in a form definition to have a "date" datatype, and you want to bind to an XML document which contains the date in the XML Schema date representation, then you could define a convertor as follows:
+ The {{wd:convertor}} element has the same purpose as the {{wd:convertor}} element in the form definition: it converts between objects (numbers, dates) and strings. This is mostly used when binding to XML documents. Suppose you have defined a certain widget in a form definition to have a "date" datatype, and you want to bind to an XML document which contains the date in the XML Schema date representation, then you could define a convertor as follows:
? ++ ++ ++ ++
- The datatype attribute on the wd:convertor element, which you don't have to specify in the form definition, identifies the datatype to which the convertor belongs.
+ The datatype attribute on the {{wd:convertor}} element, which you don't have to specify in the form definition, identifies the datatype to which the convertor belongs.
? ++ ++
-
- ''Note: the @readonly attribute supported in early versions of this binding has been replaced by the @direction attribute as supported now on all binding elements. ''
-
- The wb:aggregate element is used to bind aggregatefields. Remember that aggregatefields are a special type of widget that groups multiple field widgets and lets the user edit their values in one textbox, splitting the values out to the different widgets on submit based on a regexp.
+ The {{wb:aggregate}} element is used to bind aggregatefields. Remember that aggregatefields are a special type of widget that groups multiple field widgets and lets the user edit their values in one textbox, splitting the values out to the different widgets on submit based on a regexp.
? ++ ++
- The wb:aggregate binding allows to bind the values of the individual field widgets out of which an aggregatefield widget consists. The bindings for these field widgets are specified by the wb:value child elements.
+ The {{wb:aggregate}} binding allows to bind the values of the individual field widgets out of which an aggregatefield widget consists. The bindings for these field widgets are specified by the {{wb:value}} child elements.
? ++ ++ ++ ++
- * wd:convertor
+ * wb:unique-row
+ * wd:convertor (deprecated)
- __NOTE:__ The {{unique-row-id}} and {{unique-path}} are deprecated in favor of __<wb:unique-row>__ child element.
+ __NOTE__: The attributes {{unique-row-id}} and {{unique-path}} and the child element {{wd:convertor}} are deprecated in favor of {{<wb:unique-row>}}.
- The __wb:repeater__ binding binds repeaters based on the concept that each row in the repeater should contain a widget containing a unique identification for that row. This unique identification is necessary to know which rows in the repeater correspond to which objects in the target collection. Newly added rows in the repeater can (but should not) have a null value for this identification widget. This identification field will typically not be editable, so in most cases it will be an output widget.
+ The {{wb:repeater}} binding binds repeaters based on the concept that each row in the repeater is identified by one or more widgets uniquely. This unique identification is necessary to know which rows in the repeater correspond to which objects in the target collection. Newly added rows in the repeater can (but should not) have a null value for this identification widget(s). Typically this/these widget(s) will not editable, so in most cases it will be an output widget. If you don't need the identification widget(s) at the client you don't need to add them to the template at all! You only have to specify {{direction="load"}} to this/these widget(s) then. This prevents the database IDs from getting to the client.
- The __id__ attribute should contain the id of the repeater. The nested wd:converter element can be used to specify the convertor to use in case the id value from the model to bind is a String (typical for XML documents) while the widget inside the repeater has another type.
+ The {{id}} attribute should contain the id of the repeater.
- The __unique-row-id__ attribute specifies the id of the widget appearing on each repeater row that contains the unique identification for that row. The __unique-path__ attribute contains the corresponding path in the object model. __Both attributes are deprecated__. Instead use __<wb:unique-row>__ child element.
? ^^ ^^ ^^ ^^ -----------------------------------------------------------------------------------
+ The {{unique-row-id}} attribute specifies the id of the widget appearing on each repeater row that contains the unique identification for that row. The {{unique-path}} attribute contains the corresponding path in the object model.
? ^^ ^^ ^^ ^^
+ __NOTE__: Both attributes are deprecated. Please use {{<wb:unique-row>}} instead.
+
- The __parent-path__ and __row-path__ attributes can best be understood when described differently for XML documents and Javabeans.
? ^^ ^^ ^^ ^^
+ The {{parent-path}} and {{row-path}} attributes can best be understood when described differently for XML documents and Javabeans.
? ^^ ^^ ^^ ^^
- A childelement __wd:convertor__ can be used to specify the convertor to use in case the unique-id from the model is a String and the matching widget inside the repeater has a different type.
? ^^ ^^
+ A child element {{wd:convertor}} can be used to specify the convertor to use in case the unique-id from the model is a String (typical for XML documents) and the matching widget inside the repeater has a different type.
? + ^^ ^^ ++++++++++++++++++++++++++++
- The three remaining childelements wb:on-bind, wb:on-delete-row, wb:on-insert-row should contain the binding elements that have to be executed in case of these three events.
+ __NOTE__: This element is deprecated at that place as it is only used in combination with the deprecated attributes {{unique-row-id}} and {{unique-path}}. Please use {{<wb:unique-row>}} instead.
- The children of the __wb:on-bind__ element are executed when an existing repeater row is updated, or after inserting a new row. The JXPath context is automatically changed to match the current row.
+ The three remaining child elements {{wb:on-bind}}, {{wb:on-delete-row}}, {{wb:on-insert-row}} should contain the binding elements that have to be executed in case of these three events.
- The children of the __wb:on-delete-row__ element are executed when a repeater row has been deleted. If you want to delete the row, then put a __<wb:delete-node/>__ in there. Alternatively, you could also use the __wb:set-attribute__ binding to set e.g. an attribute "status" to "deleted".
+ The children of the {{wb:on-bind}} element are executed when an existing repeater row is updated, or after inserting a new row. The JXPath context is automatically changed to match the current row.
- The children of the __wb:on-insert-row__ are executed in case a new row has been added to the repeater. Typically this will contain a __wb:insert-node__ or a __wb:insert-bean binding__ (see the descriptions of these binding elements for more details).
+ The children of the {{wb:on-delete-row}} element are executed when a repeater row has been deleted. If you want to delete the row, then put a {{<wb:delete-node/>}} in there. Alternatively, you could also use the {{wb:set-attribute}} binding to set e.g. an attribute {{status}} to {{deleted}}.
- The childrens of the __wb:unique-row__ specifies the widgets appearing on each repeater row whose values are the unique identification of that row. Each __<wb:unique-field>__ child specifies one widget.
+ The children of the {{wb:on-insert-row}} are executed in case a new row has been added to the repeater. Typically this will contain a {{wb:insert-node}} or a {{wb:insert-bean binding}} (see the descriptions of these binding elements for more details).
+ The childrens of the {{wb:unique-row}} specify the widgets appearing on each repeater row for the unique identification of that row. Each {{<wb:unique-field>}} child specifies one widget.
+
+ !!wb:unique-row
+ ''Child elements:''
+ * wb:unique-field
+
+ The {{<wb:unique-row>}} is just a container for the child elements specifying the bindings of the identification widgets.
+
+ !!wb:unique-field
+ ''Attributes:''
+ * id
+ * path
+ * direction (optional)
+
+ ''Child elements:''
+ * wd:convertor (note the wd: namespace!) (optional)
+
+ This unique-field element references a field widget that is part of the {{<wb:unique-row>}} child element of a {{<wb:repeater>}}. The {{id}} and {{path}} attributes have the same meaning as in {{<wb:value>}}.
+
+ The {{wd:convertor}} element has the same purpose as the {{wd:convertor}} element in the form definition: it converts between objects (numbers, dates) and strings. Is used when binding from XML documents to read the data in the appropiate format. For more info see the description of this element in {{<wb:value>}}.
+
+ ''Note:'' This binding is only active in the 'load' operation, so specifying the {{direction="save"}} is meaningless.
- ''Note:'' This binding is never active in the 'load' operation, so there is no need to specify the direction="save" to protect you model from being changed during load.
? -
+ ''Note:'' This binding is never active in the 'load' operation, so there is no need to specify the {{direction="save"}} to protect you model from being changed during load.
? ++ ++
- ''Note:'' This binding is never active in the 'load' operation, so there is no need to specify the direction="save" to protect you model from being changed during load.
+ ''Note:'' This binding is never active in the 'load' operation, so there is no need to specify the {{direction="save"}} to protect you model from being changed during load.
? ++ ++
- It inserts the content of the wb:insert-node element as child of the current context element, or, if a src attribute is specified, retrieves the XML from the specified source and inserts that as child of the current context element. In this last case, you can also supply an xpath attribute to select a specific element from the retrieved source.
+ It inserts the content of the {{wb:insert-node}} element as child of the current context element, or, if a src attribute is specified, retrieves the XML from the specified source and inserts that as child of the current context element. In this last case, you can also supply an xpath attribute to select a specific element from the retrieved source.
? ++ ++
- ''Note:'' This binding is never active in the 'load' operation, so there is no need to specify the direction="save" to protect you model from being changed during load.
+ ''Note:'' This binding is never active in the 'load' operation, so there is no need to specify the {{direction="save"}} to protect you model from being changed during load.
? ++ ++
- ''Note:'' This binding is never active in the 'load' operation, so there is no need to specify the direction="save" to protect you model from being changed during load.
+ ''Note:'' This binding is never active in the 'load' operation, so there is no need to specify the {{direction="save"}} to protect you model from being changed during load.
? ++ ++
-
- !!wb:unique-field
- ''Attributes:''
- * id
- * path
- * direction (optional)
-
- ''Child elements:''
- * wd:convertor (note the wd: namespace!) (optional)
-
- This unique-field element references a field widget that is part of the <wb:unique-row> child element of a <wb:repeater>. The __id__ nad __path__ attributes have the same meaning as in <wb:value>.
-
- The __wd:convertor__ element has the same purpose as the wd:convertor element in the form definition: it converts between objects (numbers, dates) and strings. Is used when binding from XML documents to read the data in the appropiate format. For more info see the description of this element in <wb:value>.
-
- ''Note:'' This binding is only active on 'load' operation, so there specify {{ attribute="save"}} is meanless.
- This example is rather trivial and could be replaced by a simple <wb:value>, but
+ This example is rather trivial and could be replaced by a simple {{<wb:value>}}, but it shows the available variables in the script:
? ++ ++ ++++++++++++++++++++++++++++++++++++++++++++++++
- it shows the available variables in the script:
- * {{widget}}: the widget identified by the "id" attribute,
? ^ ^
+ * {{widget}}: the widget identified by the {{id}} attribute,
? ^^ ^^
- * {{jxpathPointer}}: the JXPath pointer corresponding to the "path" attribute,
? ^ ^
+ * {{jxpathPointer}}: the JXPath pointer corresponding to the {{path}} attribute,
? ^^ ^^
- * {{jxpathContext}} (not shown): the JXPath context corresponding to the "path" attribute
? ^ ^
+ * {{jxpathContext}} (not shown): the JXPath context corresponding to the {{path}} attribute
? ^^ ^^
- ''Notes:''
+ __Notes__:
- * The <wb:save-form> snippet should be ommitted if the "direction" attribute is set to "load".
? ^ ^ ^ ^
+ * The {{<wb:save-form>}} snippet should be ommitted if the {{direction}} attribute is set to {{load}}.
? ++ ++ ^^ ^^ ^^ ^^
- * The <wb:load-form> snippet should be ommitted if the "direction" attribute is set to "save".
? ^ ^ ^ ^
+ * The {{<wb:load-form>}} snippet should be ommitted if the {{direction}} attribute is set to {{save}}.
? ++ ++ ^^ ^^ ^^ ^^
- * The @readonly attribute supported in early versions of this binding has been replaced by the @direction attribute as supported now on all binding elements. ''
? ---
+ * The {{@readonly}} attribute supported in early versions of this binding has been replaced by the {{@direction}} attribute as supported now on all binding elements.
? ++ ++ ++ ++
-
+ * The attributes {{unique-row-id}} and {{unique-path}} and the child element of a {{<wb:repeater>}} are deprecated in favor of a new element {{<wb:unique-row>}} and its childs.