Re: ACTION-2275: Draft new text for <copy/>

First draft. Most of the changes go in to the top-level section 9.9.


==========================================

9.9 Selection Controls  (Some changes here)

There are two selection controls:
* select which allows the selection of zero or more values from a  
collection,
* select1 which allows for the selection of zero or one from the  
collection.

The collection of values to be selected from are provided either by a  
number of item elements, each of which supplies one value, or a single  
itemset element, which provides a sequence of values.

A selection control can be "simple" or "complex":
* a simple selection only selects simpleContent values (typically  
strings), in which case the item or itemset elements use a value child or  
attribute;
* a complex selection selects values consisting of complex types (with  
children nodes), and the item or itemset elements use a copy child or  
attribute.

If one item element has a copy attribute or child, all of them must, and  
the bound target of the containing selection control must be an element  
node, otherwise an xforms-binding-error event is dispatched to the  
containing selection control.

A simple selection can be either "open" or "closed", as indicated by the  
selection attribute: an open selection allows inclusion of values outside  
the collection given. A complex selection is always closed.

The items from the child or children of the selection control are  
evaluated, each being a pair of a label and a value.

The label for each pair must be made available to the user, with an  
indication of whether the item is selected or not.

Interaction with a label toggles the selected state. On selection, items  
receive the xforms-select event; on deselection, the xforms-deselect event.

A selection control is out-of-range if it is bound to data whose value for  
any reason is not in the list of possible values.

Typically, a style sheet is used to control the appearance of controls,  
though a means is provided to suggest an appearance through the appearance  
attribute. The value of the attribute consists of one of the following  
values:
* "full": all labels should be rendered at all times;
* "compact": a fixed number of labels should be rendered, with scrolling  
facilities as needed;
* "minimal": a minimum number of labels should be rendered, with a  
facility to temporarily render additional choices.

9.9.1 The select Element (No change)

[...]

All items whose values match a value in the bound instance data are  
initially selected; if a particular value in the bound data matches more  
than one item, at least one is selected, but it is not further defined  
which, nor how many. If there is no match, no items are initially  
selected. Items with an empty storage data subtree or a storage value that  
is either empty or contains only white space characters are never selected.

If the bound instance data contains values that do not match any item's  
value:
* for open selections, all such non-matching values are retained and made  
available to the user; since there are no associated labels, the value  
itself is used as the label;
* for closed selections, the control is out-of-range.

Any number of the items may be selected, including none.

For open selections, the control must also allow free data entry, as  
described in The input Element. The control must permit multiple values to  
be entered through free entry. The label of such an entered value is  
considered identical to the value itself.

Selected values are represented in the bound instance location:
* for simple selections as a space-separated list,
* for complex selections as copies of the subtrees of the selected values.

The content of the bound instance node must only be changed by the  
addition or deletion of storage data associated with items that have been  
selected or deselected; content not associated with selection items must  
be preserved.

For a simple selection, the net effect of newly selected and deselected  
items is computed into a string, preserving content not associated with  
selection items. For complex selections, the individual subtrees  
associated with the newly selected and deselected items are added or  
removed individually by using insert and delete; after which an update is  
done, followed by a refresh.

[...]

9.9.2 The select1 Element (No change)

[...]

Any item whose value matches the value of the bound instance data is  
initially selected; if more than one matches, at least one is selected,  
but it is not further defined which, nor how many of the matching items is  
selected. If there is no match, no item is initially selected. For both  
closed and open selections, any item with an empty storage data subtree or  
a storage value that is either empty or contains only white space  
characters is treated identically to any other value.

If the bound instance data is non-empty and does not match any item's  
value:
* for open selections, the non-matching value is retained and made  
available to the user; the value is also used as the label;
* for closed selections, the control is out-of-range;

Interaction with the label of an unselected item deselects any  
already-selected item and then selects the new item; interaction with the  
label of a selected item deselects that item.

For open selections, the control must also allow free data entry, as  
described in The input Element; entering a value selects that value after  
deselecting any already-selected value. The label of such an entered value  
is considered identical to the value itself.

The selected value is stored in the bound instance location, for complex  
selections as a copy of the subtree of the selected value.

9.9.4 The item Element (add copy as a child element and attribute)

[...]

Special Attributes:
copy
  Optional expression giving a value to be copied. Takes precedence over  
any copy child element.

Content: (value|copy), (UI Common)*

[...]

9.9.5.1 The copy Element (for item and itemset)

This element is similar to the value element, except that it works with  
subtrees of instance data rather than simple values.

Common Attributes: Common, Single Item Binding

Content: EMPTY

The storage value is obtained by evaluating the Single Item Binding.

Received on Wednesday, 11 March 2020 11:43:09 UTC