diff --git a/CHANGELOG.md b/CHANGELOG.md index 3046befbe23b5f798ed77453b48e33f111ef01fb..58063e36939287c205cd539df1b3fc8ff59dc8d3 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/src/doc/tutorials/change-entity.png b/src/doc/tutorials/change-entity.png new file mode 100644 index 0000000000000000000000000000000000000000..ddae63fa841976709b2dcf98389e578d79998f03 Binary files /dev/null and b/src/doc/tutorials/change-entity.png differ diff --git a/src/doc/tutorials/delete-entity-button.png b/src/doc/tutorials/delete-entity-button.png new file mode 100644 index 0000000000000000000000000000000000000000..c118b8217a63d00eeee6469731d8561810a8d7d4 Binary files /dev/null and b/src/doc/tutorials/delete-entity-button.png differ diff --git a/src/doc/tutorials/edit-entity-button.png b/src/doc/tutorials/edit-entity-button.png new file mode 100644 index 0000000000000000000000000000000000000000..79003121df69cc615890589941079e766f970775 Binary files /dev/null and b/src/doc/tutorials/edit-entity-button.png differ diff --git a/src/doc/tutorials/edit-mode-button.png b/src/doc/tutorials/edit-mode-button.png new file mode 100644 index 0000000000000000000000000000000000000000..28dd167a5887be45d6c41581a4645e796c3b6328 Binary files /dev/null and b/src/doc/tutorials/edit-mode-button.png differ diff --git a/src/doc/tutorials/edit-mode-toolbox.png b/src/doc/tutorials/edit-mode-toolbox.png new file mode 100644 index 0000000000000000000000000000000000000000..e291c43a77e41adfa9f2b821d90f9982449c5f9f Binary files /dev/null and b/src/doc/tutorials/edit-mode-toolbox.png differ diff --git a/src/doc/tutorials/edit_mode.rst b/src/doc/tutorials/edit_mode.rst new file mode 100644 index 0000000000000000000000000000000000000000..01502f55d5d76959a17bf74c71632d0d902f625e --- /dev/null +++ b/src/doc/tutorials/edit_mode.rst @@ -0,0 +1,193 @@ +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. + diff --git a/src/doc/tutorials/file-upload.png b/src/doc/tutorials/file-upload.png new file mode 100644 index 0000000000000000000000000000000000000000..85c9224a6453cc219e7510b13fb1c5869f7c01c6 Binary files /dev/null and b/src/doc/tutorials/file-upload.png differ diff --git a/src/doc/tutorials/index.rst b/src/doc/tutorials/index.rst index dbfeafed2a09d587ebd538a62ed9002943b52aa0..b01e45e3d574cd675b8410da1dbd1d79cb8e20c0 100644 --- a/src/doc/tutorials/index.rst +++ b/src/doc/tutorials/index.rst @@ -8,4 +8,7 @@ This chapter contains the following tutorials: :maxdepth: 2 :glob: + first_steps + query + edit_mode * diff --git a/src/doc/tutorials/new-property.png b/src/doc/tutorials/new-property.png new file mode 100644 index 0000000000000000000000000000000000000000..af438007278b2ddf30fae4f56fb803bfda06577f Binary files /dev/null and b/src/doc/tutorials/new-property.png differ diff --git a/src/doc/tutorials/new-record.png b/src/doc/tutorials/new-record.png new file mode 100644 index 0000000000000000000000000000000000000000..0b2ac31afa78ca2aa20ee8f5f83f9a04ce39be30 Binary files /dev/null and b/src/doc/tutorials/new-record.png differ diff --git a/src/doc/tutorials/new-recordtype.png b/src/doc/tutorials/new-recordtype.png new file mode 100644 index 0000000000000000000000000000000000000000..9519a9ada3b034c01308ac4a4c350954d9d32d65 Binary files /dev/null and b/src/doc/tutorials/new-recordtype.png differ