[November 2019 or later] Describe new horizontal list appearances

[lognaturel]

New spec, as agreed upon after further discussion here and on the forum:

new appearance	behavior	old appearance
columns	horizontal labels with buttons arranged in a number of columns determined by the screen width	horizontal
columns no-buttons	horizontal labels without buttons arranged in a number of columns determined by the screen width
columns-pack	horizontal labels with buttons, packed in to fit horizontal space with minimal padding	horizontal-compact
columns-pack no-buttons	horizontal labels without buttons, packed in to fit horizontal space with minimal padding	compact
columns-n	horizontal labels with buttons arranged in n columns where n is an integer between 1 and 10 inclusive
columns-n no-buttons	horizontal labels without buttons arranged in n columns where n is an integer between 1 and 10 inclusive	compact-n

This is really three base appearances with no-buttons that can combine with them (in any order) but the table above lists all 6 possibilities so that old appearances can be listed.

As of May 2019, both Collect (1.22) and Enketo (1.77.0) support all of these combinations. Documentation should be updated in November 2019 at the earliest when users will almost all have updated clients.

Various notes from the original discussion

### ODK Forum thread https://forum.opendatakit.org/t/spec-proposal-harmonize-compact-compact-n-horizontal-horizontal-compact-appearances/15565

Tentative action to take

The following changes will be made to clients, maintaining backwards compatibility:
compact-n > compact columns-n
horizontal -> columns
horizontal-compact -> columns-flex

In roughly April 2019, once users have updated their clients, change the documentation in the following way:

• compact-n, horizontal and horizontal-compact should be deprecated.
• columns, columns-n and columns-flex should be introduced.
• compact should be an optional modifier on those.

See forum.

Description

There are currently various appearances to make select options appear horizontally. Here is a test form illustrating these different appearances: https://docs.google.com/spreadsheets/d/1s79M4wsZ1QA5xwJWSEsTGoJCpjtrrdqP0NtpNeEmsPs/edit?usp=sharing

Here is how they currently behave:

appearance	Collect behavior	Enketo behavior
compact	horizontal labels without select markers, packed in to fit horizontal space with minimal padding	same as Collect
compact-n	horizontal labels without select markers arranged in n columns	same as Collect
horizontal	none	like compact-n but the number of columns is dynamically determined by the screen width and select markers are included
horizontal-compact	none	like compact but with select markers
list	label takes up half the screen, half the screen is for options, option labels are above select markers	none
label	like list but labels only	same as Collect
list-nolabel	like list but options only	same as Collect

I'm guessing these were added organically over time and it would be good to formalize them a little bit before they get broader support.

I think compact and compact-n make sense as they exist and are named appropriately.

I think list, label and list-nolabel are a bit odd but not too bad.

I'm not sure about horizontal -- @MartijnR what is its intended purpose in contrast to compact-n?

The behavior of horizontal-compact (horizontal options with minimal padding and select markers) seems useful but the naming doesn't make sense to me in the context of the other appearances. How about compact-markers or something like that?

[MartijnR]

Yes, it's good to re-think this.

I'm not sure about horizontal -- @MartijnR what is its intended purpose in contrast to compact-n?

Horizontal is more intelligent than compact, as it automatically determines the number of columns that fit on the screen (and changes when switching from portrait to landscape). It also shows radiobuttons and checkboxes.

The behavior of horizontal-compact (horizontal options with minimal padding and select markers) seems useful but the naming doesn't make sense to me in the context of the other appearances. How about compact-markers or something like that?

That's funny (or sad). I have concluded recently that horizontal-compact must have been a mistake (the ref-table now shows it as an alias for compact and Enketo validate will show a 'deprecated' warning). But now, you've discovered that compact doesn't show checkboxes, radiobuttons, so it make some sense after all! 🎉 👍 I agree the name is bad.

Too late now, but in hindsight, I think it would have made sense if we had done something like:

