Restructure form widgets #577

adammichaelwood · 2018-03-15T05:21:02Z

closes #566
closes #569
closes #38
closes #411
closes #378
closes #570
closes #568
closes #490

What is included?

Near-complete rewrite of form-widgets.rst, including new sections for several additional widgets.

Any problems?

Few things (misspellings, etc.) that I think should have been caught by style checks, but weren't. Will file a few issues against this.

(Before I forget: labelled/labeled, XSLForm)

Work still to do?

Shrink images a bit more.

lognaturel

This is looking nice!

At a high level, I'd like to see a little bit more narrative to help users figure out non-obvious characteristics of some of the widgets (e.g. the text widget expands vertically) and why certain widgets are useful (e.g. text with numbers appearance is useful for phone numbers).

I'm also finding the "See Also" notes a little disconnected from their section. I'd tend to put them above the screenshots. That said, scaling down the screenshots may also address this. How about scaling them as a percentage of the screen but no bigger than say 300 pixels wide or so? It would be great to get two on the same line where possible.

lognaturel · 2018-03-19T18:19:54Z

odk1-src/form-widgets.rst


-This document is a list of available ODK :term:`Collect` :term:`form` :term:`widgets <widget>` (question types), with:


I would still find it helpful to have a brief introduction here that states forms are made up of questions which can have different types, widgets refer to the whole package -- how the type is shown in Collect, how the user enters data, any appearances, etc.

Yes. That is coming.

lognaturel · 2018-03-19T18:20:46Z

odk1-src/form-widgets.rst


-This section shows examples of all the form widgets types, with no additional options displayed.
+All of the text widgets share the :tc:`text` type,
+and the inputs from them are saved as literal strings.


"the inputs from them" feels hard to process to me. "their inputs"?

lognaturel · 2018-03-19T18:24:05Z

odk1-src/form-widgets.rst

+  :tc:`text`
+appearance
+  *none*
+
 A simple text input.


It can contain line breaks and will grow vertically as the user adds more text. The keyboard shown depends on user's Android settings.

lognaturel · 2018-03-19T18:26:39Z

odk1-src/form-widgets.rst

-
-.. image:: /img/form-widgets/geopoint-completed.*
-  :alt: A completed geopoint form widget. It looks the same as before, but now has four fields below the button: Latitude, Longitude, Altitude, and Accuracy.
+A numerical input that treats the input as a string, rather than a number.


The keyboard shown only contains numbers, decimal markers and -. This is useful to input numbers larger than 999,999,999 (e.g. phone numbers).

lognaturel · 2018-03-19T18:30:11Z

odk1-src/form-widgets.rst

+:ref:`integer <default-integer-widget>`, 
+:ref:`decimal <default-decimal-widget>`, 
+and :ref:`number string <number-string-widget>` widgets
+will display their values using locale-specific thousands separators.


Highlight limitation that . can't be used as a thousands separator and a space is used instead -- https://forum.opendatakit.org/t/odk-collect-v1-12-beta/10965/6

lognaturel · 2018-03-19T18:40:52Z

odk1-src/form-widgets.rst


-Acknowledge
-------------
+Default decimal widget


I think this order came from the All Widgets form and it's ok but it would make a bit more sense for me to have the plan integer and decimal widgets first followed by their variations.

that makes sense

lognaturel · 2018-03-19T18:44:40Z

odk1-src/form-widgets.rst


-URL Widget
-~~~~~~~~~~~~
+Range widgets allow the user to select numbers from within a range that is visually represented as a number line. The parameters of the range widget are defined by :tc:`start`, :tc:`end`, and :tc:`step` values defined in the :th:`parameters` column of your XLSForm. The parameter values can be integers or decimals.


as a number line or a spinner.

Edit: Hmm, looks like the picker appearance isn't in All Widgets. I just added it and would be good to document here.

Great. Will include --- I rely on all-widgets to know what's available...

lognaturel · 2018-03-19T19:09:39Z

odk1-src/form-widgets.rst


-Single Select Widgets
+Single select widget


Wondering whether it might be helpful to have a short introduction to selects with the text you have in the "Including Images as Choices" section below all the select widgets. Then it gives a good sense of the possibilities.

that makes sense. I'll try to make that work.

adammichaelwood · 2018-03-19T20:04:53Z

I'd like to see a little bit more narrative to help users figure out non-obvious characteristics of some of the widgets (e.g. the text widget expands vertically) and why certain widgets are useful (e.g. text with numbers appearance is useful for phone numbers).

Great. Will do.

I'm also finding the "See Also" notes a little disconnected from their section. I'd tend to put them above the screenshots.

Yeah, I wasn't sure of the best spot. I'll move them up.

How about scaling them as a percentage of the screen but no bigger than say 300 pixels wide or so? It would be great to get two on the same line where possible.

+1

lognaturel · 2018-03-19T21:05:05Z

Sounds great, I look forward to the next iteration!

adammichaelwood · 2018-03-20T16:26:19Z

This is ready for review again. I still need to run a style check and spelling pass over it myself,
but the things mentioned above have been addressed, and there is some restructure and added wayfinding.

