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 shapes,
frames and 3D; slides and master slides may hold office:forms). 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>
…
<draw:control draw:control="control1" svg:x="2cm" svg:y="5cm"
svg:width="5cm" svg:height="0.6cm"/>Here office:forms is a child of the draw:page, and
the draw:control shape on the same slide shows the control.
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.