Create a framework for adding parameters

[lognaturel]

Some time ago, we introduced a convention of using a parameters column for specifying attributes that only apply to a particular question type as key/value pairs. This allows us to do specialized validation on those parameters without adding columns to forms.

That pattern has served us well and we're likely to keep adding to it. Checking for and validating parameters is now a bunch of spaghetti code. Ideally that functionality could be pulled out for easier extensibility and maintenance.

One high-level concept would be to introduce a json spec for specifying parameters. That might make it possible to define what types they apply to and what function should be used to validate their values. Some types of things that might be tricky to represent:

• the value and ref params only apply to select_*_from_file, not other selects
• the capture-accuracy param only applies to geopoint and not to geoshape and geotrace. Some other params apply to all three.

[lindsay-stevens]

Relevant #651 (comment)

[jkuester]

Would you consider just passing though any parameters that do not match the pre-defined set of parameters for a particular question type? Basically, I am interested in being able to set a custom param on a question and then have that parameter get set as an attribute in the xml. This would provide implementations of ODK the flexibility to parameterize custom form features without needing to fork Pyxform (or upstream parameters that are specific to a particular platform).

In the CHT ecosystem, we have been stuck on a fork of Pyxform because there is some additional data we need to load from the xlsx file to support custom form functionality. I am hoping to find a "supported" way to do this without having to customize Pyxform.

An example of what we are running into is medic/cht-core#8681. We have a Countdown timer widget (displays a simple countdown timer in the form) and we want to make it just a custom appearance for the trigger question type (so that the timer is displayed to the user and OK value gets set as the question value once the timer runs out). The trouble is that we need a way for a form to customize the duration of the timer. I was hoping to be able to do this via a parameter.... Definitively open to other ideas on how to address this challenge! (and let me know if I should have logged this as a separate issue). Thanks!

[lognaturel]

Hi @jkuester!

Is there a reason you haven’t proposed it for inclusion in the ODK spec? You can do that at https://forum.getodk.org/c/ideas/9 if it seems generally useful.

Alternately, have you considered the extension points listed at https://xlsform.org/en/#advanced-use-and-extensibility ?

The idea with the parameters column is to do validation and provide a way to keep forms more horizontally compact for common functionality. Beyond that, there should be no difference with adding columns as described above.

[jkuester]

Thanks for the details @lognaturel! I had previously missed that documentation on the extension points and your explanation helps me to understand the different purposes between those and the properties column. Ultimately, I expect we can get what we need from the extension points (and it is nice to know that is their intended use).

Is there a reason you haven’t proposed it for inclusion in the ODK spec?

Most of our custom functionality at this point is pretty specific to our use cases (e.g. a select widget for being able to search for people in our DB). Even the countdown timer seems of limited value in broader data collection usecases, but I will definitely keep this in mind as we continue to try and standardize!

[lognaturel]

Sounds good all around!

[lindsay-stevens]

Per this comment

I forgot we had all these existing parameters that use dashes because they match the XForm convention. Typically we use underscores for new parameter names but I agree with your instinct to match the others in this context.