Update docs for custom fields

website/site/content/docs/features/_index.md

@@ -19,7 +19,8 @@ description = "A list of features and limitations."
   into searchable PDF/A pdfs.
 - Non-destructive: all your uploaded files are never modified and can
   always be downloaded untouched
-- Organize files using tags, folders and other
+- Organize files using tags, folders, [Custom
+  Fields](@/docs/webapp/customfields.md) and other
   [metadata](@/docs/webapp/metadata.md)
 - Text is analysed to find and attach meta data automatically
 - *Keywords* metadata from pdf files is extracted and matched against

website/site/content/docs/webapp/customfields.md

@@ -0,0 +1,128 @@
++++
+title = "Custom Fields"
+weight = 18
++++
+
+Custom fields allow to attach user defined metadata to items. For
+example, you may want to track the amount of each receipt or the
+invoice number etc. You can define fields that can be associated to
+your items, much like organizations and person.
+
+Custom fields can be deactivated in the user settings.
+
+## Create custom fields
+
+Go to the _Manage Data_ page, that can be reached from the top right
+menu. One entry at the left shows _Custom Fields_:
+
+{{ figure(file="custom-fields-01.png") }}
+
+Fields are defined per collective. They can also be created in the
+item edit menu (just like creating organizations). The `#Usage`
+columns show how many items have a value for this field.
+
+A field consists of a name, a format and optional a label:
+
+{{ figure(file="custom-fields-02.png") }}
+
+The name and format is required. The name must be unique among all
+your fields and it is special in that it must be a valid _identifier_:
+no whitespace or weird characters allowed (ascii only). For displaying
+purposes you can set a _label_. This is only used for presenting and
+can contain unicode symbols, whitespace etc. If it is omitted, the
+_name_ is used instead.
+
+### Field Format
+
+Values of all fields are stored as strings. The format is important as
+this is used to make certain decisions. It restricts what values can
+be set for a field, it is used for deciding how to present values to
+the user and to choose an appropriate input method. There are 5
+formats provided:
+
+- `Number`: valid decimal numbers, use a dot to separate a fractional
+  part. Examples: `1`, `25.9001`, `0.1`
+- `Money`: same as Number, but requires a fractional part of exactly
+  two digits. Examples: `19.99`, `20.01`
+- `Text`: some arbitrary text.
+- `Boolean`: only `true` or `false`, a checkbox is used for setting
+  values
+- `Date`: a local date in ISO format. Examples: `2019-09-18`,
+  `2020-11-01`
+
+
+#### Note on changing the format
+
+The format of a field can be changed. This has implications to already
+stored values which may now not comply to the new format, for example,
+when changing a `Text` field into a `Date` field. In this case, the
+webui shows no value or shows an error, asking to provide a correct
+one. Existing values are not lost or tried to convert automatically.
+You can change the format back to `Text` to restore the previous
+state.
+
+
+## Add values
+
+Values for custom fields can be set in the item edit form or when
+editing [multiple items](@/docs/webapp/multiedit.md). There is a
+dropdown to select from existing fields.
+
+Use the dropdown to select which field you want to use. The
+corresponding input field is shown asking for values. You can select
+multiple fields. Only one value is allowed to set per item and field.
+The example below shows a text field and a money field:
+
+<div class="columns is-centered">
+    <div class="column is-three-quarters">
+    {{ figure(file="custom-fields-03.png") }}
+    </div>
+</div>
+
+You can create new fields right here without going to the _Manage
+Data_ page, by clicking the plus icon (1). The format of each field is
+indicated by an icon on the left of the input.
+
+As soon as a correct value is typed in, it is saved to the item and
+shown in the header next to the tags. If you click the trash-can icon
+next to an input, the value is removed from the item.
+
+{{ figure(file="custom-fields-04.png") }}
+
+The item card also shows custom fields, in the same place as tags:
+
+<div class="columns is-centered">
+    <div class="column is-half">
+    {{ imgnormal(file="custom-fields-05.png", width=300) }}
+    </div>
+</div>
+
+Adding values for custom fields in
+[multi-edit](@/docs/webapp/multiedit.md) mode works the same way.
+
+
+## Search
+
+The search menu shows the same dropdown for selecting a custom field.
+Then you can set values that are matched against your items.
+
+<div class="columns is-centered">
+    <div class="column is-three-quarters">
+    {{ figure(file="custom-fields-06.png") }}
+    </div>
+</div>
+
+Values are also validated in the search form. Only valid values are
+sent to the server for searching. For most fields you can use a
+wildcard at beginning and/or end to do a substring match:
+
+{{ figure(file="custom-fields-07.png") }}
+
+It is possible to use it for numeric fields, too. Just be aware that
+this is text-based matching.
+
+<div class="columns is-centered">
+    <div class="column is-three-quarters">
+    {{ figure(file="custom-fields-08.png") }}
+    </div>
+</div>

website/site/content/docs/webapp/metadata.md

@@ -120,6 +120,11 @@ they can be specified with the upload request or a [source
 url](@/docs/webapp/uploading.md#anonymous-upload) to have them
 automatically set when files arrive.
 
+## Custom Metadata
+
+Docspell allows to create your own fields. Please see [this
+page](@/docs/webapp/customfields.md) for more information.
+
 
 # Document Language