afform: Support url-params and other config options for Values in Submmission forms
Per conversations with @kurund , @totten , and @colemanw at the 2022 Manchester sprint:
Submission forms currently offer configuration of Values as a way to ensure a certain value is submitted for a given property of the submitted entity, without displaying a field to the form user. Currently it's only possible to specify a static value for each Value. This issue covers work to increase this functionality by allowing the specification of more options for each value. As a start, we're aiming to support these: a default value; and a value defined by URL parameter (overriding the default value). Future efforts may allow for defining a mechanism for on-page calculation of the value; specifying that the submitted value should not be applied if updating an existing entity (could be useful e.g. for Source field); and more.
New attributes:
At the start we aim to support only these:
-
default
: the default value -
urlparam
: the name of a URL parameter from which the value can be taken (which value, if given, will override thedefault
value)
We're also aiming to make decisions now which would facilitate adding other attributes in the future.
UI changes:
-
Move the Values section out of the "pallette" pane in the left, to a new "Values" tab in the "canvas" pane on the right:
-
For each defined Value, support configuration of various attributes, probably through a pop-up accessed through a gear icon, similar to that already in use under for fields under the Fields tab:
Rationale:
- We currently have the "Values" configuration appearing at the top of the left-side "pallette" pane. This leaves limited space for configuration options on each Value, whereas there will be more room for that in the "canvas" pane.
- It would make for a more consisten user experience to treat the left-side "pallette" only as a pool of available entity properties (fields), and the right-side "canvas" as the place for configuring those properties which one has selected for use in the form.
Form storage/schema changes:
Values are currently stored in the form markup within the data
attribute of each <af-entity>
tag; e.g. this line indicates that the do_not_email field should be forced to "yes":
<af-entity data="{contact_type: 'Individual', do_not_email: '1'}" type="Contact" name="Individual1" label="Individual 1" actions="{create: true, update: true}" security="RBAC" />
To store these additional config options, we make some changes to this schema:
- Values will be stored as an
<af-field>
element within the<af-entity>
container, so that the above-mentioned<af-entity>
tag would be represented like so:
<af-entity data="{contact_type: 'Individual'}" type="Contact" name="Individual1" label="Individual 1" actions="{create: true, update: true}" security="RBAC">
<af-field name="do_not_email" default="1" />
</af-entity>
Rationale:
- The
<af-field>
tag is appropriate here because these "entity properties" are in fact fields -- though they won't be presented as form fields, they will be submitted as API fields (consider the "getFields" api action). - Storing as attributes of an
<af-field>
tag is an alternative to cramming arrays of increasing complexity into thedata
attribute of the<af-entity>
tag, and this alternative facilitates easier validation. - When parsing the stored form markup for display, it should be pretty easy to identify
<af-field>
tags within an<af-entity>
container, then avoid formatting them as displayed form fields, and ensure they're attributed to the correct entity upon submission.