What is the philosophy/policy/spirit of appearances?

[lognaturel]

We've been touching on some bigger picture questions about appearances in #108 #112 #111 and a couple other issues. It would be awesome to articulate some principles, processes and guidelines around them. Currently they're not really documented in this spec and they've been added on in a pretty ad-hoc way.

Here are some things I've been thinking about, numbered so they can be commented on separately:

1. appearances are client hints. It should be totally fine for clients to ignore any or all of them. The only repercussion should be a loss of convenience for the enumerator or control for the form developer. (This isn't quite true at the moment but I'd like to propose it as policy moving forward)
2. Because clients can choose to pay attention to them or not, it's not a big deal to add more.
3. Given that we have a variety of different client types and users with significant challenges to overcome, appearances can be a powerful way to add value to the ecosystem with limited effort.
4. To ensure some coordination across clients, new appearances should be proposed here with a clear description of what they are intended to do, what a client that ignores them should do and a proposed name or two.
5. Once approved by lazy consensus, appearances should be added to this spec even if only a couple of clients actually do anything with them.
6. Unlike in the W3C spec, appearances can be combined in a space-separated list. This is generally implemented just in specific contexts and allows for a limited number of combinations. See #111.

The W3C spec does make it clear that arbitrary, client-specific appearances can be added here so I don't think any of this is revolutionary. I like some of the wording used here (about metadata appearances, but same idea).

What else? What other "provocative" thoughts do we have?? 😄

[chrislrobert]

Your proposals sound very sensible to me! I would only add:

6. When not mutually-exclusive in a logical or functional way, appearances can be combined by listing them in a space-separated list. When there is any kind of mutual-exclusivity, the first of several mutually-exclusive options should be used.

I don't feel super strongly about all of that, and there are a few discrete proposals snuck into that one bullet -- but I thought I'd give it a go.

On Tue, May 9, 2017 at 12:12 PM Hélène Martin notifications@github.com wrote:

We've been touching on some bigger picture questions about appearances in

108 https://github.com/opendatakit/xforms-spec/issues/108 #112

https://github.com/opendatakit/xforms-spec/issues/112 #111 https://github.com/opendatakit/xforms-spec/issues/111 and a couple other issues. It would be awesome to articulate some principles, processes and guidelines around them. Currently they're not really documented in this spec and they've been added on in a pretty ad-hoc way.

Here are some things I've been thinking about, numbered so they can be commented on separately:

1. appearances are client hints. It should be totally fine for clients to ignore any or all of them. The only repercussion should be a loss of convenience for the enumerator or control for the form developer. (This isn't quite true at the moment but I'd like to propose it as policy moving forward)
2. Because clients can choose to pay attention to them or not, it's not a big deal to add more.
3. Given that we have a variety of different client types and users with significant challenges to overcome, appearances can be a powerful way to add value to the ecosystem with limited effort.
4. To ensure some coordination across clients, new appearances should be proposed here with a clear description of what they are intended to do, what a client that ignores them should do and a proposed name or two.
5. Once approved by lazy consensus, appearances should be added to the spec.

The W3C spec does make it clear that arbitrary, client-specific appearances can be added here https://www.w3.org/community/xformsusers/wiki/XForms_2.0#attrs-appearance so I don't think any of this is revolutionary. I like some of the wording used here https://www.w3.org/MarkUp/Forms/wiki/Metadata_Appearance (about metadata appearances, but same idea).

What else? What other "provocative" thoughts do we have?? 😄

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/opendatakit/xforms-spec/issues/124, or mute the thread https://github.com/notifications/unsubscribe-auth/AIO0HuGKkKxSjq0-dOJESx42ebyvZhlhks5r4JBqgaJpZM4NVi3u .

[MartijnR]

Thanks for this! I totally agree with you both.

