Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add section on representing zero repeats and add subheadings to repeat section #179

Merged
merged 6 commits into from
Nov 5, 2019

Conversation

lognaturel
Copy link
Contributor

@lognaturel lognaturel commented Oct 23, 2019

In preparation for XLSForm/pyxform#380 which will make it so that all repeats have a first instance.

Since this results in a change in behavior for some clients, I was at first going to talk about versions and specific clients but it got too messy:

  • The XLSForm spec isn't versioned (maybe it should be? Except that there isn't really a spec, just a tutorial. It's dynamic so hard to know how we'd do versioning exactly.)
  • Users generally don't even know they're using pyxform so calling out that version isn't helpful
  • There are a ton of systems that use pyxform as a library so it's not reasonable to try to enumerate those versions

I think it's ok to not talk about versions and to merge this before the pyxform change is released because:

  • The suggestions in the new zero repeats section are helpful and good form design even with currently-released versions of pyxform that result in Collect prompting before the first repeat
  • The only known client that will change in behavior is Collect because Enketo already injects the first instance
  • The change in behavior will only affect newly-converted forms
  • We've decided that pyxform will generate a warning for forms that include repeats and link to this documentation so that will be the natural way for users to find this information

I included a few other perhaps controversial changes.

  1. I pulled the repeat section to be a sibling of groups rather than a child. I don't think it's helpful for end users to think about repeat groups rather than just repeats. I think repeats are important enough that they merit their own section
  2. I took out selects from some of the sample forms because I thought they just made the section harder to skim.
  3. While I'm here, I documented how to name repeat instances. See the line before this one in the ODK XForms spec.

CC @nribeka @ukanga @MartijnR

It's nice to have a select_one question in one of the examples to make it clear that they're supported in repeats but having them for every example makes the section longer without added benefit.
Copy link
Contributor

@MartijnR MartijnR left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Looks very clear and should go a long way in avoiding support questions.

@lognaturel lognaturel requested a review from MartijnR October 24, 2019 17:20
Copy link
Contributor

@MartijnR MartijnR left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

@lognaturel lognaturel merged commit bccca4d into XLSForm:master Nov 5, 2019
@lognaturel lognaturel deleted the update-repeats branch November 5, 2019 21:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants