feat(#2080): add section for default parameters - #2081
Open
garethbowen wants to merge 5 commits into
Open
Conversation
8 tasks
garethbowen
commented
Aug 10, 2026
lognaturel
reviewed
Aug 13, 2026
| 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`. |
Member
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
approved these changes
Aug 14, 2026
lognaturel
left a comment
lognaturel
left a comment
Member
There was a problem hiding this comment.
Thank you! Can't wait to release this!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.