A form holds user-interface controls: text fields, buttons, check boxes, lists. In
ODF the controls live in office:forms, apart from the text; each visible
control is shown by a draw:control shape that refers to it by ID and
gives its position (see frames,
images and objects). Forms may nest, are not part of the text flow, and may be
data-aware: their controls then show and update one row at a time of a database
result set. Submission and data-source behaviour is defined only for
form:form, not for XForms models. This page covers chapter 13 of
OpenDocument 1.3 part 3 and the form: attributes of chapter 19.
office:forms and form:form
office:forms holds form:form and
xforms:model elements. Its attributes:
form:apply-design-mode (default true: forms open in design
mode, editable; false: ready to fill in) and
form:automatic-focus (default false; true:
put the focus in a control on loading; which one is not defined). An
xforms:model is an XForms 1.0 model (§3.3.1 of XForms); controls bind to
it with xforms:bind.
| Attribute of form:form | Values | Meaning |
|---|---|---|
form:name | text | The form’s name. |
xlink:href, xlink:type, xlink:actuate | IRI | Where the form is submitted. |
form:method | get (default), post or another string, any case | HTTP method. |
form:enctype | media type, default application/x-www-form-urlencoded | Content type for post. |
office:target-frame | _blank (default), _parent, _self, _top, or a frame name | Where the result is shown. |
form:datasource | IRI or data source name | Database connection, a registered data source name, or an ODF database front-end document (.odb). |
form:command-type | command (default), query, table | form:command is an SQL statement, a stored query’s name, or a table name (all rows). |
form:command | text | The command. |
form:escape-processing | true (default), false | For SQL commands: whether the program processes the command before passing it to the driver. |
form:filter, form:apply-filter | text; boolean (default false) | An extra WHERE condition, ANDed with any in the command, used only when form:apply-filter is true. |
form:order | text | Sort order. |
form:allow-inserts, form:allow-updates, form:allow-deletes | boolean, default true | Whether records may be added, changed or deleted. |
form:ignore-result | boolean, default false | true: discard what the query returns; the form only inserts new data. |
form:master-fields, form:detail-fields | comma-separated column names | For a sub-form: the parent form’s columns and this form’s matching parameters; the sub-form queries again each time the parent moves to another row. |
form:navigation-mode | none, current, parent | No navigation bar (Tab only); a bar that moves this form; a bar that moves the parent form. |
form:tab-cycle | records, current, page | Tab from the last control: to the first control and the next record; to the first control, same record; to the next form. |
form:control-implementation | text | A preferred implementation; a reader that does not have it uses its own. |
Children: the controls, nested form:forms,
form:connection-resource, form:properties and
office:event-listeners.
Controls
Every control has a name (not necessarily unique), and may hold
form:properties (implementation-defined properties) and
office:event-listeners.
| Element | Control | Attributes besides the common ones |
|---|---|---|
form:text | One-line text input. | form:value, form:current-value, form:max-length, form:readonly, form:data-field, form:convert-empty-to-null, form:linked-cell |
form:textarea | Multi-line text; plain text in form:current-value or formatted text as text:p children (if both, which is used is up to the program). | as form:text |
form:password | Password input. | form:echo-char (default *), form:value, form:max-length, form:convert-empty-to-null, form:linked-cell |
form:file | File picker. | form:value, form:current-value, form:max-length, form:readonly, form:linked-cell |
form:formatted-text | Text in the format of the data style on the control’s shape. | value attributes, form:min-value, form:max-value (strings), form:validation, form:spin-button, form:repeat, form:delay-for-repeat, data and cell links |
form:number | Number input. | as formatted text, with numeric min, max and value |
form:date | Date input. | as formatted text, with date min, max and value |
form:time | Time input. | as formatted text, with time min, max and value |
form:fixed-text | A label; one per control. | form:label, form:for (IDs of the controls it labels), form:multi-line |
form:combobox | Editable text with a list; items are form:item (text content, form:label). | form:auto-complete, form:dropdown, form:size, form:list-source, form:list-source-type, form:source-cell-range, text attributes |
form:listbox | Pick one or more items; items are form:option (form:label, form:value, form:selected, form:current-selected). | form:multiple, form:dropdown, form:size, form:bound-column, form:list-source, form:list-source-type, form:list-linkage-type, form:source-cell-range, form:xforms-list-source, form:data-field, form:linked-cell |
form:button | Button. | form:button-type, form:label, form:value (boolean), form:default-button, form:toggle, form:focus-on-click, form:image-data, form:image-align, form:image-position, form:repeat, form:delay-for-repeat, xlink:href, office:target-frame, form:xforms-submission |
form:image | Image button (of any button type, unlike HTML 4.01). | form:button-type, form:image-data, form:value, xlink:href, office:target-frame |
form:checkbox | On/off box; on when form:current-state is checked. | form:state, form:current-state, form:is-tristate, form:label, form:value, form:visual-effect, form:image-align, form:image-position, data and cell links |
form:radio | Option button; buttons with the same form:name form a group, only one on. Bound to a field, the chosen button’s value is written to it. | form:selected (only one per group true), form:current-selected, form:label, form:value, form:visual-effect, image placement, data and cell links |
form:frame | A frame grouping controls. | form:label, form:for |
form:image-frame | Shows an image. | form:image-data, form:readonly, form:data-field |
form:hidden | No visible part; its value is submitted. | form:value |
form:grid | Table of data; one form:column per column, each holding one text, textarea, number, date, time, formatted-text, combo box, list box or check box control. | –; columns take form:name, form:label, form:text-style-name (paragraph style for the column, which may name a data style) |
form:value-range | Pick a value from a number range. | form:min-value, form:max-value, form:value, form:step-size (default 1), form:page-step-size, form:orientation (horizontal, vertical), form:repeat, form:delay-for-repeat, form:linked-cell |
form:generic-control | Placeholder for an implementation-defined control. | – |
Common attributes (on most controls): form:name,
xml:id (with deprecated form:id, which must equal it),
form:control-implementation, form:disabled,
form:printable (default true), form:tab-index,
form:tab-stop (default true), form:title
(extra information, such as a tooltip) and xforms:bind.
Control attribute values
| Attribute | Values | Meaning |
|---|---|---|
form:value | by control: boolean (button), date, number (number, value range), time, string (others) | The default value. |
form:current-value | string, date, double (number) or time | The current value; overrides form:value. |
form:min-value, form:max-value | date, string (formatted text), double (number, value range) or time | Limits. |
form:max-length | integer | Most characters the user may type. |
form:disabled | boolean, default false | A disabled control takes no input, cannot get focus and is skipped by Tab. (The standard’s value list has true and false the wrong way round.) |
form:readonly | boolean, default false | The user may not change the value; still in the Tab order. (Value list reversed in the standard too.) |
form:tab-index | integer, default 0 | Tab order: lowest non-zero first, equal values in document order, then the controls with 0 or none; disabled controls skipped. |
form:data-field | column name | The result-set column the control shows; changes are written back (perhaps only when focus leaves). |
form:convert-empty-to-null | boolean, default false | Store an empty entry as NULL. |
form:linked-cell | cell address or named range | A spreadsheet cell kept equal to the control (first cell of a range; a name wins over an address). |
form:button-type | push (default), submit, reset, url | No action (scripts only); submit the form; reset every control; open xlink:href. |
form:default-button | boolean, default false | Pressing Return in an input does what this button does. |
form:toggle | boolean, default false | A toggle button (pressed / not pressed) instead of a push button. |
form:image-align | start, center (default), end | Alignment of image and text. |
form:image-position | start, end, top, bottom, center (default) | Image before, after, above or below the text, or centred. |
form:image-data | IRI | The image file. |
form:state | unchecked (default), checked, unknown | Initial state of a check box (unknown only if tristate). |
form:current-state | checked, unchecked, unknown | Current state; a checked box’s value is submitted. |
form:is-tristate | boolean, default false | Allow the third state. |
form:visual-effect | flat, 3d | Look of the box. |
form:spin-button | boolean, default false | Show up/down buttons. |
form:repeat, form:delay-for-repeat | boolean; duration, default PT0.050S | Repeat the action while held, after this delay. |
form:validation | boolean, default false | Check input against the format while typing. |
form:auto-complete | boolean | Complete typed text from a matching list item. |
form:dropdown | boolean, default false | true: list always shown; false: shown when the button is clicked. |
form:size | integer | Visible list rows. |
form:multiple | boolean, default false | Several items may be chosen. |
form:list-source-type | table, query, sql, sql-pass-through, table-fields, value-list | Where list entries come from: first column of all rows of a table (SELECT * FROM), of a stored query, of an SQL statement (passed to the driver unchanged for pass-through, or a query with escape processing off); the column names of a table; or the form:values of the form:option children (list boxes only, form:list-source ignored). |
form:list-source | text | The table, query or SQL, resolved against the form’s data source. |
form:bound-column | column | Which column of the list result fills the data field. |
form:list-linkage-type | selection, selection-indices | With a linked cell: the selected text, or its 1-based index, is written to the cell, and changing the cell changes the selection. |
form:source-cell-range | cell range or range name | A spreadsheet range whose (left-most) column fills the list and follows changes. |
form:xforms-list-source | bind reference | One list entry per node of an XForms bind. |
form:xforms-submission | ID | On a button: the xforms:submission to perform. |
xforms:bind | ID | On buttons: an XForms submission; on other controls: the xforms:bind element the control reads and writes. |
Form events
Besides the DOM events (see comments,
events and DDE), forms and controls may use these script:event-name
values:
| Event | On | When |
|---|---|---|
form:approveaction, form:performaction | button, image | Before the action (may veto it); when it is performed (“pressing the button”). |
form:textchange | text controls | The user changes the text. |
form:itemstatechange | check box, radio | The state changes. |
form:mousedrag | all controls | The mouse is dragged onto the control. |
form:approvereset | as for reset | Before a reset (may veto). |
form:approveupdate, form:update | data-bound controls | Before an update (may veto); when the value is committed. |
form:load, form:startreload, form:reload, form:startunload, form:unload | forms | Connecting to the data source; about to refresh, refreshed; about to drop, dropped. |
form:confirmdelete | forms | A record is about to be deleted. |
form:approverowchange, form:rowchange | forms | Before a row change (may veto); after it. |
form:approvecursormove, form:cursormove | forms | Before moving to another row (may veto); after. |
form:supplyparameter | forms | Parameters are needed to connect. |
form:error | forms, combo and list boxes | A database error. |
form:adjust | value range | The value was adjusted. |
Implementation properties
form:properties holds properties a program defines for itself:
form:property (a form:property-name, unique in the
element, an office:value-type and the value in the matching
office:value, office:string-value,
office:boolean-value, office:date-value,
office:time-value or office:currency) and
form:list-property (a name and value type, with
form:list-value children each holding one value).
<office:forms form:automatic-focus="false" form:apply-design-mode="false">
<form:form form:name="Form" form:command-type="table">
<form:text form:name="Name" xml:id="control1" form:max-length="40"/>
<form:checkbox form:name="Agree" xml:id="control2" form:label="I agree"
form:state="unchecked" form:value="yes"/>
</form:form>
</office:forms>
…
<text:p><draw:control draw:control="control1" text:anchor-type="as-char"
svg:width="5cm" svg:height="0.6cm"/></text:p>Source
OpenDocument Version 1.3, OASIS Standard, 27 April 2021, part 3 (schema), chapter 13 (including Table 9, form control events) and attributes 19.247–19.319, 19.384 and 19.910; read in full for this page. XForms itself is not described.