1. horizontal : display horizontally (not in columns, overflowing to next line)
2. columns: display in columns (determine columns intelligently)
3. columns-n: display with fixed number of columns
4. compact: do not display radiobuttons, checkboxes.

1-3 would be mutually exclusive and compact could be added to any of them.

Hmm. We should change at least horizontal-compact into something else and maybe horizontal as well (and turn those into aliases). Not sure what. It doesn't seem right to indicate that the radiobutton/checkboxes should be shown (because that's the default).

[lognaturel]

Thanks for the response, @MartijnR and I apologize for missing it! Agreed with your ideal and too bad it's too late to do. 😫

I've modified my initial table to describe horizontal as "like compact-n but the number of columns is dynamically determined by the screen width and select markers are included." Does that accurately represent it?

How about making the primary name for that appearance (currently horizontal) compact-auto-markers? The compact-auto part seems to be a nice analogy with compact-n. Now compact would just basically mean "horizontal rather than vertical" and markers would be additive. I know you said "it doesn't seem right to indicate that the radiobutton/checkboxes should be shown" and I theoretically agree but in practice I'm not coming up with a great alternative.

Then it would make sense for horizontal-compact to be compact-markers and we could introduce compact-auto to be like compact-auto-markers but without markers (useful for images).

So we'd have:

• compact: horizontal labels without select markers, packed in to fit horizontal space with minimal padding
• compact-markers: horizontal labels with select markers, packed in to fit horizontal space with minimal padding (alias horizontal-compact)
• compact-n: horizontal labels without select markers arranged in n columns
• compact-auto: horizontal labels without select markers arranged in a number of columns determined based on the device width
• compact-auto-markers: horizontal labels with select markers arranged in a number of columns determined based on the device width (alias horizontal)

Naturally, we could also add compact-n-markers to make this "complete".

It would be better to have several appearances that combine but I don't think this is terrible. At least it has some logic to it!

[MartijnR]

Welcome back @lognaturel!

I think this is good pragmatic solution, and I think we need others' input too (@tinok, you were looking at the current mess the other day).

2 things I'm not sure about:

• the word "marker"
• whether "marker" (or its replacement word) should be concatenated or be its own appearance

[tinok]

@MartijnR @lognaturel this is great. My ideal would be:

• Don't use 'marker'--never seen this to mean either 'checkbox' or 'radio button'. My suggestions would be no-button, nobutton, clickable
• Make this appearance as standalone so it can be used in combination with all other appearances (including without another appearance)

This would mean for select or select1 questions have have
compact
compact-n
compact-auto

as well as
no-button (or similar)

(and any combination of these appearances)

Thoughts?

[lognaturel]

Glad to see this moving!

While I agree that introducing an appearance to suppress select markers would be great if we were starting over, we can't change the meaning of compact or compact-n because they've existed for a long time and are all over documentation as being primarily for use with images. In that context, a select marker is definitely undesirable.

That means we need to introduce something that adds the markers to those existing appearances. We could certainly do it as an additive appearance rather than introducing new appearances with suffixes. It feels backwards but perhaps it's still better than the concatenation. Certainly it makes the implementation cleaner.

Agreed that my attempt to be precise with "select markers" is not common. I don't think of those markers as buttons but I could live with buttons or show-buttons if that seems clearer to both of you.

[MartijnR]

Thanks @tinok, @lognaturel.

I was about to say okay to show-buttons as a best-we-can-do compromise, but decided I want to make an attempt to help us figure out if we can do it right, in such a way that we don’t change the meaning of already-used appearances that remain valid but may have to translate old-style (which no longer exists) to a new style. This would actually be very easy to do implementation-wise.

appearance	description
compact	do everything to make things compact; no buttons, small margins, horizontal
grid	show options in a grid where the number of columns is determined based upon space available
grid-n	same but with fixed number of columns

