= EdenMobile Data Formats =
[[TOC]]

== 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!)
      },
      "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!

=== 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|in|has (in=belongs, has=contains)
     }

     More complex conditions:

     "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