feat(#2080): add section for default parameters - #2081
Conversation
| Default Parameters | ||
| ^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| You can add parameters to the public link URL to set values when the form is opened. This can be useful to fill the form with data that's available on the page where the link is clicked. Parameters must be in the format :code:`d[{XPath}]={value}`, where XPath is the ref of the element you want to set, and value is the string value. For example, :code:`d[/root/name]=odk` will set the string "odk" into the name element. To reduce the length of the URL omit the primary instance name and leading slash, for example: :code:`d[name]=odk`. Set values on multiple elements by including more parameters separated by an ampersand, :code:`d[name]=odk&d[engine]=webforms`. |
There was a problem hiding this comment.
We don't typically use "XPath", "ref", "primary instance" in user-facing docs.
The default root node name out of XLSForm is data, not root. I don't think we need to document that the root node name can be included, it's too much to explain for most users.
Here's an alternative proposal:
Parameters use the format :code:`d[{field}]={value}`, where ``field`` identifies the form field you want to set and ``value`` is the text to put in it. For example, :code:`d[name]=odk` sets the ``name`` field to ``odk``. For a field inside groups or repeats, include the names of the groups or repeats in the field identifier, separated by slashes. For example: :code:`d[person/name]=Maria`.
To set multiple fields, separate parameters with an ampersand (``&``), for example: :code:`d[name]=odk&d[engine]=webforms`.
lognaturel
left a comment
lognaturel
left a comment
There was a problem hiding this comment.
Thank you! Can't wait to release this!
|
|
||
| .. _central-submissions-link-default-parameters: | ||
|
|
||
| Default Parameters |
There was a problem hiding this comment.
I think "URL defaults" is more human?
There was a problem hiding this comment.
I struggled with the naming here - I wanted something that people would understand but would also be a searchable feature. I'm not a fan of "url defaults" because it's ambiguous (is the URL defaulting to something?), but also would be hard to google for. I don't really like Default Parameters either. We could go for something verbose like "setting default values via the URL"?
Suggestions welcome...
There was a problem hiding this comment.
Also liking "Set field values in the URL"
Then the user-facing benefit becomes
Speed up data entry by including known field values in the form's URL. ODK will automatically fill the matching fields when the form opens, so users can focus on entering what鈥檚 new.
There was a problem hiding this comment.
@yanokwa I've updated the title and added an intro paragraph borrowing from your user-facing benefit.
3 participants
closes: #2080
What is included in this PR?
A section about using default parameters with public link URLs. I'm not convinced this is exactly the right place for this to live but it is the best option I could find right now.
What new issues will need to be opened because of this PR?
None.
What is left to be done in the addressed issue?
Nothing - but the web-forms feature should be merged and released before the documentation is pushed.
What problems did you encounter?
None.