Add JSON Form Widget readme (#4344)

docs/requirements.txt

@@ -2,6 +2,7 @@ myst-parser>=2.0.0
 sphinx==7.2.6
 sphinx-rtd-theme>=1.2.2
 sphinxcontrib-httpdomain>=1.8.1
+sphinxcontrib.mermaid>=1.0.0
 sphinxcontrib-phpdomain>=0.11.1
 pygments>=2.14
 sphinx-prompt>=1.8.0

docs/source/components/index.rst

@@ -8,3 +8,4 @@ Components
    dkan_datastore
    dkan_harvest
    dkan_api
+   json_form_widget

docs/source/components/json_form_widget.rst

@@ -0,0 +1,2 @@
+.. include:: ../../../modules/json_form_widget/README.md
+    :parser: myst_parser.sphinx_

docs/source/conf.py

@@ -36,6 +36,7 @@
   'myst_parser',
   'sphinx.ext.autosectionlabel',
   'sphinxcontrib.httpdomain',
+  'sphinxcontrib.mermaid',
   'sphinx_rtd_theme',
   'sphinx_prompt'
 ]
@@ -76,6 +77,7 @@
     '.md': 'markdown',
 }
 source_parsers = {'.md': 'myst_parser.sphinx_'}
+myst_fence_as_directive = ["mermaid"]
 
 autosectionlabel_prefix_document = True
 autosectionlabel_maxdepth=None

docs/source/user-guide/guide_custom_schemas.rst

@@ -19,14 +19,22 @@ Then make any modifications necessary to the `dataset.json` file inside the `col
 
   }
 
-You can remove metadata fields with the exception of the *distribution* property, this one must remain present in the dataset.json file.
+.. note::
 
-Note that even if you are only changing the dataset.json schema, it is important to copy ALL of the schema files as DKAN will be expecting all of the
-schema files to be in the same location.
+  Note that even if you are only changing the dataset.json schema, it is important to copy ALL of the schema files as DKAN will be expecting all of the
+  schema files to be in the same location.
 
 .. warning::
 
-  Warning: The schema is actively used by the catalog to verify the validity of the data.
+  You can change or remove metadata fields from the dataset schema without causing issues, with the exception of the *distribution* property. If there is no array of objects called ``distribution``, each containing a ``downloadURL`` field, the :doc:`datastore <../components/dkan_datastore>` will not detect resource for import. This may or may not be an issue, depending on your use case. We hope to improve this in the future so that the datastore is not dependent on a particular metadata schema.
+
+.. warning::
+
+  The schema is actively used by the catalog to verify the validity of the data.
   Making changes to the schema after data is present in the catalog should be done with care
   as non-backward-compatible changes to the schema could cause issues.
   Look at ``Drupal::metastore::SchemaRetriever::findSchemaDirectory()`` for context.
+
+.. note::
+
+  For more information on how forms are generated from schema files, see :doc:`JSON Form Widget <../components/json_form_widget>`.

modules/json_form_widget/CodeFlowDiagrams.md

@@ -0,0 +1,88 @@
+# Code flow diagrams
+
+## High level
+
+```mermaid
+sequenceDiagram
+  participant FormBuilder
+  participant FieldTypeRouter
+  participant Element Handlers
+  participant SchemaUiHandler
+
+  loop each $property in $form
+    FormBuilder ->> FieldTypeRouter: getFormElement()
+    FieldTypeRouter ->> Element Handlers: handler methods<br />on helper classes
+    Note over FieldTypeRouter, Element Handlers: See "Initial Build" diagram<br />for handler details
+    Element Handlers ->> FormBuilder: Return default element for $property
+  end
+
+  FormBuilder ->> SchemaUiHandler: applySchemaUi()
+  Note over FormBuilder, SchemaUiHandler: Now apply SchemaUi to full $form
+  loop each $property
+    SchemaUiHandler ->> SchemaUiHandler: applyOnBaseField()
+    SchemaUiHandler ->> SchemaUiHandler: handlePropertySpec()
+    Note over SchemaUiHandler, SchemaUiHandler: See "Customizing widgets"<br />diagram
+  end
+  SchemaUiHandler ->> FormBuilder: Return $form with SchemaUi alterations
+```
+
+## The initial build
+
+```mermaid
+graph TD
+  getForm["FormBuilder::getJsonForm()"] --> eachProp["foreach $properties"]
+  eachProp --> getElement["FieldTypeRouter::getFormElement()"]
+  getElement --> switch[Switch $type]
+  switch --> object{object}
+
+  object -- true --> handleObject["ObjectHelper::handleObjectElement()"]
+  handleObject --> generateObject["ObjectHelper::generateObjectElement()"]
+  generateObject --> generateProperties["ObjectHelper::generateProperties()"]
+  generateProperties -- recursion --> eachProp
+
+
+  object -- false --> array{array}
+  array -- true --> handleArray["ArrayHelper::handleArrayElement()"]
+  handleArray --> complex{Items are objects?}
+  complex -- no --> buildSimple["ArrayHelper::buildSimpleArrayElement()"]
+  complex -- yes --> buildComplex["ArrayHelper::buildComplexArrayElement()"]
+  buildComplex --> handleObject
+
+  array -- false --> string["string"]
+  string -- true --> handleString["StringHelper::handleStringElement()"]
+  string -- false --> integer["integer"]
+  integer -- true --> handleInteger["IntegerHelper::handleIntegerElement()"]
+  switch --> eachProp
+  eachProp --> getForm
+```
+
+## Customizing widgets w/SchemaUI
+
+```mermaid
+flowchart-elk TD
+    getForm["FormBuilder::getJsonForm()"] --> applySchemaUi["SchemaUiHandler::applySchemaUi()"]
+    applySchemaUi --> eachProp2["foreach schemaUI property"]
+    eachProp2 --> applyOnBaseField["SchemaUiHandler::applyOnBaseField()"]
+    eachProp2 --> handlePropertySpec
+    subgraph s2["handlePropertySpec"]
+        handlePropertySpec["SchemaUiHandler::handlePropertySpec()"] --> what{"what is it"}
+        what -- array --> eachArrayElement
+        eachArrayElement --> applyOnArrayFields
+
+        applyOnArrayFields --> eachArrayElementField
+        eachArrayElementField --> inSpec{"Does SchemaUI<br>contain config for<br>this field?"}
+        inSpec -- yes --> handlePropertySpec
+        inSpec -- no --> applyOnBaseFieldRec["SchemaUiHandler::applyOnBaseField()"]
+
+        what -- object --> applyOnObjectFields
+        applyOnObjectFields --> eachObjField["foreach object property in the SchemaUi spec"]
+        eachObjField --> applyOnBaseFieldRec
+    end
+    subgraph s1["applyOnBaseField()"]
+        applyOnBaseField --> updateWidgets["SchemaUiHandler::updatewidgets()"]
+        updateWidgets --> disableFields["SchemaUiHandler::disableFields()"]
+        disableFields --> addPlaceholders["SchemaUiHandler::addPlaceholders()"]
+        addPlaceholders --> changeFieldDescriptions["SchemaUiHandler::changeFieldDescriptions()"]
+        changeFieldDescriptions --> changeFieldTitle["SchemaUiHandler::changeFieldTitle()"]
+    end
+```