DOC: Data model tutorial.

src/doc/tutorials/edit_mode.rst

@@ -8,9 +8,15 @@ 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>`_.
 
+.. contents::
+   :local:
+
+Getting started
+---------------
+
 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:
+top menu as shown below:
 
 .. image:: edit-mode-button.png
    :width: 480
@@ -97,42 +103,94 @@ is inserted by clicking ``Save``.
 
 .. _new_recordtypes_properties:
 
-Creating new RecordTypes and Properties
----------------------------------------
+Extend your data model: Add 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:
+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 "Create Property" and "Create RecordType" buttons in
+the edit mode toolbox:
 
 .. image:: edit-mode-toolbox.png
    :width: 240
    :alt: Edit mode toolbox
 
+New RecordType
+--------------
+
 When creating a new RecordType, a RecordType card is added to the
-entity panel, similar to the new Record explained above:
+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
+1. As above, you can enter a name and a description.  Don’t reuse existing names, if it can be
+   avoided.
+
+2. You can add parent RecordTypes by dragging existing RecordTypes on the “parents” zone above the
+   “name” field.
+
+   .. image:: img/dnd_parent.png
+      :width: 720
+      :alt: A screen shot of the drag&drop source and target zones in the RecordType edit mode
+            dialog
+
+   .. note::
+      
+      Adding parents currently (May 2023) does not automatically add the parents’ properties
+      yet. You will have to do this manually.
+   
+3. Add Properties as described above by selecting them from the lists in the edit mode toolbox and
+   dragging them to the Property area in the new RecordType. Note that in contrast to Records, the
+   Properties of RecordTypes do not have values.
+
+4. Click “Save” to save your newly created Property, or abort with the
+   “Cancel” button.
+
+New Property
+------------
+
+When creating a new Property, a Property card shows up:
+
+.. image:: img/screenshot_new_property.png
    :width: 720
    :alt: Create a new Property
 
+1. As above, you can enter a name and a description.  Don’t reuse existing names, if it can be avoided.
+
+2. Set the datatype:
+
+   -  **TEXT** properties hold short and long strings of text. Newlines
+      are also allowed.
+   -  **DOUBLE** properties hold numeric floating point values, such as
+      3.142. DOUBLE properties may have a unit, you can set the default
+      unit (for example kg or mm) here.
+   -  **INTEGER** properties hold (signed) integer values such as …, -2,
+      -1, 0, 1, 2, …, they can have units just like DOUBLE properties.
+   -  **DATETIME** properties are for dates or datetimes (date plus time
+      of day). LinkAhead does not distinguish between dates and
+      datetimes, because users can freely decide to enter a time if they
+      want to.
+   -  **BOOLEAN** properties can be either ``TRUE`` or ``FALSE``.
+   -  **FILE** properties are special, in that they reference a *File*
+      entity. *Files* are similar to normal *Records*, but do not need a
+      *RecordType* and are connected to a binary file which is stored
+      somewhere.
+   -  **REFERENCE** properties are links to other *Records*. You can choose a RecordType to further
+      specify which Records are accepted as references.
+
+      Inheritance plays a role here!  For example, if you select “Experiment”, all “Magnetism
+      Experiment” Records are also accepted (if they inherit from “Experiment”).
+
+   See `here <https://docs.indiscale.com/caosdb-server/specification/Datatype.html>`_ for more
+   information on the datatypes.
+
+3. If you want the new Property to be a list, check the checkbox. List
+   Properties can hold many entries of the same datatype.
+
+4. Click “Save” to save your newly created Property, or abort with the
+   “Cancel” button.
+
 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
@@ -146,20 +204,81 @@ values. Again, the new entity is created by clicking on ``save``.
    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
-------------------
+.. rubric:: Save your time!
+
+It is not alway necessary to create REFERENCE properties: In many cases when editing a
+``RecordType``, it’s sufficient to simply drag the target ``RecordType`` into the property
+field. For example, you can simply drag “CellLine” into the properties of the
+“CellCultureExperiment”, this will automatically create a REFERENCE property of type “CellLine”.
+
+Similarly, you can reuse existing non-list properties if you need a list property: Simply click on
+the “List” checkbox when adding it to a RecordType, instead of creating list and non-list properties
+with the same meaning.
+
+Of course there are cases where it makes sense to create new REFERENCE properties, notably when you
+want to give the reference a special name to denote its meaning. For example, you may want to create
+two distinct REFERENCE properties to “Person”s, one with the name “experimenter”, and one with the
+name “author”. These two properties now carry different meanings, and may even be used side by side
+in the same RecordType!
+
+.. _delete-an-entity:
+
+Delete an Entity (Record, Property, RecordType)
+-------------------------------------------------
 
 Entities can also be deleted by clicking on the delete button in the
-top right of the entity:
+top right of the entity, once the Edit Mode has been activated:
 
 .. 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.
+After clicking on ``delete`` you'll be asked for confirmation.
+
+.. note::
+
+   Entities cannot be deleted if they are needed by other entities, e.g., as a reference.  To check
+   if an entity is in use, you can start a query like this:
+
+   - ``FIND Record WITH myentity`` to check for Property or Record ``myentity``
+   - ``FIND Record MyRT`` for RecordType ``MyRT``
+
 
+Make a Property into a list
+---------------------------
+
+List Properties can hold many entries of the same datatype. If you want
+to change if a Property is a list or not, follow these steps:
+
+1. Find the property you want to change.
+2. Activate the *Edit Mode* in the top menu. Now the Property should have a clickable “Edit” button.
+3. Click the “Edit” button. A dialog for editing the Property shows up.
+4. Click the “list” checkbox to change the status.
+5. Click “Save” to save your changes, or abort with the “Cancel” button.
+
+Add Properties to an existing RecordType
+----------------------------------------
+
+1. Find the *RecordType* you want to change.
+2. Activate the *Edit Mode* in the top menu. Now the RecordType should have a clickable “Edit”
+   button.
+3. Click the “Edit” button. A dialog for editing the RecordType shows up.
+4. You can drag&drop existing Properties and RecordTypes from the toolbox onto the RecordType’s
+   target area. Note that dragging RecordTypes is similar to explicitly creating a REFERENCE
+   Property of the same type.
+5. Click “Save” to save your changes, or abort with the “Cancel” button.
+
+Remove Properties from an existing RecordType
+---------------------------------------------
+
+1. Find the *RecordType* you want to change.
+2. Activate the *Edit Mode* in the top menu. Now the RecordType should have a clickable “Edit”
+   button.
+3. Click the “Edit” button. A dialog for editing the RecordType shows up.
+4. Click on the Trash icon |The trash icon.| to remove a Property. The Property as an abstract
+   Entity still exists, it is simply not a part of this RecordType any more. Removed properties can
+   be re-added again at any time.
+5. Click “Save” to save your changes, or abort with the “Cancel” button.
 
 Uploading files
 ---------------
@@ -183,3 +302,7 @@ 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.
+
+.. |The trash icon.| image:: img/trash.png
+   :width: 20
+   :alt: The trash icon.