Support for numeric range questions

[spatialdude]

Add support for numeric range questions.

The XForms specification describes the <range> control https://en.wikibooks.org/wiki/XForms/Range which might look like

This would be provide more flexibility than the distress appearance as supported in Enketo which has a limited range of 0 to 10.

The <range> control is also mentioned in the JavaRosa roadmap https://bitbucket.org/javarosa/javarosa/wiki/xform

Two approaches could be considered -

Option 1

A range question type, which would be supported by additional columns to define the parameters for start, end, step and increment and appearance type to control presentation (eg compact for spinner control or horizontal for a horizontal bar)

Option 2

Support a range appearance type for integer and decimal question types.

e.g range(start, end, step, increment) with logical default for all parameters (e.g. 1, 10, 1, 1)

Option 2 has some simplicity advantages in that does not require additional columns to be recognised nor the addition of new control types. It could also be combined with other appearance for additional styling control. As its just an appearance type, there would no change to pyxform.

e.g. range(1, 200) compact

Which might look like -

An enhanced range(...) appearance bears some similarity in concept to the select(...) expression appearance type http://xlsform.org/#dynamic-selects-from-pre-loaded-data

[MartijnR]

I would be in favor of adding support for the <range> control in our XForms implementation, according to the XForms spec. Perhaps just omitting the incremental property.

I think our first concern is adding it to JavaRosa because of ODK Validate. It may be better to move this discussion (as an XForms discussion) to the ODK Dev forum first, but we can see what happens here.

I'm guessing there are already some JavaRosa ports that have added this functionality but they might have been inflexible, specific solutions like Enketo's distress widget.

[MartijnR]

As long as the XForm syntax is as described in the XForms 1.1 spec, I would be open to any XLSForm syntax.

Option 3

Use in the type column: "range 1 100 2" (similar to @mitchellsundt suggestion here)

For the XLSForm syntax, I like option 1 and option 3 best.

If an appearance is chosen (option 2), that range(...) appearance would not make it into the XForm output, which makes it acceptable, in my opinion (@spatialdude, sorry I misread that during our out-of-thread discussion).

[lognaturel]

