Merge pull request #189 from alliomeria/1.3.0

New Webform LoD via CSV DO Element + Custom Webforms Update
esmero · Feb 21, 2024 · 9ebdd72 · 9ebdd72
2 parents df9a3fe + 6dbbc23
commit 9ebdd72
Show file tree

Hide file tree

Showing 11 changed files with 125 additions and 8 deletions.
diff --git a/docs/customwebformelements.md b/docs/customwebformelements.md
@@ -8,7 +8,7 @@ tags:
 
 # Archipelago Custom Webform Elements
 
-In addition to the [core elements](https://api.drupal.org/api/drupal/namespace/Drupal%21Core%21Render%21Element/8) provided by the [Drupal Webform module](https://www.drupal.org/project/webform), Archipelago also deploys a robust set of custom webform elements specific to digital repositories metadata needs and use cases.
+In addition to the [core elements](https://api.drupal.org/api/drupal/namespace/Drupal%21Core%21Render%21Element) provided by the [Drupal Webform module](https://www.drupal.org/project/webform), Archipelago also deploys a robust set of custom webform elements specific to digital repositories metadata needs and use cases.
 
 ### Linked Data:
 
@@ -49,6 +49,17 @@ _(*found under Composite Elements in "Add Element" menu)_
 
 * Europeana Entity Suggest
     - Provides a form element to reconciliate against [Europeana Entity](https://pro.europeana.eu/page/entity)
+
+### Custom/Local Webform LoD Elements
+
+_(*also found under Composite Elements in "Add Element" menu)_
+
+* Webform Options LoD suggest
+    - Provides a form element autocomplete labels/urls(values) from Webform Options.
+
+* Webform LoD from CSV attached to an ADO suggest
+    - Provides a form element autocomplete labels/urls(values) from a CSV attached to a Digital Object.
+    - Documentation Guide found here: [Using Archipelago's 'Webform LoD from CSV attached to an ADO suggest'](WebformLoDfromCSV.md)
 
 ### File Upload Elements:
 
@@ -86,4 +97,10 @@ _(*found under Composite Elements in "Add Element" menu)_
 #### But wait there's more!
 
 You can review the coding behind these custom elements here:
-<https://github.com/esmero/webform_strawberryfield/tree/1.1.0/src/Element>
+<https://github.com/esmero/webform_strawberryfield/tree/1.3.0/src/Element>
+
+___
+
+Thank you for reading! Please contact us on our [Archipelago Commons Google Group](https://groups.google.com/forum/#!forum/archipelago-commons) with any questions or feedback.
+
+Return to the [Archipelago Documentation main page](index.md).
diff --git a/docs/images/DefaultArchipelagoWebforms.png b/docs/images/DefaultArchipelagoWebforms.png
diff --git a/docs/images/WebformAddElement.png b/docs/images/WebformAddElement.png
diff --git a/docs/images/WebformLoDfromCSVaddElement.png b/docs/images/WebformLoDfromCSVaddElement.png
diff --git a/docs/images/WebformLoDfromCSVadvancedTab.png b/docs/images/WebformLoDfromCSVadvancedTab.png
diff --git a/docs/images/WebformLoDfromCSVautocompleteSettings.png b/docs/images/WebformLoDfromCSVautocompleteSettings.png
diff --git a/docs/images/WebformLoDfromCSVgeneralSettings.png b/docs/images/WebformLoDfromCSVgeneralSettings.png
diff --git a/docs/images/WebformLoDfromCSVinAction.png b/docs/images/WebformLoDfromCSVinAction.png
diff --git a/docs/webformLoDfromCSV.md b/docs/webformLoDfromCSV.md
@@ -0,0 +1,90 @@
+---
+title: Archipelago Custom Webform Elements
+tags:
+  - Webform
+  - Form Mode
+  - Webform Elements
+---
+
+# Using Archipelago's 'Webform LoD from CSV attached to an ADO suggest'
+
+Archipelago's custom webform element 'Webform LoD from CSV attached to an ADO suggest' provides a form element autocomplete labels/urls(values) from a CSV attached to a Digital Object. Using this element affords a way for you to utilize a custom local vocabulary, a subset of labels and URIs from a wider LoD authority source, or an LoD vocabulary that does not have an accessible API or public query service.
+
+## Step-by-step
+
+1. To use this element, you need to first have prepared a CSV file containing two columns only:
+
+    - one column for 'label' containing the labels for your vocabulary
+    - one column for 'uris' containing the corresponding uris for your vocabulary
+
+2. Create a new Digital Object, and attached the prepared CSV file to the new Digital Object.
+
+    - Be sure to provide a unique label to help you identify this Object in future steps.
+    - It is recommended that you do not Publish this Object.
+
+!!! note
+
+    If you are not yet familiar with how to create a Digtial Object, please refer to [this guide](firstobject.md).
+
+3. Go to `Admin > Structure > Webforms` and select the 'Build' button beside the Default Descriptive Metadata Webform.
+
+4. Scroll down to the 'Subjects and Other Classifications' page of the Webform and select 'Add Element'.
+
+![Webform Add Element](images/webformAddElement.png)
+
+5. In the 'Select an element to add ..' popup that opens, either scroll down to select the 'Composite Element' section or search for the 'Webform LoD from CSV attached to an ADO suggest.' Select 'Add Element'.
+
+![Webform LoD From CSV Add Element](images/WebformLoDfromCSVaddElement.png)
+
+6. In the Edit tab that opens for your newly added element, you will need to review the following sections.
+
+* Element Settings
+
+    - provide a Title for element
+    - check that the Key generated from the Title you supply is well formed and make changes if needed
+    - specify the 'Allowed number of values'
+
+![Webform LoD from CSV General Settings](images/WebformLoDfromCSVgeneralSettings.png)
+
+* Webform LoD from CSV attached to an ADO suggest settings:
+
+    - It is recommended to keept both 'label' and 'uri' checked as Visible.
+    - You may also wish to mark both elements as 'Required'
+
+![Webform LoD from CSV Autocomplete Settings](images/WebformLoDfromCSVautocompleteSettings.png)
+
+* Autocomplete settings
+
+    - In the 'Choose an ADO' box, begin typing to search for the Digital Object that holds a CSV containing the Vocabulary you want to autocomplete.
+    - Under 'The CSV column(header name) that will be used for autocompleting', enter 'label'
+    - Under 'The CSV column(header name) that will be used for the URL value', enter 'uri'
+    - 'Autocomplete limit'
+          - determines the maximum number of matches to be displayed
+          - recommended that you set to '10'.
+    - 'Autocomplete minimum number of characters'
+          - determines the minimum number of characters a user must type before a search is performed
+          - recommended that you set to '3'.
+    - 'Autocomplete matching operator'
+          - determines the method used to collect autocomplete suggestions
+          - recommended to use 'Starts with'          
+
+7. Navigate to the 'Advanced' tab for this Webform element.
+
+    - Open the 'Multiple settings' section
+    - dDeselect the options to 'Allow users to sort elements' and 'Allow users to add more items'
+
+![Webform LoD from CSV Advanced Tab](images/WebformLoDfromCSVadvancedTab.png)
+
+8. Save your new form element settings. Then Save your updated Webform.
+
+9. Navigate to a Digital Object in your repository that you would like to use this new custom vocabulary element with. Select 'Edit' for that Digital Object and navigate to the 'Subjects and Other Classifications' page of the webform. Begin typing a label found in your prepared CSV associated with the webform element.
+
+![Webform LoD from CSV in Action](images/WebformLoDfromCSVinAction.png)
+
+You can now begin using this custom vocab vocabulary element when using the corresponding webform (where you added this element) to Edit and Update your Digital Objects. You may also wish to add this same element to the Default Digital Object Collection/Creative Work Series webform.
+
+___
+
+Thank you for reading! Please contact us on our [Archipelago Commons Google Group](https://groups.google.com/forum/#!forum/archipelago-commons) with any questions or feedback.
+
+Return to the [Archipelago Documentation main page](index.md).
diff --git a/docs/webforms.md b/docs/webforms.md
@@ -10,22 +10,31 @@ tags:
 
 The [Webform Strawberryfield](https://github.com/esmero/webform_strawberryfield) module provides [Drupal Webform](https://www.drupal.org/project/webform) ( == awesome piece of code) integrations for StrawberryField so you can really have control over your Metadata ingests. These custom elements provide Drupal Webform integrations for Archipelago’s StrawberryField so you can have fine grained and detailed control over your Metadata ingests and edits.
 
+## Where to Find
+
+You can access Webforms in Archipelago at:
+- `Admin > Structure > Webforms`
+- `/admin/structure/webform/`
+
+![Default Archipelago Webforms](images/DefaultArchipelagoWebforms.png)
+
 ### Instructions and Guides
 
 * [How to Create a Webform as an Input Method for Archipelago Digital Objects (ADO)](webformsasinput.md)
 * [Customizing Webforms: Modifying allowable file extensions](modifyingfileextensionsinwebform.md)
 * [Archipelago Custom Webform Elements](customwebformelements.md)
+* [Using Archipelago's 'Webform LoD from CSV attached to an ADO suggest'](WebformLoDfromCSV.md)
 
-### Examples
+### Archipelago Default Example Webforms
 
-Use these webforms or their elements to create a custom webform for your own repository/project needs
+Use these webforms or their elements to create a custom webform for your own repository/project needs:
 
 * Archipelago Default Deployment Webforms
-    * [Descriptive Metadata](https://github.com/esmero/archipelago-deployment/blob/1.0.0/config/sync/webform.webform.descriptive_metadata.yml)
-        * [Corresponding Schema.org Type Options](https://github.com/esmero/archipelago-deployment/blob/1.0.0/config/sync/webform.webform_options.schema_org_creative_works.yml)
+    * [Descriptive Metadata](https://github.com/esmero/archipelago-deployment/blob/1.3.0/config/sync/webform.webform.descriptive_metadata.yml)
+        * [Corresponding Schema.org Type Options](https://github.com/esmero/archipelago-deployment/blob/1.3.0/config/sync/webform.webform_options.schema_org_creative_works.yml)
 
-    * [Digital Object Collection](https://github.com/esmero/archipelago-deployment/blob/1.0.0/config/sync/webform.webform.digital_object_collection.yml)
-        * [Corresponding Schema.org Type Options](https://github.com/esmero/archipelago-deployment/blob/1.0.0/config/sync/webform.webform_options.schema_org_cw_collections.yml)
+    * [Digital Object Collection](https://github.com/esmero/archipelago-deployment/blob/1.3.0/config/sync/webform.webform.digital_object_collection.yml)
+        * [Corresponding Schema.org Type Options](https://github.com/esmero/archipelago-deployment/blob/1.3.0/config/sync/webform.webform_options.schema_org_cw_collections.yml)
 
 ___
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -61,6 +61,7 @@ nav:
         - How to Create a Webform as an Input Method for Archipelago Digital Objects (ADO): webformsasinput.md
         - Customizing Webforms (Modifying allowable file extensions): modifyingfileextensionsinwebform.md
         - Archipelago Custom Webform Elements: customwebformelements.md
+        - Using Archipelago's 'Webform LoD from CSV attached to an ADO suggest': WebformLoDfromCSV.md
       - Find and Replace:
         - find_and_replace.md
         - Text Based Find and Replace: find_and_replace_action_text.md