EdenMobile Data Formats

Form List

• tbd

Form Download

Table Schema

The table schema describes the field in the table.

The field name, type and label are read from the web2py Field instance directly.

The field type will determine the choice of widget in the mobile app. This default widget decision can be overridden by Field.s3_settings["mobile"].

For dynamic tables, Field.s3_settings will be established from s3_field.settings. The format for both is identical.

Field.s3_settings = s3field.settings = {

   // must be JSON-seriablizable

   "mobile": {            <== the mobile-specific section in the field settings, will be send to EdenMobile

      "widget": {
          "type": widget-type,       <== must be a widget-type name supported by EdenMobile (if an unknown widget type is set, no widget will be shown at all!)
          ...                        <== other widget options as key-value pairs
      },
      "requires": {
          validatorName: {parameters}              <== general format: parameters for the validator must be passed as dict, all parameters are optional
          "isIntInRange": {"min": 0, "max": 100},  <== example: mobile-specific validator (instant validation!)
          "isNotEmpty": {}                         <== require field to be filled if visible
      },
      "l10n": {                                    <== localized strings for the field (label, comment)
          "es": {
              "label": "...spanish translation of the label...",
              "comment": "...spanish translation of the comment...",
          }
      },
      "image": {
          "url": "...download-URL of the image for this widget..."
      },
      "pipeImage": {
          // format to be defined
      }
   }
}

NB In future, the field settings will fall back to values introspected from the web2py Field instance (requires/widget/represent), but this does not happen yet, so it is essential to configure the "mobile" section in the settings for EdenMobile to handle the field correctly. If no mobile settings are provided, EdenMobile will assume defaults, which may differ from what is configured for the field on the server!

Widget-specific Configurations

Likert-scale

• Field is type "string"

Field settings to use pre-defined scales (app-specific):

"mobile": {
    "widget": {
        "type": "likert",
        "scale": "appropriateness"|"confidence"|"frequency"|"safety"|"satisfaction"|"smiley-5"|"smiley-3"
    }
}

• predefined scale sets field options (override!) and option<=>icon mapping

Field settings to use custom scale:

"mobile": {
    "widget": {
        "type": "likert",
        "icons": [[option, "icon-css-class"], ...],
        "iconsOnly": true|false
    }
}

• with custom scale, the field must have options defined
• scales without icons-only are rendered as standard vertical radio list (single-select)
• scales with icons-only are rendered as horizontal radio bar with icons

Form Description

The form description is a JSON array with form elements.

If the mobile_form table setting on the server is a Python list, it will be used as-is. Otherwise, if the mobile_form setting is a S3SQLCustomForm instance, then it will be converted into such an list (with every S3SQLFormElement corresponding to one entry in the list).

The general format:

[
    "fieldA",                   <== String indicates a field name

    // Form element type S3SQLField
    {"type": "input",           <== Non-string elements must be objects and have a "type"-attribute
     "field": "fieldB",         <== Form element of type "input" must specify a "field" attribute with the field name
     ...,                       <== Other parameters in key-value format for the form element (e.g. display logic)
     },

    // Form element type S3SQLInstruction
    {"type": "instructions",    <== A non-field form element "instructions", will show instructions to the form user
     "do": "...string...",      <== String with instruction what to do
     "say": "...string...",     <== String with example what to say (will automatically be quoted, so no need to quote it)
     "l10n": {
         "es": {                                              <== localized instruction, language-code as attribute name
             "do": "...do-instruction in Spanish...",
             "say": "...say-instruction in Spanish..."
         }
     },

     // Form element type S3SQLSectionBreak
     {"type": "section-break"}  <== A non-field form element that marks a section/page break in the form

     // Form element type S3SQLSubHeading (<= yet to be implemented)
     {"type": "subheading",
      "text": "...subheading...",
      "l10n": {
          "es": {
              "text": "...spanish translation of the subheading text..."
          }
      }
]

Display Logic

Every form element (except section breaks) can have an entry "displayLogic" - which determines when the form element is to be shown.

Format:

    {"type": "input"
     "field": "fieldname",
     "displayLogic": {"field": <fieldname>, op: value}        <== single condition display logic, op = eq|ne|lt|gt|le|ge, 
                                                                  multiple op-value-pairs can be specified (all must apply = AND)
     }

     More complex expressions:

     "displayLogic": [{...cond...}, {...cond...}]                                        <== multi-condition display logic, AND assumed
     "displayLogic": ["anyOf", {...cond...}, {...cond...}]                               <== multi-condition display logic, explicit OR
     "displayLogic": ["allOf", ["anyOf", {...condA...}, {...condB...}], {...condC...}]   <== nested multi-condition display logic, translates to "(condA or condB) and condC"

Data Upload

• uses regular S3JSON via REST API, no specifics