Though some key steps of coding configurations require technical skills, initial planning and consultation with project participants is essential to designing effective data structures and does not require coding skills.
To start the customization process, project participants should reflect on the project goals, what kind of data will be needed, and what properties might be required for data outputs.
If you have not already done so, work through the What information to collect? section of this guide as a first step.
When planning your configuration, you will need to think through what to include for each of the key customizable areas of Mapeo. The pages that follow will walk you through some considerations when determining content for each area:
Categories When collecting or creating data with Mapeo, users assign a top-level category to each observation or element on the map.
Icons Each category you include must have an icon, or a small graphic to display to users when selecting a category.
Details fields (optional) For each category in your configuration, you can include one or more structured data fields (like a mini form or questionnaire) that users can optionally fill out when creating a new observation or map element with that category.
Configurations can and often will evolve over time. As you begin collecting data, you will likely find categories, details fields and options you would like to add or modify. Unlike some other survey or data collection tools, Mapeo allows a lot of flexibility for changing configurations over time and does not require that the database be wiped when changes are made.
In order to create a Mapeo configuration file, the information you map out for the above areas will need to be translated into JSON
files and .svg
image files and then compiled. The details of this process will be covered in Coding configuration.
If you do not have the technical skills required to code the configuration yourself, the information you define in the following pages for for Categories, Icons and Details fields can be documented and passed off to a developer or individual with technical skills to code and compile the configuration file.
Each of the categories you include in your configuration needs to be assigned an icon, or a small graphic to display to users when selecting a category. You can assign the same icon to various cateogries, or each category can have it's own icon.
Examples of the icon files from our default configuration can be found here.
Though creating the .svg
icon files requires some knowledge of image editing tools, sketching and brainstorming ideas for icons can be a great way to involve community members and project participants who may not have technical skills. With paper and pencils, groups can come up with ideas for icons to represent each category in your project.
If you're not up for designing your own icon images, there are libraries of images online with Creative Commons licenses that you can draw from.
Icons are displayed as very small images in Mapeo Mobile (24x24px) and Mapeo Desktop (100x100px). Very simple designs with minimal detail will render more clearly to users.
When thinking about size and scale, imagine drawing your icons with a marker on a dime.
Bold and solid-color lines and shapes will be most clearly visible.
Once you've settled on the design or concept for your icons, you'll need to generate .svg
files required to include as part of the Coding configuration process.
To do so, you can use our online Mapeo Icons Generator, here.
Or, jump to Creating and exporting SVG files using Adobe Illustrator or Creating and exporting SVG files using Inkscape for technical guidelines in generating your own suitable SVG files.
If you do not have skills to prepare the digital icon files, paper sketches can be passed off to someone with technical skills to complete the steps of generating icon files, outlined in Coding configuration.
Categories list with icons in Mapeo Mobile (using the default configuration):
For each category in your configuration, you can include one or more structured data fields (like a mini form or questionnaire) that users can optionally fill out when creating a new observation or map element with that category. Details fields can be text fields (type in your own answer) or multiple choice (select one or select many from a set of pre-defined answers).
Details field screen displayed during data collection with Mapeo Mobile:
When planning your data structure, you should think through which (if any) details fields you would like to include for each category. The same details field can be used for many categories.
For each details field you would like to include, you'll need to define the following:
Label The primary text to be displayed to users ("Name" in the above image).
Placeholder A hint or subtext that can clarify the field to users or provide guidance on how to use it ("Common name of this place" in the above image).
Field type How users will be able to enter information for the field or question.
Text
or type in your own answer (Pictured in the image above)
Select one
from a list of options
Select multiple
from a list of options
Options
For Select one
and Select multiple
fields, you will need to define a list of possible answers to display.
It can be very challenging for users to type in detailed information when collecting data in the field. Users may be under significant stress, in risky situations, or interacting with the Mapeo screen in bright sun or rain. When creating Text
fields, keep in mind the conditions users will be facing and have reasonable expectations for the amount of detail and work required to fill out your details fields.
If there are a consistent set of answers you can anticipate for a field or question, it can be much faster or easier for users to select from a list as part of a Select one
or Select multiple
field. Please note that there is no automatic option for typing in information for "Other" or an option not included in the list.
It may be very clear to you when authoring your configuration what each details field means or intends to communicate. Keep in mind, however, who will be collecting data as part of your project and how they might read or interpret each field. Very clear and explicit language can go a long way towards ensuring your configuration is used as intended.
Mapeo Desktop currently allows you to filter observations by options in Select one
fields. To filter by options in Select multiple
or Text fields
, you will need to export your data and view it in another software tool.
All information you define for details fields will be formatted in JSON
in the Coding configuration process, detailed in the following section.
If you are not comfortable working with JSON, this information can be be passed off to someone with technical skills to complete the steps in Coding configuration.
When collecting or creating data with Mapeo, each observation or element on the map is assigned a category. Users must select a single category when creating a new observation or map element. Categories can be broad or specific, depending on your context and project needs.
Categories list in the Filters panel of Mapeo Desktop (using the default configuration):
For each category you choose to include in your configuration, you'll need to determine the following:
Name The label users will see in Mapeo when viewing or selecting the category
Geometry
Each element on the map will be marked as a
point
, line
(eg. a path), or area
(eg. a zone or lake). You will need to determine which of these geometries users will be able to use for each category.
All data collected with Mapeo Mobile will be points. If you are using Mapeo Mobile, you should include point
as a geometry for every category.
If you are using Mapeo Desktop Territory mode as part of your project, you can also include line
or area
for categories where relevant.
Color (optional) You have the option of setting a custom color for the map dots or markers for each category in Mapeo Mobile and Mapeo Desktop Observations mode.
Sort order (optional) You have the option of determining the order in which you would like categories to appear on the Mapeo Mobile Categories screen (pictured above). If no order is added, categories will appear alphabetically by name.
Categories are one of the key ways data can be filtered in Mapeo. Thinking through how you will view and use data once it has been created offers useful perspective when defining categories.
As a general rule, categories should not overlap - users should see only one option that fits when making a selection.
Categories and what would fall within them should be clear to those who will be collecting data. Training and information sessions may be critical for ensuring that project participants know how to gather data in consistent ways, but clarity and simplicity in configuration authoring goes a long way.
The space available to display category names is limited, especially in Mapeo Mobile, so names should be generally be brief.
All information you define for categories will be formatted in JSON
in the Coding configuration process, detailed in the following section.
If you are not comfortable working with JSON, this information can be be passed off to someone with technical skills to complete the steps in Coding configuration.
Categories list in Mapeo Mobile (using the default configuration):