DOC: Add a tutorial for the edit mode

CHANGELOG.md

@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added a previous and next buttons for pages in the tour
 - Added warnings to inform about minimum width when accessing tour and
   edit mode on small screens.
+- Added a tutorial for the edit mode to the documentation
 
 ### Changed (for changes in existing functionality)
 - The heading attributes datatype, path, checksum and size are now placed 

src/doc/tutorials/edit_mode.rst

+The Edit Mode
+=============
+
+Entities in CaosDB can be changed, created, and deleted using the
+``Edit Mode``. In the following chapter, you'll learn how. You should
+be fairly familiar with the concepts of Records, RecordTypes and
+Properties in CaosDB. If you have doubts, please have a look at the
+`data model documentation
+<https://docs.indiscale.com/caosdb-server/Data-Model.html>`_.
+
+In usual setups of CaosDB, you have to log in to use the edit
+mode. Afterwards, you can access it by clicking on the button in the
+to panel as shown below:
+
+.. image:: edit-mode-button.png
+   :width: 480
+   :alt: Edit mode button
+
+After entering the edit mode, the button changes its text to ``Leave
+Edit Mode``. Unsurprisingly, clicking here terminates the edit mode.
+
+.. note::
+
+   The edit mode is only available if you have sufficient
+   privileges. You can only create/edit/delete entities if your user
+   is allowed to do that. User and group permissions can be configured
+   in detail as explained in the `server documentation
+   <https://docs.indiscale.com/caosdb-server/Permissions.html>`_.
+
+When you have entered the edit mode, you'll see the edit mode toolbox
+appearing on the right hand side of your screen:
+
+.. image:: edit-mode-toolbox.png
+   :width: 240
+   :alt: Edit mode toolbox
+
+You'll learn more about its contents in the following sections. Right
+now it only contains the options for creating a new RecordType or
+Property which we'll explain in :ref:`new_recordtypes_properties`.
+
+.. _change_existing:
+
+Changing an existing Entity
+---------------------------
+
+We'll start by changing and updating existing entities. First, find
+the entity you want to change and enter the edit mode. You'll see an
+edit button in the top right of the entity card:
+
+.. image:: edit-entity-button.png
+   :width: 240
+   :alt: Edit entity button
+
+After clicking on this button, the edit menu for this entity is opened
+as shown below for a guitar Record from the `demo
+<https://demo.indiscale.com>`_. You'll also note that the edit mode
+toolbox changes its contents: It now harbours two lists of the
+existing Properties and RecordTypes.
+
+.. image:: change-entity.png
+   :width: 720
+   :alt: Changing an existing Record
+
+Property values can be changed in the entity card directly; additional
+parents can be added by dragging them from the list of RecordTypes to
+the corresponding area at the top of the Record. Similarly, Properties
+can be added by dragging Properties (or RecordTypes) from the list in the edit mode toolbox
+to the corresponding area at the bottom of the Record. Properties and
+parents can be removed from the entity by clicking on the trash-can
+symbol. Not that a Record must always have at least one parent.
+
+Changes will be applied after clicking on ``Save`` or can be discarded
+entirely by clicking ``Cancel``. Existing Properties and RecordTypes
+can be edited in the same way. Note that when changing a RecordType,
+the properties don't have values.
+	 
+
+Creating a new Record
+---------------------
+
+If you want to create a new Record of a given RecordType, visit that
+RecordType and enter the edit mode (if your new Record will have more
+than one parent, visit any one of them - you can add the others
+later). A new Record is then created by clicking on the ``+Record``
+button in the top right of the RecordType:
+
+.. image:: new-record.png
+   :width: 240
+   :alt: New record button
+
+Clicking here opens an entity card with an edit menu for the new
+Record similar to the one discussed in :ref:`change_existing`. In
+here, you can enter the name and the description of your new Record,
+assign values to its properties, and add further parents or properties
+from the corresponding lists in the edit mode toolbox. The new Record
+is inserted by clicking ``Save``.
+
+.. _new_recordtypes_properties:
+
+Creating new RecordTypes and Properties
+---------------------------------------
+
+You can extend the data model of your CaosDB by creating new
+RecordTypes and Properties directly from the WebUI. This is done by
+clicking on the corresponding buttons in the edit mode toolbox:
+
+.. image:: edit-mode-toolbox.png
+   :width: 240
+   :alt: Edit mode toolbox
+
+When creating a new RecordType, a RecordType card is added to the
+entity panel, similar to the new Record explained above:
+
+.. image:: new-recordtype.png
+   :width: 720
+   :alt: Create a new RecordType
+
+As above, you can enter a name and a description. You can add parents
+and properties by selecting them from the lists in the edit mode
+toolbox and dragging them to the respective areas in the new
+RecordType. Note that in contrast to Records, the properties of
+RecordTypes do not have values.
+
+When creating a new property name and description can be entered as
+above. In addition, the `datatype` can be selected from the CaosDB
+datatypes ``TEXT``, ``DOUBLE``, ``INTEGER``, ``DATETIME``,
+``BOOLEAN``, ``FILE``, and ``REFERENCE``. See `here
+<https://docs.indiscale.com/caosdb-server/specification/Datatype.html>`_
+for more information on the datatypes. You can also choose whether the
+new property should have a single value or a list of values.
+
+.. image:: new-property.png
+   :width: 720
+   :alt: Create a new Property
+
+When creating a property with datatype ``INTEGER`` or ``DOUBLE``,
+i.e., a number, you may enter a unit in an additional input field if
+applicable. In case of a ``REFERENCE`` property, you may specify the
+RecordType that all referenced Records must have. In the above example
+a ``REFERENCE`` property is created which may only have violins as
+values. Again, the new entity is created by clicking on ``save``.
+
+.. note::
+
+   After having created a new RecordType or Property, you may have to
+   leave and re-enter the edit mode for the new entity to appear in
+   the lists of Properties or RecordTypes in the edit mode toolbox.
+
+Deleting an Entity
+------------------
+
+Entities can also be deleted by clicking on the delete button in the
+top right of the entity:
+
+.. image:: delete-entity-button.png
+   :width: 240
+   :alt: Delete entity button
+
+After clicking on ``delete`` you'll be asked for confirmation. Note that
+entities cannot be deleted if they are needed by other entities, e.g.,
+as a reference.
+
+
+Uploading files
+---------------
+
+In case of properties with data type ``FILE``, you can use the edit
+mode to upload a corresponding file directly. When editing the Record
+which will have the file to be uploaded as the value of the
+corresponding property (named ``SourceFile`` in the example below),
+add the property as described above if it isn't present already. Next
+to the dropdown menu, in which you can choose from existing files, you
+find an uploaded button:
+
+.. image:: file-upload.png
+   :width: 720
+   :alt: File upload button
+
+Click on it to open an upload dialogue in which you can choose the
+file that you want to upload. The files uploaded this way will be
+stored within ``/uploaded.by/<REALM>/<USER>/``.
+
+The same is true for properties with data type ``REFERENCE``, too. In
+that case, the Record of the file that is uploaded will be assigned the
+RecordType of value of the original reference property.
+
+.. warning::
+
+   Until `this bug
+   <https://gitlab.indiscale.com/caosdb/src/caosdb-webui/-/issues/200>`_
+   has been fixed, the upload button is broken and does not open the
+   upload dialogue.
+

src/doc/tutorials/index.rst

@@ -8,4 +8,7 @@ This chapter contains the following tutorials:
    :maxdepth: 2
    :glob:
 
+   first_steps
+   query
+   edit_mode
    *