7. Surface
Contents of DESL 0.2
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", (DESL 0.2) "hierarchy" |
Required. The layout: a table of rows and columns (7.2 to 7.6), or boxes that contain boxes (7.7). |
The other properties of surface are those of its kind. Sections 7.2 to 7.6 define the table kind, and section 7.7 the hierarchy kind.
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). |
| 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.
| 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.
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). |
| 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.
A hierarchy shows levels, elements drawn as boxes that contain boxes, and entries, elements a level holds that contain nothing. Labels name members of lists kept per document, notes stand at the level or entry they are about, and stored filters narrow and sort the page. Its roles name the metamodel's types and attributes:
| Property | Type | Description |
|---|---|---|
levels |
{type, title, description} |
Required. The levels' element type, which contains itself and the entries' type, and its string title and text description attributes. |
entries |
{type, title, description} |
Required. The entries' element type, and its title and description attributes. |
labels |
map attribute name → {on, options, prefix} |
Attributes whose values name members of a list: on, the types (of levels and entries) the attribute is on; options, {type, name, colour}, the element type whose elements are the list's members, with the attributes that name and colour one; prefix, what a filter's word for one of its members starts with, before the member's name (7.7.3), by default the attribute's name and :. |
notes |
{type, about, kind, text, detail, resolved} |
The notes' element type: about, a string attribute with a mentions facet (4.3) naming the level or entry a note is about; kind, an enumeration whose values carry icons (4.4); text and detail, its text; resolved, a bool. |
collapsed |
attribute name | The bool attribute, on the levels' and the entries' types, that folds a level or an entry. |
filters |
{type, name, query} |
The stored filters' element type, with the attributes that name one and hold its query (7.7.3). |
widths |
{type, level, width} |
The element type whose elements keep the widths of the columns of levels (7.7.1): level, a string attribute holding the column's depth as a whole number, 1 for the top levels; width, an int attribute holding its width in pixels. |
ids |
"shown" (default), "hidden" |
Whether an element's id is shown beside its title. |
Every host draws the same page:
- One page, which scrolls from top to bottom, with no second pane beside it.
- A level is a box. Its entries, then its levels, stand to its right, each in the order of the document, and the box is as high as what stands to its right. Neighbouring boxes share their borders. A level's top-level elements stand one below the other at the left edge of the page.
- Each level and entry shows its title, its id when
idsisshown, and its description when it has one, under the title. A mention in a description is drawn as a box holding the id and the current title of the element it names, and a broken one as broken. - A collapsed level or entry shows its id, its title, its labels and its notes icon only.
- Column widths. The levels of one depth stand in one column, as wide as the element of the
widthstype for that depth says, or as wide as the host draws a level when there is none. The user changes a column's width by dragging its right edge; the host then creates or sets that element, and a host SHOULD offer to take it away, which gives the column the host's width again. A width is the depth's in the document, not its place on a focused page. Withoutwidthsthe columns have the host's width and cannot be changed. - Focus. The page shows as many levels as fit its width, marks a level whose deeper levels do not fit, and lets the user make any level the left edge of the page, with a trail of the levels above it that leads back to each of them. Focus is the viewer's and is not stored.
- Notes. A level or entry shows, at its top right, the icon of the kind of its one unresolved note, an icon that stands for several when it has more, and a way to add the first when it has none. A collapsed level's icon also stands for the unresolved notes of everything inside it. Choosing the icon opens the notes it stands for as a list.
How a host draws a label, a menu or a list is not DESL's: a designer type's companion document names the looks.
A label attribute is a string, or a string with many, whose value names a member of its list by the member's name, ignoring case. A level's or entry's labels are drawn below its title, each in its member's colour.
A value that names no member is an implicit member of the list all the same: an element of the options type, with the id its derived rule gives it, standing after the stored members in the order of its first appearance in the document, with the colour attribute's default, and spelt as it first appears. Every operation on members serves it. Such a value is never reported. When a list is written (5.5), its implicit members become stored members, after the others, in their order.
Renaming a member MUST rename every value that names it in the same transaction, and deleting one MUST remove every such value; a specification states both with its operations.
A filter's query is words separated by spaces:
| Word | Selects |
|---|---|
<prefix><name> |
Entries whose label attribute with that prefix names that member, ignoring case: #security with the prefix #, @proposed with the prefix @, category:functional with the default prefix of category. |
item:pattern |
Levels whose title matches the pattern, with everything in them. * is any run of characters and ? one character, in any case; the pattern holds no space. |
sort:key |
The order of the entries within each level: number (by id), title, or the name of a label attribute, ascending; a label sorts by its member's place in its list, and an entry without it stands last. Of several sort: words the first counts. |
Words of one kind are alternatives, and kinds combine. A level is shown when an item: word selects it or one above it, or no item: word is given, and it holds an entry that is shown or no entry word is given. Narrowing and sorting change nothing in the document. A stored filter is an element of the filters type, which persistence.settings keeps in the registration (5.5).
A host SHOULD complete a word as it is typed, offering the members of the label whose prefix the word starts with, and the prefixes themselves, so that a user need not remember either.