7. Surface

Contents of DESL 0.1

7.1 Overview

surface says how the model is laid out for the user, by naming which types and attributes of the metamodel play which part. It names no designer type of its own; a host's component for a kind serves all designer types of that kind.

Property	Type	Description
`kind`	`"table"`	Required. The layout. DESL 0.1 defines one kind.

The rest of this section defines the table kind.

7.2 The table

A table shows the elements of one type as rows, the elements of another type as columns, and at each crossing one cell that holds the row's value for that column. A table has views, elements that store how it is shown: which columns, in which order and width, sorted, filtered and grouped how.

Property	Type	Description
`columns`	Columns	Required. The type whose elements are the columns (7.3).
`rows`	`{ type }`	Required. The type whose elements are the rows, in document order unless a view sorts them.
`cells`	Cells	Required. The type whose elements are the cells (7.3).
`views`	Views	Required. The type whose elements are the views, and the types of their settings (7.4).
`valueTypes`	map SimpleId → ValueType	Required. One entry per value type a column may have (7.5).

7.3 Columns and cells

Columns property	Type	Description
`type`	TypeRef	Required. The columns' element type. Document order is column order.
`name`	attribute	Required. The attribute that names a column.
`valueType`	attribute	Required. The attribute whose value, a key of `valueTypes`, is the column's value type.
`title`	attribute	The boolean attribute that marks the one column that titles a row.
`options`	`{ type, name, colour }`	The element type contained in a column that lists the values a choice may take, with the attributes that name and colour one.
`parent`	attribute	The boolean attribute that marks a column whose values are the row's parent within the same document, for nesting.

Cells property	Type	Description
`type`	TypeRef	Required. The cells' element type, contained in a row.
`column`	attribute	Required. The reference attribute that names the cell's column.
`items`	TypeRef	The element type contained in a cell that holds one of several values.

A row has at most one cell per column. A row without a cell for a column has no value for it, which is shown empty. A cell MUST NOT carry an id of its own beyond what its row and column give it.

7.4 Views

Views property	Type	Description
`type`	TypeRef	Required. The views' element type. Document order is the order of the view tabs.
`name`	attribute	Required.
`active`	attribute	An attribute of the document (`metamodel.document`) naming the view the document was last left in; absent, the first view.
`settings`	map role → TypeRef	The element types contained in a view that store its settings, by role: `columns` (a column's visibility, width and wrap), `sorts`, `conditions`, `filterGroups` and `groups` (the order, hidden state and collapsed state of a group).

A table MUST always have at least one view. A view stores only what differs from the default: a column with no settings is visible, at the default width, after the columns that have settings, in column order.

7.5 Value types

A value type says what a column's cells hold and how the surface treats it:

Property	Type	Description
`label`	LocalizedText	Required.
`key`	attribute	Required. The attribute of the cells' type that holds the value or, with `many`, of the items' type that holds one value. A cell holds its value under the key of its column's type, so a value that does not fit its column's type is still readable and is reported, never discarded.
`many`	bool	The cell holds any number of values as items (7.3). Default false.
`editor`	`text`, `number`, `checkbox`, `date`, `dateTime`, `time`, `choice`, `choices`, `rows`	Required. The editor a host opens over a cell: free text, a number, a checkbox, a date, a date and time, a time, one option, several options, or rows of a document, searched by title.
`comparisons`	string[]	Required. The comparisons a filter condition on this type offers, by the operator stored in the condition. `is-empty` and `is-not-empty` are offered for every type and MUST NOT be listed.
`sort`	`text`, `number`, `false-first`, `chronological`, `option-order`, `title`	Required. How values compare when sorted: by text ignoring case, numerically, unchecked first, by time, by the options' order (of the first value, for several), or by the first related row's title. Empty values sort last in both directions.
`converts`	map value type → conversion	What a value becomes when its column's type changes to another (7.6).

7.6 Conversions

Conversion	From → to	Result
`written-form`	any → a text type	The value's written form: the text a cell shows.
`parse`	text → number, checkbox, date, date and time, time	The value parsed in its target type's form (a number as JSON writes one, `true` or `false`, ISO 8601); a text that does not parse is not converted.
`match-option`	text → a choice	The option whose name equals the text, ignoring case, created when there is none.
`wrap`	one value → several	The one value as the only item.
`unwrap`	several → one value	The only item, when the cell holds exactly one.

A change of a column's value type MUST convert every cell whose value the change's conversion converts, in the same step. A value with no conversion to the new type, or one its conversion cannot convert, MUST be kept as it is, under its old key, and reported as a finding on its cell. No value is discarded by a change of type.