So grid does not hide the radiobuttons/checkboxes but compact does. We miss out on a disorganized "compact" way of showing radiobuttons/checkboxes horizontally, but I doubt users will miss that.

These appearance combinations remain unchanged:

• compact

We'd have to translate these for backwards-compatibility of old forms in new clients:

• compact-n-> compact grid-n
• horizontal -> grid
• horizontal-compact -> compact grid (slightly different but okay)

[lognaturel]

That seems fine to me! Collect has never had horizontal and horizontal-compact so as long as that change in meaning is ok with you @MartijnR, I don't see a problem with it.

[MartijnR]

Great! Is grid the best to use, or should we use columns or something else? I'm just wondering if grid could cause confusion with the Gorgeous Grid Theme.

[lognaturel]

Hmm. Yes, columns does seem better since it's only configurable in the horizontal dimension. Maybe we should all give it another think through and finalize in the next couple of days.

[lognaturel]

Ok, have spent some more time meditating on this and am not coming up with anything I like more than columns.

[MartijnR]

Me too, and reached the same conclusion.

Any body else any opinion on these select & select_one appearance changes? @tinok, @faith-mutua, others?

[tinok]

I really like the final suggestions here with the much simplified columns and compact and columns-n appearances.

@MartijnR I find horizontal-compact useful to have response options fit as tightly as possible. Using the current appearances, see this comparison:

w4 horizontal

w4 horizontal-compact

I'm guessing compact columns-4 will achieve the same result (all responses on the same line)? If so I have no other objections.

[MartijnR]

Thanks @tinok,
This is a good point. I think I was too quick to dismiss the use case for the current horizontal-compact, because even if we tweak the new columns appearance to fix your example into displaying 4 equal columns automatically, it would unnecessarily break into a second row if one of the option labels is much larger than the others.

(compact columns-4 would not show the radiobuttons)

Since we cannot change the meaning of the existing horizontal (which would seem a good candidate otherwise) we need to come up with something else.

[lognaturel]

I'm going to come back to the suggestions I made earlier, perhaps with another word for marker and perhaps with marker being a modifier:

• compact: horizontal labels without select markers, packed in to fit horizontal space with minimal padding
• compact-markers: horizontal labels with select markers, packed in to fit horizontal space with minimal padding (alias horizontal-compact)
• compact-n: horizontal labels without select markers arranged in n columns
• compact-auto: horizontal labels without select markers arranged in a number of columns determined based on the device width
• compact-auto-markers: horizontal labels with select markers arranged in a number of columns determined based on the device width (alias horizontal)

[MartijnR]

Thanks for the re-suggestion @lognaturel ;). I had to think about this for 28 days. Any thoughts on:

• compact
• columns
• columns-n
• columns-flex

It avoids having to negate the button-hiding of compact which is the thing that bothers me. There is no difficult-to-grasp-for-users mutual exclusivity between compact and columns* . However, compact and compact columns-flex are exactly the same.

Translations to be made from old syntax:

compact-n > compact columns-n
horizontal -> columns
horizontal-compact -> columns-flex

[lognaturel]

I would really prefer that in addition to old forms working with updated clients, new forms work with old clients. This is particularly important to me for compact and compact-n which exist across the ecosystem.

Current Collect would choke on compact columns-n and would default to compact. That doesn't seem great -- we'd have to communicate to users to keep using compact-n unless they have upgraded their client. In fact, the compact-n-> compact grid-n suggestion had that same property. @MartijnR the latest set you've proposed would work with old Enketo?

[MartijnR]

@MartijnR the latest set you've proposed would work with old Enketo?