@spatialdude @MartijnR Range is now documented in the ODK XForms spec and in JavaRosa as of v2.2.0 released last weekend. Validate was also updated and on the Collect side, the widgets are on track to ship at the end of June (getodk/collect#105). It'd be great to get it in XLSForm/pyxform as well!

I think it'd be best not to add columns for this so I like options 2 or 3. I think in a vacuum I'd like 3 best but there isn't really such a convention. image has an appearance of align:1 1 1 which is probably the closest analog.

Would we require the user to specify whether the result should be an integer or decimal or infer it based on the arguments? This will be needed for the bind.

[lognaturel]

P.S. I'm not opposed to creating a new convention if it has significant benefits. I almost wish appearance were called parameters!

[ukanga]

I am in favour of option 2 or 3 as well.

How do we come to a consensus on this? I will work on the implementation once this is determined.

[MartijnR]

We do already have parameters for types, but not more than 1 (select_one options e.g.) so far, I believe.

I'd like to immediately forget about the OMG space-separated align appearance syntax 😧, but for this feature only care about the XForm output (which is the same for all options). So I'd go with whatever is easier for XLSForm builders to understand.

To reach consensus, I think we need to get somebody to cut the tie between option 2 and option 3!

[lognaturel]

I've given this some more thought and now prefer using the type column because range already supports several different appearances and I think it's more consistent to leave the appearance column for client hints in analogy to XForms (see discussion here).

Could the type column accept something of the format range(start, end, step, increment) and validate that all 4 parameters are given values?

There will also need to be a bind type of integer or decimal. I propose inferring that from the values for start, end, step and increment. If all are integers, generate an integer bind. If one or more are decimals, generate a decimal bind.

[spatialdude]

The simplicity of type column is quite nice at the moment, being essentially a keyword with the the exception of the select_* cases.

Expanding the scope of the type column to include more types that include parameters will potentially make the column much messier and harder to use for many users. (Even the select_... ) is confusing to some users but at least they get by.

As an example many of our users use a "hotted up" version of a template XLSForm that includes some very basic Excel validation in some of the columns (e.g. valid type, no duplicates in the name column etc.) which helps tremendously in reducing simple errors. Such validation in the spreadsheet will become much harder to do if the type column gets complicated. Example -
XLSFormTemplate.xlsx

The argument of not hijacking the appearance column to become a way of passing additional parameters is also valid.

I would suggest a modified approach which would be to add support for a new range type.

With the parameters defined in a new parameters column.

e.g.

type	parameters	name	label	appearance
text		name	Your name
date		dob	Date of birth
range	min=1;max=5	r1	Range 1 to 5

The parameters can be then used to specify type specific parameters that do not fit the other exiting columns that are well defined and common to all or most types.

The interpretation of the parameters would be type specific and have defaults if not specified. They key=value pair styles makes it easy to parse and not worry about order etc. as well as keeping it reasonably human friendly. The column, like most others, is optional (e.g. not using range type).

The range may have the following initial parameters -

• min=[minimum value] (default 1)
• max=[maximum value] (default 10)
• step=[step size] (default 1)

This approach supports parameters to be added for other types if and when appropriate without having to fudge it via other columns (like appearance).

Future parameters can be added with backward compatibility.
The parameters essentially would be output attributes in the XForm XML for the binding or control elements as appropriate.

The also keeps the appearance to be used as an application style hint as intended.

In fact range may have eventually support some appearance hints such as vertical or horizontal.

[lognaturel]

I'm not even kidding, I came here to basically say what @spatialdude said. 🎉 We are going to be adding more attributes on the ODK XForms side (see max-pixels for example) and so this would be a nice, extensible approach. I agree with @spatialdude that it has many nice properties.

I was going to suggest something JSON-like with colons rather than equals but I'm not picky on that point. The column could also be called either parameters or attributes.

I'd prefer not having defaults and force the user to specify values where needed. Defaults mean one more thing to describe in the specification and using them reduces clarity. For example, if I'm looking at a form with no max specified, I need to look up what it's going to default to.

[spatialdude]

@lognaturel 😀 👍

I think the use of = in the name value pairs might be a little more human friendly, not that I have any thing against colons 😀

It may also be worth considering what separates name value pairs. In my example I had ; but it may simply be a space which is then consistent with appearances and keep the column "friendly". In the case where a parameter may accept a string value that could have spaces, these would be quoted.

e.g.
min=1 max=25 step=5

param1=1 param2=100 param3="Blah blah blah"

As for the default, its nice to see all the parameter options, but to it may be beneficial for backward compatibility (e.g. parameters get added in a future update) to have the notion of defaults.

Although it might be nice for pyxform to perform some validation, syntax wise at least, in practice to maintain of flexibility this probably need not be too heavy handed about the exact parameter names and their values.

This keeps the column a little more flexible and open in much the way that appearances are not heavy-handedly validated.

Admittedly in the case of parameters for a type, there is value in more strictness compared to appearances which are more a hint. Ultimately it will be the responsibility of the app to determine what parameters and values it handles as long as they appear correctly as appropriate attributes in the XML.

As for the column name itself attributes also makes sense, maybe also properties

[marikavertzonis]

• hooray for range
• yeh for leaving appearance out of this new type implementation (its got enough going on already)
• I'd prefer to have defaults - they help self document the syntax
• I like the term 'attributes' to describe min max and step

[lognaturel]

I think we have for the most part reached consensus! 🎉 If I may try to summarize:

• introduce a new column called parameters, attributes or properties
• use name/value pairs separated by = in those cells
• separate name/value pairs either by spaces or ; or ,
• for range, allow min, max and step with defaults as specified by @spatialdude

I have a slight preference for comma or semicolon separators over spaces.

@ukanga Does this give you enough information to work with? Let us know if you need more details or want to deliberate a bit on some of the choices remaining to be made.

[ukanga]

@lognaturel this does give me the enough information to start with.