XLSForm Template - Few missing Appearances

wroos · November 1, 2023, 10:10pm

Hi @LN, @yanokwa
I did a quick check of the new template against the reference table and found some missing options for appearance (sheet Appearances and https://xlsform.org/en/ref-table/). Add_Appearances01.xlsx (10.8 KB)

Maybe we could also create a new tag for postings concerning this template, please?

I would also like to propose putting Excel filters in all tables in the sheets. This would for ex. allow to filter appearances for a type or those not available in Enketo.

Furthermore, I would prefer to adapt the column order in the appearances table to the reference table, i. e. starting with type/item, to get type-based ordering of the appearances.

Overall, the new template is a big step forward. Many thanks for your work!

Kind regards

LN · November 2, 2023, 10:10pm

Thanks for the verification, I really appreciate it!

I realize I should have mentioned that one of our goals is to move towards documenting a single, preferred way to do things. XLSForm has historically defined a lot of aliases which can lead to confusing examples and documentation. I realize there are tradeoffs here -- if people already use the less-favored way of doing something, they may find it confusing not to find it in reference. We think the overall value of presenting a single approach and having consistent examples and documentation outweighs that concern.

thousands-sep: good catch, have added that it applies to decimal and text numbers!

autocomplete: documented as its alias search

printer: deprecated; the Zebra print driver app and the printer it was designed for are no longer available. We'll be working on a way to build and send a document to a generic Android printer in the next Collect release.

new-rear: as far as I know it was never implemented anywhere

table-list: this is an alias for building a grid of selects. As far as I know it's not documented anywhere and looking at the pyxform code I'd rather we not expose it further. I've seen many forms with the "raw" grid building and it seems generally approachable to users.

Select appearances

There used to be differences between how Enketo and Collect treated select appearances. These were aligned as described in this thread.

compact: deprecated, use columns-pack/columns-pack no-buttons

compact-n: deprecated, use columns-n/columns-n no-buttons

horizontal: deprecated, use columns

quickcompact: deprecated, use quick as a modifier to any select one you want

Special Enketo behavior

distress: its more general counterpart is the range widget which can have a vertical presentation with ticks. We never discussed distress for inclusion in the ODK spec and it feels pretty specific.

streets, terrain, satellite, [other]: this depends on map layers defined in the Enketo configuration. I think it's best documented in Enketo.

w-n: this feels like it doesn't stand on its own. We chose to mention it in the hover description of the style setting only. Someone would have to read longer documentation on the grid theme to know what those appearances mean. That said, I'm on the fence about it and could be convinced if others would rather see it part of the appearance table!

wroos · November 3, 2023, 12:20am

Thanks! A lot of interesting details; and fully agree with the goals.
Few small remarks:

We would like that the Template also covers Enketo, as people use XLSForm here too (sometimes even the same form for both tools in parallel). Maybe an extra block in template parts? (See https://enketo.org/openrosa/#collection)
table-list and field-list show a slightly different screen (at least in Enketo) see example, and table-list seems a simpler coding form.
MatrixLikert03.xlsx (14.3 KB)
new-rear may make sense (might even exist in KoboCollect?).

Hint: As far as I have seen likert cannot be combined with field-list appearances. (See https://community.kobotoolbox.org/t/kobomatrix-for-likert-scale/46705/2). Or is there an option?

wroos · November 15, 2023, 12:41am

Hi @LN,
I made an example for the difference between grid selects with field-list (preferred) and table-list, see
TableHeading02.xlsx (21.9 KB)

I also found few existing appearance docs (e.g. former reference-table). There are also several table-list usage in the form postings, e.g. https://forum.getodk.org/search?q=table-list%20after%3A2018-01-01 (since 2018). Maybe, it would be good to give a hint in the new template that usage of table-list appearance is not recommended.

There is another related issue/bug. Until the bug is fixed, read_only is needed to make field-list (or table-list) based tables working well in Enketo. Without the "label" row items can be selected and 1. But in Collect the behaviour seems ok, no data for the label title are created.

Side-note: If read_only is set and Collect is used, the labels will not show up for the field-list option, but for the table-list. (This might happen, if Collect and Enketo are used in parallel for data collection with the same form).

Collect with read_only set
Field-list (label, list-nolabel)

Table-list

.

LN · November 21, 2023, 7:30pm

We absolutely do too! Are there any of the three "special Enketo behavior" items that you feel strongly should be included?

The things I don't like about it is that it's not documented at all and it injects some nodes into the form instance. Specifically, it creates nodes for the title and the header. See this form example to see how to re-create what table-list does without using the alias. You can look at the XML form definition or submitted data from the table-list variation to see the note and header fields that are added.

My guess is that at some point someone noticed that for long question text, having the question text in the corner of the table is not nice. I think that in an ideal world, that person would have asked whether putting the question text in the corner is the best behavior for the label appearance and maybe suggested either always putting the question text above, suggested a new appearance that modifies label to get the question text above, or documented the pattern that table-list ends up implementing. Instead, they introduced the table-list alias but did not document what it's an alias for. But anyway, it's in there now so I think we can document it and add it to the template.

We discovered when implementing new-front to force taking selfies that controlling which camera is used is not very reliable. It also doesn't apply to Enketo. We didn't hear of a usecase for new-rear so we didn't end up implementing it.

KoboCollect is a nearly exact copy of the ODK Collect version with the same version name. For example, if you're using Kobo Collect v2023.3.4, that is the same as ODK Collect v2023.3.4. You can verify that at: https://github.com/kobotoolbox/collect Differences are that text is changed and it doesn't include the Mapbox mapping engine.

When you say field-list appearances you mean that likert could have an effect similar to label/list/list-nolabel? You're correct that there's no such thing. I guess the difference between list-nolabel and e.g. likert-nolabel would be lines between the choice radio buttons? Note that currently Collect doesn't even render lines between them with regular likerts because there was a bug in the implementation so list-nolabel really does do the same thing.

That is a bug!

I don't think that's related to grid-theme which is entirely ignored by Collect. My guess is that you made the label row read-only at the same time that you added the grid theme directive. Making a label field read-only does hide the labels. Does that sound right?

wroos · February 13, 2024, 1:05am

Hello @LN,
The ODK template says no-calendar appearance (for date and datetime) is working in Collect and in Enketo. But current tests indicate that it only works in Collect, see https://community.kobotoolbox.org/t/when-i-use-date-type-without-any-appearance-option-it-gives-a-calendar/49738/14 (and XLSForm documentation https://xlsform.org/en/#appearance and Kobo documentation https://support.kobotoolbox.org/date_time.html#advanced-appearances).

So, this might be a further point for your list of Enketo / Collect differences.

If there is a (hidden) keyword for Gregorian Calendar appearance, this might offer a workaround for Enketo.