@lognatural, no it wouldn't. That's not much of a concern to me though (more of an advantage to force users to keep the client up to date - but maybe that's an extremist view ;)). So think this would be a totally acceptable temporary "cost" for the benefit of having more logical appearances.

So maybe we agree to disagree here and we need somebody or somebodies to break the tie!

[lognaturel]

more of an advantage to force users to keep the client up to date - but maybe that's an extremist view ;)

Interesting! Even when in the Enketo case users are often at the mercy of some other entity for upgrades?

The challenge is that something that is perfectly usable with compact-4 might not be at all with just compact.

[MartijnR]

Interesting! Even when in the Enketo case users are often at the mercy of some other entity for upgrades?

Yes, because we have backwards-compatibility for the old syntax, we can document/promote the new syntax a month or so after adding support for the new syntax in Enketo/Collect. It's really more about when to announce/document the change, perhaps. Does a more extreme version of delaying documentation sound like an approach that may alleviate your concern about old clients? We could even wait 6 months with documenting the new syntax. We could have the PR waiting for you when you're back! :)

[lognaturel]

Hehe. Ok, works for me. 😊6 months is probably a good time frame -- Collect users now upgrade quite quickly for the most part.

[MartijnR]

Awesome! Thanks.

Now, we'll just have to go through the same process for all the geo appearances (some day)...

[lognaturel]

I updated the issue to make the action clear. Let me know if I didn't capture it as intended.

Now, we'll just have to go through the same process for all the geo appearances (some day)...

Are there others beyond map and placement-map?

I think there are some interesting discussions to have there. Users would like to do things like specify basemaps in the form which would be very useful.

[MartijnR]

I think you haven't clicked 'Save' or maybe GitHub is having troubles. Ah here: https://forum.opendatakit.org/t/spec-proposal-harmonize-compact-compact-n-horizontal-horizontal-compact-appearances/15565. Thanks!

For geo, we've documented maps, hide-input, streets, terrain, satellite, [other], placement-map. I think there may be a few undocumented ones out there as well. But the other day, I noticed there are quite a few differences between clients between placement-map and maps.

[tinok]

Sounds like we have a plan for the new select appearances. I was ready to be the tie breaker :) +1 to reviewing the geopoint appearances between both clients.

[tiritea]

Have to say, compact-n - that is 'parameterized' appearances - dont really right to me... :-( It seems like the number of options should determine the (preferred) number of columns [and isnt this going to pretty much always be the case in practice?]. Otherwise, specifying column-n where n>#options is redundant.

And if n<#options the form writer is basically try to 'fit' a maximum number of columns to a screen size - which they dont know the actual width of - so than any extra arbitrarily wrap. So I therefore dont necessarily see the (minor?) benefit of being able to specify n - instead of simply using the number of options - is worth introducing something dubious like parameterized appearances [do we allow them anywhere else?].

So I'm still more inclined to have separate appearances for column (vs list), button (vs no button), label (vs no label), and maybe flex vs something (which is only meaningful when associated with column) to indicate the horizontal packing of columns. [eg flex = size each column width to fit, max = columns equal to total width, ...]

Wrapping options - which would be default behavior if only columns is specified (where each column is sized to fit) - would handled both a fixed number of options, or variable number if coming from an external choice-list. In both cases, I dont quite see the benefit of statically specifying a fixed number of columns in the form definition when the form writer has no way of knowing the screen width its actually going to be displayed on (yet alone landscape vs portrait)

Anyway, just my $0.02 before we go down the path of further setting-in-stone something a dubious (IMO) as paramterized appearances... :-)

[MartijnR]

We should see columns-n them as a documentation trick to save space. They're actually fixed columns-1, columns-2, etc, until columns-10.

Probably best to hold off on documenting for a bit.

Enketo Express is supporting these new appearances (and also the old ones for another year or so) from version 1.77.0 onwards.

Some major Enketo servers (and their versions):

• https://enketo.ona.io
• https://ee.kobotoolbox.org
• https://ee.humanitarianresponse.info/

[lognaturel]

We talked about 6 months before updating user-facing documentation so I tried to add that in the issue title in a sensible way. Feel free to edit if you see a better way, @MartijnR.