add docs for global bc form items (#1018)

source/how-tos/app-development/interactive/form.rst

@@ -108,6 +108,8 @@ This is the full list of items with details, you may supply to this yaml file to
 
        whether or not the application is cacheable or not. Defaults to true.
 
+.. _bc_form_attributes:
+
 Attributes
 ----------
 
@@ -811,5 +813,47 @@ The last option is to :ref:`configure the cluster in the submit file <configurin
 When using this option, there's no need to add any cluster configuration to the
 form.yml.
 
+.. _global_bc_form_items:
+
+Global Batch Connect Form Items
+-------------------------------
+
+Since version 4.0, you can define form items once in an ``ondemand.d`` file
+that can be used in all batch connect applications.
+
+.. warning::
+
+  Global batch connect items need to have the prefix ``global_`` otherwise
+  OnDemand won't recognize it as a global configuration.
+
+
+Defining a global batch connect form item is just like specifying :ref:`bc_form_attributes`
+above. Only the location is in an ``ondemand.d`` file in ``/etc/ood/config/ondemand.d``
+under the ``global_bc_form_items`` key.
+
+Here's an example of defining a select widget with options called ``global_queues``.
+Note the appropriate previx of ``global``.
+
+.. code-block:: yaml
+
+  # /etc/ood/config/ondemand.d/global_bc_items.yml
+
+  global_bc_form_items:
+    global_queues:
+      widget: select
+      options:
+        - [ 'any', 'any' ]
+        - [ 'gpu', 'gpu' ]
+        - [ 'special', 'special', data-option-for-cluster-not-special: false ]
+
+Then to use this form item, one simply needs to specify it in the ``form`` section
+of the file and it will display the select widget defined above.
+
+.. code-block:: yaml
+
+  # form.yml
+  form:
+    - global_queues
+
 .. _markdown: https://en.wikipedia.org/wiki/Markdown
 .. _html form: https://en.wikipedia.org/wiki/Form_(HTML)

source/release-notes/v4.0-release-notes.rst

@@ -11,6 +11,8 @@ Administrative changes
 New Features
 ------------
 
+- `Global Batch Connect items`_
+
 Thanks!
 -------
 
@@ -92,3 +94,12 @@ Upgrade directions
 
 Details of new features
 -----------------------
+
+Global Batch Connect items
+..........................
+
+In 4.0 you can now define batch connect form items
+in ondemand.d files to be used in any batch connect
+application.
+
+See :ref:`global_bc_form_items` for more details.