With respect to the need for collaboration on this (re. discussion in #112), I see it primarily as helpful for:

• users, to port their forms to a different client (e.g. from Enketo to Collect) and make it more likely the forms will behave/look the same. We can avoid little issues like we had a few months back, where Survey123 used appearance="autocomplete" and ODK Collect used appearance="search" for the same feature.
• developers, to be aware of added tweaks in other clients, to avoid user support issues, and to somewhat steer towards a sensible naming convention

[tiritea]

[1]. appearances should just be hints; that is to say, they can be ignored (by a client) and still be able to submit a semantically valid record (using just the binding info; eg type, constraints, ...)

[4]. Registry of appearances recognized by the server (aka ODK Xforms) MUST be published, otherwise there's a good possibility of appearance name collisions in custom implementations.

[6]. something to the effect that - contrary to XForms1.1 - the appearance value can contain a space-separated list of appearance settings. These SHOULD be mutually exclusive; eg <select1 ... appearance="full minimal"> is syntactically valid according to [4] but semantically ambiguous. But I'm not sure to what extent this should be enforced...

[7] related to [4], how can/should appearance names be shared across multiple controls (eg select & select1 can both use 'full', 'minimal' and 'compact'), and/or control+data types. That is to say, do we enumerate valid appearances by control (valid appearances for input, select, select1, upload, ...) or control+type (valid appearances for input when type is string, valid appearance for input when type is decimal, ...). Seems like we will probably need the level of granularity of the later.

Chris: I'm not quite sure what you mean by "... first of several mutually exclusive options should be used". Can you elaborate?

[chrislrobert]

I meant that we might hope that users wouldn't specify mutually-exclusive appearances, but if they do, we could have a well-defined behavior. In such a case, I could see either the first or the last ME appearance taking precedence.

BTW, I do believe that multiple appearances are already supported when not ME, as in "quick" and "compact".

On Wed, May 10, 2017, 9:35 PM Dr. Gareth S. Bestor notifications@github.com wrote:

[1]. appearances should just be hints; that is to say, they can be ignored (by a client) and still be able to submit a semantically valid record (using just the binding info; eg type, constraints, ...)

[4]. Registry of appearances recognized by the server (aka ODK Xforms) MUST be published, otherwise there's a good possibility of appearance name collisions in custom implementations.

[6]. something to the effect that - contrary to XForms1.1 - the appearance value can contain a space-separated list of appearance settings. These SHOULD be mutually exclusive; eg <select1 ... appearance="full minimal"> is syntactically valid according to [4] but semantically ambiguous. But I'm not sure to what extent this should be enforced...

[7] related to [4], how can/should appearance names be shared across multiple controls (eg select & select1 can both use 'full', 'minimal' and 'compact'), and/or control+data types. That is to say, do we enumerate valid appearances by control (valid appearances for input, select, select1, upload, ...) or control+type (valid appearances for input when type is string, valid appearance for input when type is decimal, ...). Seems like we will probably need the level of granularity of the later.

Chris: I'm not quite sure what you mean by "... first of several mutually exclusive options should be used". Can you elaborate?

— You are receiving this because you commented.

Reply to this email directly, view it on GitHub https://github.com/opendatakit/xforms-spec/issues/124#issuecomment-300657968, or mute the thread https://github.com/notifications/unsubscribe-auth/AIO0HrQHPHFk7Rg09shE4gxG6Jjo4Qi5ks5r4mXZgaJpZM4NVi3u .

[tiritea]

Gotcha. Yup, that's the same point I was trying to make in my [6] - once we allow multiple appearances do we enforce mutual exclusion (only one can be specified) - in case the form writer made an error - by rejecting the form as invalid, or (silently) accept only the first setting specified, last setting, or treat them as an explicit preference list (ie prefer the first appearance setting, but if not support then try the second...)? If specification of multiple mutually exclusive appearances will be considered a semantic error, then it would probably be better to reject the form upon submission, since its indicative that the form writer made a mistake (and we dont know what they intended). Or if it will be treated as an order list of appearance preferences then we'll need to be explicit what the ordering is, eg probably preferred first.

Devil is always in the details when writing a spec, eh ;-)

Anyone have any idea what Collect will do if you have <select1 ... appearance='full compact minimal'> !? Its going do something with it... :-)

[chrislrobert]

Well, there's a real tension between wanting the appearances to be somewhat client-specific and then wanting to validate them at server/upload/validation-time. In practice, the upload/validation process has tended to be pretty weak, and in cases where appearances are differently-supported by different clients that's probably been more asset than liability. But then I don't know the extent the spec should be constrained (or sullied?) by practical considerations. You could write something into the spec knowing full well that it wouldn't be implemented that way, I suppose (for practical reasons).

On Thu, May 11, 2017 at 5:39 PM Dr. Gareth S. Bestor < notifications@github.com> wrote:

Gotcha. Yup, that's the same point I was trying to make in my [6] - once we allow multiple appearances do we enforce mutual exclusion (only one can be specified) - in case the form writer made an error - by rejecting the form as invalid, or (silently) accept only the first setting specified, last setting, or treat them as an explicit preference list (ie prefer the first appearance setting, but if not support then try the second...)? If specification of multiple mutually exclusive appearances will be considered a semantic error, then it would probably be better to reject the form upon submission, since its indicative that the form writer made a mistake (and we dont know what they intended). Or if it will be treated as an order list of appearance preferences then we'll need to be explicit what the ordering is, eg probably preferred first.

Devil is always in the details when writing a spec, eh ;-)

Anyone have any idea what Collect will do if you have <select1 ... appearance='full compact minimal'> !? Its going do something with it... :-)

— You are receiving this because you commented.

