# The settings file

The file `settings.yaml` defines the properties of a collection.

It is a yaml file with a dict of properties and their values.

`name`:

  the human readable name of the collection.

`lang`:

  the language of the collection; valid values are listed in the xapian stemmer documentation and are usually either the English name or the two letter ISO639 code of a language.

`entry_label`:

  a jinja2 template used to show an entry in the interface; beside the entry fields two useful variables are `eid` for the full entry ID and `short_id` for the short version.

`default_sort`:

  a list of field names (possibly prefixed by + or -) that are used by default to sort results of searches in the collection. The fields must be marked as sortable in their definition, see below.

`search_aliases`:

  a dict of <name>: <search snippet> which can be used in a query template. For more details see Search templates and search_aliases

`fields`:

  The list of fields used by the collection, as described below.

## Field definitions

`name`:

  a name for the field (computer readable: keeping it lowercase alphabetic ascii is probably safer).

`type`:

  the type of the field: valid fields are listed in lesana.types module (see the `name` property for each field)

`index`:

  whether this field should be indexed: valid values are `free` for fields that should be available in the free text search and `field` for fields that should only be available by specifying the field name in the search.

`sortable`:

  boolean; whether this field is sortable. Sortable fields enable sorting the results and search by ranges, but having too many sortable fields make the search more resurce intensive.

`help`:

  a description for the field; this is e.g. added to new entries as a comment.

`default`:

  the default value to use when creating an entry.

`prefix`:

  the optional term prefix used inside xapian: if you don’t know what this means you should avoid using this, otherwise see Term Prefixes on the xapian documentation for details.

Some field types may add other custom properties.

### `list` properties

`list`:

  the type of the entries in the list; note that neither lists of non uniform values nor lists of lists are supported (if you need those you can use the `yaml` generic type, or write your own derivative with an additional type).

### `integer` properties

`auto`:

  automatic manipulation of the field contents.

  The value of `increment` will autoincrement the value at every update.

  The reference command-line client will run this update before editing an entry, allowing further changes from the user; a command line user can then decide to abort this change through the usual git commands.

  Other clients may decide to use a different workflow.

`increment`:

  the amount by which an `auto: increment` field is incremented (negative values are of course allowed). Default is 1.

### `decimal` properties

`precision`:

  if this property is set, every value in this field will get rounded to the given number of decimals.

  With this property it is possible to store decimal values as YAML floats instead of strings.

### `date` and `datetime` properties

`auto`:

  automatic manipulation of the field contents.

  The following values are supported.

  `creation`

    autofill the field at creation time with the current UTC time (`datetime`) or local zone day (`date`).

  `update`

    autofill the field when it is updated with the current UTC time (`datetime`) or local zone day (`date`).

    The reference command line client will run this update before editing an entry, allowing further changes from the user; a command line user can then decide to abort this change through the usual git commands.

    Other clients may decide to use a different workflow.

### `values`

The `string`, `text`, `list` and numeric types can have a property `value` with a list of valid values for that field.

An empty value is always allowed.

For the `list` type, each element of the list is checked, not the whole list.