Replace "form name" with "form title"?

[matthew-white]

Central uses the term "form name," but I'm noticing the term "form title" for the same thing in other places within ODK. I think we've heard that users are sometimes confused about the difference between the form ID and the form name/title, so I think it could be useful to standardize terminology. If "form title" is more common throughout ODK, perhaps we should start using that in Central?

[lognaturel]

Good point. I agree that "form title" would be more consistent. In particular, that's how it's set in XLSForm: http://xlsform.org/en/#settings-worksheet

[issa-tseng]

yeah i don't have a big problem with that. i guess i'll have to change the API too then. but also it is technically possible in the API to name a form something other than the xform title at the moment.

[issa-tseng]

and people seem to like the idea of being able to rename things more easily. being shackled to whatever the xform said when you uploaded i think is annoying.

[lognaturel]

being shackled to whatever the xform said when you uploaded i think is annoying.

Is it confusing if it shows up as something different on clients than on Central, though?

[issa-tseng]

i think if it stays consistent between central listing <=> collect form list it can be different when you actually open the form and that's okay? but i'm not sure. i agree that this area is a weird tricky mess but i also feel like the current solution sort of sucks.

[matthew-white]

I just had the thought that the form versioning that was introduced with v0.8 might affect this discussion, because now (I think) a form's XForm title can change from version to version. I don't have a sense of how common that is though. @lognaturel, have you encountered that before?

[lognaturel]

This has come up again because currently Central's form display name is read once from the form definition and not updated with new versions. We've seen this be a problem when there's a typo in the original title or the title evolves as the purpose of the form does. Then the same form has different names on Central and on clients and that gets confusing. For now we've decided to keep what Central displays consistent with what is in the form definition.

As far as I can tell, frontend never shows anything about a form name or title. I don't feel very strongly about internal naming. The API change would be breaking, right? It doesn't seem worth it to me.

We've also discussed adding the concept of a "nickname" that would be modifiable and just for display on Central. This might be complementary to a longer "description" or "notes" field about forms or maybe the description makes a modifiable name less important.

[matthew-white]

As far as I can tell, frontend never shows anything about a form name or title. I don't feel very strongly about internal naming. The API change would be breaking, right? It doesn't seem worth it to me.

I think that's right. I wish we knew whether any users are updating the name property over the API. If they are, then publishing a form draft would overwrite whatever name they have set. I assume that's pretty rare though.

[lognaturel]

I agree that's likely rare. Another option we have is to keep the name property exactly as it is but no longer use it in frontend. We would add a title property that is updated based on form updates which does get shown in frontend. The name property would continue to exist for other clients that already use it and would likely eventually be surfaced in frontend some different way (e.g. alongside the title as a Central-only nickname). Decision described in #29 (comment)

[lognaturel]

I'll describe some of my reasoning for wanting to always use the form title from the form definition because it may help with future decision making and intersects with some thinking I've been doing about introducing an entity concept.

ODK XForms form definitions have been defined to be entirely self-contained and portable. That is, once you have a form definition, you can push it to an arbitrary client and always get a similar/compatible result without needing additional resources provided by a server. Similarly, the form definition can be uploaded to any compatible server and work immediately with no additional configuration needed other than defining who has access to it. This is a powerful and intentional model that I'd like to see preserved. The tradeoff is that form definitions contain a few types of information -- form structure, text translations, metadata about how forms are displayed -- but that's well-managed by XLSForm's tabs, I think.

We've experimented with managing some of the metadata outside of form definitions by allowing users to override the version identifier when uploading a form definition. The biggest challenge we've seen with that is that we should be updating XLSForms in that case and aren't yet. Using that feature is disconcerting when there are further edits to make because then the form definition that's being modified does not match what the server knows. Some of this is alleviated by a more integrated form design experience but in the mean time, I think explicitly letting form definitions be self-contained is a good principle.

I mentioned an intersection with entity concepts. In that context, one extreme would be to pack the new concepts into form definitions. The other would be to leave form definitions virtually untouched and define the entity concept entirely as a server-driven wrapper. The latter is what I'm currently leaning towards for a variety of reasons, including maintaining the portability of form definitions.

[matthew-white]

Very interesting context!

Also, for the sake of keeping everything linked, I wanted to link to the v1.2 release criteria. There the suggestion is to have the name field always reflect the XForms title of the latest form version. The name field would no longer be editable: a PATCH request wouldn't fail, but it would have no effect on the name field. I think that seems reasonable for now and would give us space to consider a nickname concept in the future. And if someone's workflow is broken by this change, that'll be good information to learn as well.

[matthew-white]

Closed by getodk/central-backend#344. 🎉