Using form based notes

Geopaparazzi supports complex notes called form based notes. To use them, a tags.json file needs to be created and placed inside the geopaparazzi folder inside the sdcard. In that file a json format description of the wanted tags and forms needs to be placed.

By default, to help the user to start, a sample tags.json is created in the Geopaparazzi installation. It contains form samples and examples to show all supported form widgets.

_images/01_tags.png

Currently no tool is available to create forms in an interactive way, they have to be created manually.

A good online tool to at least validate your json form is the Json Lint Validator. Make sure it passes that test before putting it on the device and test it in geopaparazzi.

Supported tags (via the example form)

The example form that is available by default shows all the possible options available.

Text

Looks like Created by
_images/02_text.png
      "formname": "text",
      "formitems": [
          {
              "key": "some text",
              "value": "",
              "type": "string"
          }
      ]

Text with key and label

In simple forms the key element is also used as label for the widget (ex. some text in the text note). Some charactersets are not suitable to be used as keys for a database, so in that cases the user should consider to define both the key (ex. in English) and the label (in the own language). Here an example:

Looks like Created by
_images/03_text_key.png
      "formname": "multiple text",
      "formitems": [
          {
              "key": "some text",
              "value": "text1; text2; text3",
              "type": "dynamicstring"
          }
      ]
  },{

Numbers

Looks like Created by
_images/04_numeric.png
      "formitems": [
          {
              "key": "the_key_used_to_index",
              "label": "the label used to describe",
              "value": "",
              "type": "string"
          }
      ]
  },{
      "formname": "numeric text",
      "formitems": [
          {

Labels rendered in the map view

Text and numbers can also be shown as labels in the map view.

To do so, the tag islabel has to be added and set to true:

                        "value": "",
                        "type": "double"
                    },{
                        "key": "an integer number",
                        "value": "",
                        "type": "integer"
                    }
                ]
            },{
                "formname": "numeric text used as label in map",
                "formitems": [
                    {
                        "key": "a number",

Only one text or number item is accepted as label, so if more than one is added, the last read will be picked.

Date

Looks like Created by
_images/05_date.png
              "islabel": "true",
              "type": "double"
          },{
              "key": "an integer number",
              "value": "",
              "type": "integer"
          }
      ]

Time

Looks like Created by
_images/06_time.png
      "formname": "date",
      "formitems": [
          {
              "key": "a date",
              "value": "",
              "type": "date"
          }
      ]

Labels

Looks like Created by
_images/07_labels.png
      "formname": "time",
      "formitems": [
          {
              "key": "a time",
              "value": "",
              "type": "time"
          }
      ]
  },{
      "formname": "labels",
      "formitems": [
          {
              "value": "a simple label of size 20",
              "size": "20",
              "type": "label"
          },{
              "value": "a underlined label of size 24",

Checkbox

Looks like Created by
_images/08_boolean.png
              "type": "labelwithline"
          },{
              "value": "a label with link to the geopaparazzi homepage",
              "url": "http://www.geopaparazzi.eu",
              "size": "20",
              "type": "labelwithline"
          }
      ]

Combos

Looks like Created by
_images/09_combos.png
      "formname": "boolean",
      "formitems": [
          {
              "key": "a boolean choice",
              "value": "",
              "type": "boolean"
          }
      ]
  },{
      "formname": "combos",
      "formitems": [
          {
              "key": "a single choice combo",
              "values": {
                  "items": [
                      {"item": ""},
                      {"item": "choice 1"},
                      {"item": "choice 2"},
                      {"item": "choice 3"},
                      {"item": "choice 4"},
                      {"item": "choice 5"}
                  ]
              },
              "value": "",
              "type": "stringcombo"
          },{
              "key": "a multiple choice combo",
              "values": {
                  "items": [
                      {"item": ""},
                      {"item": "choice 1"},
                      {"item": "choice 2"},
                      {"item": "choice 3"},
                      {"item": "choice 4"},
                      {"item": "choice 5"}
                  ]
              },
              "value": "",
              "type": "multistringcombo"
          },{
              "key": "two connected combos",
              "values": {
                  "items 1": [
                      {"item": ""},
                      {"item": "choice 1 of 1"},
                      {"item": "choice 2 of 1"},
                      {"item": "choice 3 of 1"},
                      {"item": "choice 4 of 1"},
                      {"item": "choice 5 of 1"}
                  ],
                  "items 2": [
                      {"item": ""},
                      {"item": "choice 1 of 2"},
                      {"item": "choice 2 of 2"},
                      {"item": "choice 3 of 2"},
                      {"item": "choice 4 of 2"},
                      {"item": "choice 5 of 2"}
                  ]
              },
              "value": "",
              "type": "connectedstringcombo"
          },{
              "key": "two connected combos, default selected",
              "values": {
                  "items 1": [
                      {"item": ""},
                      {"item": "choice 1 of 1"},
                      {"item": "choice 2 of 1"},
                      {"item": "choice 3 of 1"},
                      {"item": "choice 4 of 1"},
                      {"item": "choice 5 of 1"}
                  ],
                  "items 2": [
                      {"item": ""},
                      {"item": "choice 1 of 2"},
                      {"item": "choice 2 of 2"},

Pictures

Looks like Created by
_images/10_pictures.png
                      {"item": "choice 4 of 2"},
                      {"item": "choice 5 of 2"}
                  ]
              },
              "value": "choice 4 of 2",
              "type": "connectedstringcombo"
          }
      ]

Sketches

Looks like Created by
_images/11_sketches.png
      "formname": "pictures",
      "formitems": [
          {
              "key": "a picture archive",
              "value": "",
              "type": "pictures"
          }
      ]

Map screenshot

Looks like Created by
_images/12_map.png
      "formname": "sketches",
      "formitems": [
          {
              "key": "a sketches archive",
              "value": "",
              "type": "sketch"
          }
      ]

Other supported tags

hidden

Not shown in the gui, but useful for the application to fill in infos like the GPS position:

{"key":"LONGITUDE", "value":"", "type":"hidden"}

primary_key

An item of particular importance, can be used by the application to link to particular infos:

{"key":"tourism", "value":"", "type":"primary_key"}

Constraints

Constraints are conditions that are checked when the ok button of the form is pushed.

mandatory

To make an item mandatory, just add:

"mandatory": "yes"

range

To peform a range check on a numeric field you can add something like:

"range":"[0,10)"

which would check that the inserted number is between 0 (inclusive) and 10 (exclusive).

Create a simple form to map fountains

As an excercise we will now create a simple form to map fountains.

Sections

Every form is composed of sections, each of which create a button in the add notes view.

We want to create a form for a fountain, so one section is enough.

The blueprint for such a form, i.e. the empty button shell starts with:

[
    {
        "sectionname": "fountain",
        "sectiondescription": "fountain",
        "forms": [

and ends with:

        ]
    }
]

Form subsections

Each section can contain several sub-forms, that will create a tab each.

A sub-form starts with:

            {
                "formname": "General data",
                "formitems": [

and ends with:

                ]
            },

Note that the comma at the end is only needed if more than one sub-form is added.

Form elements

To add content to the sub-forms, any of the tags described in the supported tags section can be used.

For example lets add two textfields to prompt the user for a name and street. Also the name should then be the label rendered in the map view.

                    {
                        "key": "name",
                        "value": "",
                        "islabel": "true",
                        "type": "string",
                        "mandatory": "yes"
                    },
                    {
                        "key": "street",
                        "value": "",
                        "type": "string",
                        "mandatory": "no"
                    }

Finalize the form

This is everything that needs to be done. Let’s also add some technical data in a dedicated tab and also a tab for media, inside which it is possible to take pictures.

We leave the exercise to the reader.

Here below the tags file of a possible implementation is presented:

[
    {
        "sectionname": "fountain",
        "sectiondescription": "fountain",
        "forms": [
            {
                "formname": "General data",
                "formitems": [
                    {
                        "key": "name",
                        "value": "",
                        "islabel": "true",
                        "type": "string",
                        "mandatory": "yes"
                    },
                    {
                        "key": "street",
                        "value": "",
                        "type": "string",
                        "mandatory": "no"
                    }
                ]
            },
            {
                "formname": "Technical data",
                "formitems": [
                    {
                        "key": "protected",
                        "value": "true",
                        "type": "boolean",
                        "mandatory": "no"
                    },
                    {
                        "key": "type",
                        "values": {
                            "items": [
                                {
                                    "item": ""
                                },
                                {
                                    "item": "manual"
                                },
                                {
                                    "item": "electrical"
                                },
                                {
                                    "item": "gravity"
                                }
                            ]
                        },
                        "value": "manual",
                        "type": "stringcombo",
                        "mandatory": "no"
                    },
                    {
                        "key": "PH",
                        "values": {
                            "items": [
                                {
                                    "item": ""
                                },
                                {
                                    "item": "PH < 5"
                                },
                                {
                                    "item": "5 < PH < 7"
                                },
                                {
                                    "item": "PH > 7"
                                }
                            ]
                        },
                        "value": "PH < 5",
                        "type": "stringcombo",
                        "mandatory": "no"
                    },
                    {
                        "key": "number of served people",
                        "value": "",
                        "type": "double",
                        "mandatory": "no"
                    },
                    {
                        "key": "is working",
                        "value": "true",
                        "type": "boolean",
                        "mandatory": "no"
                    },
                    {
                        "key": "needs",
                        "values": {
                            "items": [
                                {
                                    "item": ""
                                },
                                {
                                    "item": "nothing"
                                },
                                {
                                    "item": "maintainance"
                                },
                                {
                                    "item": "rehabilitation"
                                }
                            ]
                        },
                        "value": "nothing",
                        "type": "stringcombo",
                        "mandatory": "no"
                    }
                ]
            },
            {
                "formname": "Media",
                "formitems": [
                    {
                        "key": "Images",
                        "value": "",
                        "type": "pictures",
                        "mandatory": "no"
                    }
                ]
            }
        ]
    }
]