adammichaelwood · 2018-03-20T17:15:52Z

note:

shrink images

adammichaelwood · 2018-03-21T00:21:45Z

This is (I think) ready to go...

yanokwa · 2018-03-21T04:52:48Z

This is really great, @adammichaelwood. I did find it hard to leave comments inline so my apologies! I've tried to arrange this top down and I'm glad to hop on a call tomorrow if it'd help.

In the intro, I'd add a hint that you can also use ODK Build to design forms graphically, but it doesn't give you the full range.

The ordering of the widgets are a bit strange to me. I'd order them as far as frequency of use..

Text widgets
Numerical widgets
Date and time widgets
Select widgets
GPS widgets
Image widgets
Audio widget
Video widget
Barcode widget
Range widgets
Note widget
URL widget
Printer widget
Trigger/acknowledge widget
Grouping multiple questions on the same screen

There is a multiline appearance that this doc is missing. It might be good to review http://xlsform.org/ref-table to make sure we have them all.

I think maybe the number string widget should be called the number text widget. We don't use string anywhere.

The integer widget has a limit of 9 digits, but the decimal widget has a limit of 14 digits or 15 characters (not digits).

You call it "Numeric appearance attributes" but you don't use attributes as a header elsewhere.

I'd rename GPS widgets to Location. More on this later.

I'd move bearing widget under GPS/Location, and not numeric. I don't think people think of it as a number.

I'd move signature widget up one level. I don't think people think of it as an image.

Under default image widget, you don't mention appearance in the title, but you do so in numeric appearance.

The barcode app is now called Barcode Scanner, not ZXing.

Audio Record should be Audio Recorder.

Sort the non-Gregorian calendars alphabetically. I don't know how you ordered it but it looks weird to me :)

Single select with search feature can probably drop the feature.

Multiselect should be multi select (I think).

Geopoint doesn't capture GPS always. Sometimes it's WiFi or fused. I'd say Location to be precise. You are missing a period after "Geopoint with user-selected location".

Including images as choices would feel better as the last item in the select list.

In Single Select menu, sometimes you say "Select" other times you "Select widget". I think it should be the latter to be consistent.

In ODK Aggregate, a completed...I'd drop the "In ODK Aggregate". I think it's stored as OK in the form XML.

Trigger acknowledgment widget widget as a repeated word. It might be good to search for "widget widget" to make sure it's not elsewhere.

There is a really big gotcha for grouping multiple question on a screen that should be noted here. See "fields dependent upon an earlier field are not being updated" section on https://opendatakit.org/help/form-design/workarounds/

adammichaelwood · 2018-03-22T19:30:26Z

I think i addressed just about everything above.

Couple points:

I tested multiline and it didn't change the actual appearance at all. So I didn't include it.
I'm not entirely happy with the awkwardness of the "questions depending on other questions" note, so if you have some better words for that, please volunteer them
i added meta as we discussed. Other reference items I've seen put the meta section at the top of the document, but I didn't. I can change that, of course. Also -- i don't know how I feel about wording in there, so feel free to suggest changes. (Always feel free, of course. But, you know -- especially.)
I switched "numeric" and "numerical" to "number" in most cases. There's a few where "numeric" seemed to fit better, but you might disagree.

yanokwa

This reads a lot better to me! Just a few more changes...

Under Location widgets

You use "GPS" position, but that isn't accurate. Sometimes it's WiFi or fused. I'd say Location to be precise.

Under Number text widget

The decimal widget has a limit of 14 digits (15 characters)

Under metadata

End is the time the survey was last saved, not completed.
Today is the current date according to the device (which we might want to note is sometimes totally incorrect)

Under grouping questions

Don't say swipe, since people might have buttons enabled. Say, determined when you move to the next screen.
If you don't listen to the advice, it won't fail. It will just cause very unpredictable and likely incorrect behavior. That is, sometimes it will work and sometimes it won't.

yanokwa · 2018-03-22T19:48:51Z

@lognaturel This isn't a blocker for merge, but has it always been the case that multiline does nothing on text boxes?

yanokwa · 2018-03-22T19:50:07Z

Nitpick, but per our definition, it should be Grouping multiple widgets, not questions on the same screen!

lognaturel · 2018-03-22T19:56:05Z

multiline does nothing on text boxes

That has always been the case. Collect uses the rows attribute, Enketo uses the multiline appearance. This is less relevant for Collect now because the text control just grows vertically as more text is entered.

adammichaelwood · 2018-03-22T20:07:46Z

per our definition, it should be Grouping multiple widgets, not questions on the same screen!

I thought about that, but then I thought.... maybe the whole screen of questions is one widget...

adammichaelwood · 2018-03-22T20:09:32Z

It will just cause very unpredictable and likely incorrect behavior.

I would call that a failure condition, no?

yanokwa · 2018-03-22T20:50:55Z

Failure implies that there will be something obvious that it has failed. I worry that people will think it's working when they swipe through, but it's failing subtly.

adammichaelwood · 2018-03-22T20:55:43Z