Reply to this email directly, view it on GitHub https://github.com/opendatakit/xforms-spec/issues/124#issuecomment-300924483, or mute the thread https://github.com/notifications/unsubscribe-auth/AIO0Ht2YLnG76GNnLi196Zeykwm92LM-ks5r43_7gaJpZM4NVi3u .

[lognaturel]

The current approach for select1 appearances in Collect is to look at the beginning of the appearance string so your full compact minimal case above will show as the standard widget with no appearance. full is not supported as an explicit appearance so it just falls through to an else. That appearance is the same as pickles compact minimal or just no appearance at all. If you specify compactpickles you'll get a compact appearance. I think that looking at what the appearance string starts with works ok with a single appearance but I'm not clear on how that pattern would expand when it's possible to combine appearances. As far as I can see in a quick pass through, Collect does not yet support any combination of appearances. And it's not consistent about using startsWith, contains or equals to match individual ones.

My preference for untangling what happens when multiple appearances are specified would be to make the supported combinations explicit and then establish a hierarchy of which are default and which are overrides. This would be very much control-specific. There's an example of that here in the range appearances discussion. I like that it keeps things really simple for form creators (most people will just follow the table) while also giving an easy way for clients to support in a consistent way whatever crazy things someone might want to put in the appearance.

In that example, we're saying that the default way of displaying a range is with a slider. If the user specifies an appearance of picker, no matter what else they say, we override the default. Similarly, we say that by default a slider is horizontal. If they specify vertical somewhere, we override the default. If you really want to, you can have an appearance of horizontal vertical horizontal picker slider pickles which is not in the explicit table and we'll just show you a picker. It's a lax approach that I wouldn't like in most contexts but since appearances are hints, I think it's ok to say that in that case the user hinted in a kind of roundabout way that they wanted a picker. By agreeing on a hierarchy and including that kind of pseudocode, we can easily have consistent behavior across clients.

I very strongly believe we shouldn't try to reject forms with invalid appearance combinations.

[tiritea]

If handling appearances on the client-side is/will not be mandatory (ie just 'hints'), and the appearances are custom client-specific, and the fact the XForms server has no real knowledge of what the target client is at form submission time (at best, all it knows is that the client conforms to "OpenRosa1.0", from the HTTP header, and even that's much later at form download time), then for all practical purposes there is really no meaningful error checking that the server can perform (!). Basically the appearance setting is free-form text the client MAY interpret as it wants (but read on...)

At best, about all the server could do - at form submit time - is ensure the only formally specified appearances - "full", "compact", "minimal" - are mutually exclusive. But, with everything else loosey-goosey, I rather have to wonder if its really worth even bothering to do that...

About all we can do is instead perhaps set guidelines over the usage of multiple appearance settings, eg they SHOULD be treated as a partial ordering (eg preferred appearances first), and try to maintain a quasi-formal (and ODK ecosystem specific?) list of appearances, possible combinations thereof, that are currently in use and supported by one or another (ODK) Xforms client, their intended result, etc, to basically give form writers (future XForm client developers) some best-practices to follow.

[So, if it makes you feel any better, I wholly agree that we shouldn't reject forms based on their, um, 'appearance' 😄]

[lognaturel]

Don't judge a control by its appearance!! 😄

I'll try to issue a pull request soon summarizing this discussion within the spec and will tag you all for review.

[issa-tseng]

Question: besides "this is what XForms gave us," why are we so attached to shoving a half-dozen properties into a single appearance text attribute? Some are enums you choose from, some are boolean flags, there isn't much rhyme or reason since the field encompasses so much.

The X in XML should give us some leeway to add some of these features as eXtended properties, yes? We can add our own attributes if we wish?

I am an outsider voice to this conversation; please feel free to ignore me if I'm not making any sense.

[lognaturel]

For those who may not know @clint-tseng, he is the father of Build 👨‍👧. We were talking about how to implement range in Build and its different appearances when this came up (see #build-code for our full conversation).

I think it's a good point that certainly new attributes could be added and be defined more precisely. To me (with my limited experience), having a loose appearance seems to have been an asset for the reasons I mentioned in my original post. Given that its contents are always safe to ignore, I think the lack of structure there is ok. It does seem important to distinguish that from other kinds of directives such as transformations -- orx:max-pixels for example (#79).

That said, @clint-tseng if you have a proposal for how to amend what we've loosely agreed on here or have changes to propose for appearances that are currently under discussion, I'd be very interested.

[getodk-bot]

ERROR: This issue is in progress, but has no assignee.

[getodk-bot]

ERROR: This issue is in progress, but has no assignee.

[getodk-bot]

Hello @lognaturel, you have been unassigned from this issue because you have not updated this issue or any referenced pull requests for over 10 days.

You can reclaim this issue or claim any other issue by commenting @opendatakit-bot claim on that issue.

Thanks for your contributions, and hope to see you again soon!