WCMS-20047: Data Dictionary Documentation (#4271)

docs/source/user-guide/guide_data_dictionaries.rst

@@ -195,13 +195,38 @@ Creating a data dictionary via the UI
 1. Log in as a user with the *Data: Create new content* permission.
 2. From the DKAN menu, select Data Dictionary -> Create.
 3. Enter a human readable title for your data dictionary.
-4. In the **Dictionary Fields** section, click the "Add one" button.
-5. Fill the form to define your field. Reference the Table Schema section above if needed.
-6. Repeat steps 4 and 5 for each field you want in your data dictionary.
-7. Click the "Save" button.
-8. See a list of your data dictionaries at `/api/1/metastore/schemas/data-dictionary/items/`
-9. Edit your data dictionary by going to `/admin/dkan/data-dictionaries`.
-10. Click the "Edit" link in the right-hand column next to the data dictionary you want to edit.
+4. To define a "Data Dictionary field" start by clicking "Add field".
+
+  .. image:: images/fields/add-data-field.png
+    :alt: A portion of the data dictionary creation admin page with a focus on the "Add field" button.
+
+5. An "Add new field" editable form box will appear. Complete the required form fields here, reference the `Table Schema <#table-schema>`_ section above if needed.
+
+  .. image:: images/fields/add-data-field-editable-form-box.png
+    :alt: A portion of the data dictionary creation admin page with a focus on the "Add new field" section.
+
+6. Click "Add" to save the field temporarily. Remember that the Data Dictionary and it's respective fields are not completely saved until the form is submitted in it's entirety by clicking "Save".
+7. Alternatively you can click "Cancel" to stop creating the Data Dictionary field, at which point all the information you entered will be removed and the "Add new Field" box will close.
+8. Note that after saving, an informational table will appear listing the data dictionary fields you have created thus far and their names, titles, and details (data types, formats and descriptions).
+
+  .. image:: images/fields/edit-data-field-informational-table.png
+    :alt: A portion of the data dictionary creation admin page with a focus on the informational table that appears.
+
+9. You also have the ability to edit or modify the data dictionary fields you've created so far by clicking the gear icon on the right-hand side of this table.
+10.  Clicking the gear icon will open an editable form that will show the previously entered information for the respective data dictionary field. You can then modify this information and either: "Save" (retain the modifications), "Cancel" (close the editable form box without retaining any modifications) or "Delete" (remove the respective Data Dictionary field entirely).
+
+  .. image:: images/fields/edit-data-field.png
+    :alt: A portion of the data dictionary creation admin page with a focus on the editable form that appears in order to modify the data dictionary field.
+
+11.  You can enter any additional data dictionary fields by repeating steps 4-6. 
+12.  Click the "Save" button.
+
+  .. image:: images/fields/data-field-save-data-dictionary.png
+    :alt: A portion of the data dictionary creation admin page with a focus on the save button at the bottom of the form.
+
+13.  See a list of your data dictionaries at `/api/1/metastore/schemas/data-dictionary/items/`.
+14.  Edit your data dictionary by going to `/admin/dkan/data-dictionaries`.
+15.  Click the "Edit" link in the right-hand column next to the data dictionary you want to edit.
 
 
 Adding indexes

docs/source/user-guide/guide_indexes.rst

@@ -63,14 +63,86 @@ In the example below we are defining two fields, and adding a standard index for
 GUI
 ---
 
-  1. Log in as an administrator.
-  2. From the DKAN menu, select Data Dictionary -> Create.
-  3. Enter a name for your data dictionary that will serve as its identifier.
-  4. Any column you want to index must be defined in the 'Dictionary Fields' section.
-  5. After defining the fields, move to the 'Dictionary Indexes' section.
-  6. Enter the column name into the 'Name' field.
-  7. Use the 'Add one' button to add more fields if desired.
-  8. Select the index type: standard or fulltext
-  9. Add a description to name the index if desired.
-  10. Click the “Save” button.
+As an alternative to creating Data Dictionary Indexes through the API, you may choose to use the graphical user interface (GUI).
+The GUI can be used to create both Data Dictionary Fields and Indexes. See below for how to create Indexes. For more information on how to add data dictionary fields please see :doc:`guide_data_dictionaries`.
+
+Prerequisites
+^^^^^^^^^^^^^
+1. Log in as an administrator.
+2. From the DKAN menu, select Data Dictionary -> Create.
+3. There are certain form elements that apply to all Data Dictionaries, they are as follows:
+
+  a. Identifier: This is a UUID and is autogenerated for each Data Dictionary.
+  b. Title: Enter a name for your data dictionary here.
+
+4. After completing the above two required fields, move to the Data Dictionary Fields section and complete it, referencing :doc:`guide_data_dictionaries` if needed. Please note that any column you want to index below must be defined in the ‘Data Dictionary Fields’ section (see step 2 in the ‘Index Fields’ section below for reference).
+5. After defining the fields, move to the ‘Indexes’ section.
+
+Indexes
+^^^^^^^
+1. Click "Add index".
+
+  .. image:: images/indexes/add-index.png
+    :alt: A portion of the data dictionary creation admin page with a focus on the "Add index" button.
+
+2. An editable "Index" form box will appear. Complete the required form fields here.
+
+  .. image:: images/indexes/add-index-editable-form-box.png
+    :alt: A portion of the data dictionary creation admin page with a focus on the editable form that appears after clicking the "Add index" button.
+
+3. After defining the index, move to the ‘Index Fields’ section. Please note that an index requires at least one index field and that index field must be defined in the ‘Data Dictionary Fields’ section.
+
+Index Fields
+^^^^^^^^^^^^
+1. To add an index field, click "Add field" under the ‘Fields’ section within the respective ‘Index’ section.
+2. An editable "Add new field" form box will appear. Complete the required form fields here:
+
+  .. image:: images/indexes/add-index-fields-editable-form-box.png
+    :alt: A portion of the data dictionary creation admin page with a focus on the editable form that appears after clicking the "Add new field or add field" button.
+
+ a. Name: Enter a name, this must be a key from the dictionary fields object as created previously (see step 4 in the ‘Prerequisites’ section above for reference).
+ b. Length: how many characters long this field can be.
+
+3. Click "Add" to save the field temporarily. Remember that the Data Dictionary and it's respective fields and indexes are not completely saved until the form is submitted by clicking "Save".
+4. Alternatively you can click "Cancel" to stop creating the index field, at which point all the information you entered will be removed and the editable "Add new field" form box will close.
+5. Note that after saving an index field, an informational table will appear listing the index fields you have created thus far and their names and length.
+
+  .. image:: images/indexes/add-index-fields-informational-table.png
+    :alt: A portion of the data dictionary creation admin page with a focus on informational table that appears after saving an index field.
+
+ a. You also have the ability to edit or modify the fields you've created so far by clicking the gear icon on the right-hand side of this table.
+ b. Clicking the gear icon will open an editable form that will show the previously entered information for the respective index field. You can then modify this information and either: "Save Index Field" (retain the modifications), "Cancel Index Field" (close the editable form box without retaining any modifications) or "Delete Index Field" (remove the respective index field entirely).
+
+    .. image:: images/indexes/edit-index-fields.png
+      :alt: A portion of the data dictionary creation admin page with a focus on editable form that appears after you click the gear icon to edit a specific index field.
+
+6. You can enter additional index fields by clicking "Add field" (in this index section) and repeating steps 2-3 in this Index Fields section again.
+7. After defining the index fields, click "Submit Index" to save the index temporarily. Remember that the Data Dictionary and it's respective fields and indexes are not completely saved until the form is submitted by clicking "Save".
+
+  .. image:: images/indexes/edit-index-box.png
+    :alt: A portion of the data dictionary creation admin page with a focus on the indexes box, specifically meant to reference the "Submit Index" button.
+
+8. Note that after submitting, an informational table will appear listing the indexes you have created thus far and their names, types, and fields (field name and field length).
+
+  .. image:: images/indexes/add-index-informational-table.png
+    :alt: A portion of the data dictionary creation admin page with a focus on informational table that appears after saving an index.
+
+ a. You also have the ability to edit or modify the indexes you've created so far by clicking the gear icon on the right-hand side of this table.
+ b. Clicking the gear icon will open an editable form that will show the previously entered information for the respective index. You can then modify this information and either: "Save" (retain the modifications), "Cancel Index" (close the editable form box without retaining any modifications) or "Delete Index" (remove the respective index entirely).
+
+    .. image:: images/indexes/edit-index.png
+      :alt: A portion of the data dictionary creation admin page with a focus on the edit index box.
+
+   1. Note here that it is not possible to modify index fields in this manner at this time. If you must change an index field, the current work around is to delete the associated index entirely and re-create it and it's fields again.
+
+9. Finally, make sure you click "Save" and then "Yes" to "Are you sure you want to publish this item?" in order to submit the form in it's entirety, saving the data dictionary.
+
+  .. image:: images/indexes/indexes-save-data-dictionary.png
+    :alt: A portion of the data dictionary creation admin page with a focus on the save button at the bottom of the form.
+
+10. See a list of your data dictionaries at `/api/1/metastore/schemas/data-dictionary/items/`.
+11. Edit your data dictionary by going to `/admin/dkan/data-dictionaries`.
+12. Click the "Edit" link in the right-hand column next to the data dictionary you want to edit.
+
+