do you know if today is captured at start, end, completion, or some other time?

yanokwa · 2018-03-22T21:18:30Z

Today is captured when the widget is shown.

adammichaelwood · 2018-03-22T21:25:13Z

when the widget is shown.

Except it isn't visible. I'm using "rendered" unless you have a better suggestion...

yanokwa · 2018-03-22T21:33:35Z

odk1-src/form-widgets.rst

- :tc:`end` --- The time the survey was completed.
- :tc:`today` --- The date of survey collection.
+- :tc:`end` --- The last time the survey was saved.
+- :tc:`today` --- The current date, according to the device, when the survey is collected. (The date is determined when the widget is rendered.)


Ugh, now that I look at this, the meta widget isn't shown. Let's just drop the stuff in the parenthesis. Better to say nothing than say wrong stuff.

getodk-bot added the needs review label Mar 15, 2018

rewrite form widgets

dc8df72

adammichaelwood force-pushed the restructure-form-widgets branch from 7aa835d to dc8df72 Compare March 15, 2018 19:48

lognaturel reviewed Mar 19, 2018

View reviewed changes

getodk-bot added reviewed needs review and removed needs review reviewed labels Mar 19, 2018

address PR comments

05e873f

adammichaelwood added 6 commits March 20, 2018 15:10

image map work

a9b64e8

fix up image map section

5a46277

form list additions

39aea36

svg resources

3ecac65

spelling fixes

34a21b9

fix titling

c37e513

adammichaelwood changed the title ~~WIP: Restructure form widgets~~ Restructure form widgets Mar 21, 2018

adammichaelwood added 2 commits March 21, 2018 07:32

re-order widget sections

ac8c703

wrap up pr review

51e31ca

spelling fix

f8cbc9a

yanokwa reviewed Mar 22, 2018

View reviewed changes

nitpicky PR review issues

50a7a50

yanokwa reviewed Mar 22, 2018

View reviewed changes

remove note on 'today'

804da97

yanokwa approved these changes Mar 22, 2018

View reviewed changes

yanokwa merged commit 323dfa8 into getodk:master Mar 22, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Restructure form widgets #577

Restructure form widgets #577

adammichaelwood commented Mar 15, 2018 •

edited

Loading

lognaturel left a comment

lognaturel Mar 19, 2018

adammichaelwood Mar 19, 2018

lognaturel Mar 19, 2018

adammichaelwood Mar 19, 2018

lognaturel Mar 19, 2018

adammichaelwood Mar 19, 2018

lognaturel Mar 19, 2018

lognaturel Mar 19, 2018

lognaturel Mar 19, 2018

adammichaelwood Mar 19, 2018

lognaturel Mar 19, 2018

adammichaelwood Mar 19, 2018

lognaturel Mar 19, 2018

adammichaelwood Mar 19, 2018

adammichaelwood commented Mar 19, 2018

lognaturel commented Mar 19, 2018

adammichaelwood commented Mar 20, 2018 •

edited

Loading

adammichaelwood commented Mar 20, 2018

adammichaelwood commented Mar 21, 2018

yanokwa commented Mar 21, 2018

adammichaelwood commented Mar 22, 2018

yanokwa left a comment •

edited

Loading

yanokwa commented Mar 22, 2018 •

edited

Loading

yanokwa commented Mar 22, 2018

lognaturel commented Mar 22, 2018

adammichaelwood commented Mar 22, 2018

adammichaelwood commented Mar 22, 2018

yanokwa commented Mar 22, 2018

adammichaelwood commented Mar 22, 2018

yanokwa commented Mar 22, 2018

adammichaelwood commented Mar 22, 2018

yanokwa Mar 22, 2018


		This document is a list of available ODK :term:`Collect` :term:`form` :term:`widgets <widget>` (question types), with:

Restructure form widgets #577

Restructure form widgets #577

Conversation

adammichaelwood commented Mar 15, 2018 • edited Loading

What is included?

Any problems?

Work still to do?

lognaturel left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adammichaelwood commented Mar 19, 2018

lognaturel commented Mar 19, 2018

adammichaelwood commented Mar 20, 2018 • edited Loading

adammichaelwood commented Mar 20, 2018

adammichaelwood commented Mar 21, 2018

yanokwa commented Mar 21, 2018

adammichaelwood commented Mar 22, 2018

yanokwa left a comment • edited Loading

Choose a reason for hiding this comment

yanokwa commented Mar 22, 2018 • edited Loading

yanokwa commented Mar 22, 2018

lognaturel commented Mar 22, 2018

adammichaelwood commented Mar 22, 2018

adammichaelwood commented Mar 22, 2018

yanokwa commented Mar 22, 2018

adammichaelwood commented Mar 22, 2018

yanokwa commented Mar 22, 2018

adammichaelwood commented Mar 22, 2018

Choose a reason for hiding this comment

adammichaelwood commented Mar 15, 2018 •

edited

Loading

adammichaelwood commented Mar 20, 2018 •

edited

Loading

yanokwa left a comment •

edited

Loading

yanokwa commented Mar 22, 2018 •

edited

Loading