In fields directory customize the .json files

Each .json file in the fields directory needs a key, type, label, and placeholder.

type can be one of select_multiple, select_one, or text.

For select_one and select_many fields, you will need to define an array of answer options.

Example fields file (name.json):

{
    "key": "name",
    "type": "text",
    "label": "Name",
    "placeholder": "Common name of this place"
}

Los archivos de configuración de Mapeo (.mapeosettings) se compilan a partir de un conjunto de archivos y carpetas que contienen toda la información que Mapeo necesita para mostrar las categorías, iconos y campos de detalles que usted desea que los usuarios vean al recolectar y ver datos. Esta sección lo guiará a través de la traducción de toda la información que ha definido en Planeando la configuración y la estructura de datos en un archivo de configuración de Mapeo.

Estructura de la carpeta de configuración

Para comenzar a preparar sus archivos, puede descargar o clonar nuestro repositorio de configuración predeterminado o este repositorio de configuración vacío de GitHub. Estos repositorios contienen los archivos y carpetas principales que necesitará para editar.

Al crear configuraciones personalizadas, editará archivos dentro de las siguientes carpetas de configuración:

• icons (iconos)

• fields (campos)

• presets (categorias)

Y los siguientes archivos de configuración:

• metadata.json

• defaults.json

• package.json

Preparar estructura de carpetas

Usando el explorador de archivos

1. Descargue el repositorio de configuración predeterminado o el repositorio de configuración vacío.

2. Descomprima el contenido en una nueva carpeta usando un programa como 7zip.

3. Cambie el nombre de la carpeta de "mapeo-default-settings" para usar su propio nombre de proyecto, "mapeo-config-projectname".

Usando el terminal (linux y mac) - línea de comandos

wget https://github.com/digidem/mapeo-default-settings/archive/v2.1.0.zip 
unzip v2.1.0.zip 
mv mapeo-default-settings-v2.1.0 mapeo-settings-myprojectname

The defaults.json file is currently used by Mapeo Desktop to determine which categories (presets) to list for each type of map geometry (point, line, area).

Before building your configuration, ensure that defaults.json includes an array of presets for each geometry that corresponds to the geometries you've listed in your preset files.

Example defaults.json file:

{
    "area": [
        "area", 
        "airstrip",
        "animal",
        "community",
        "fishing-site",
        "gathering-site",
        "hills",
        "hunting-site",
        "lake",
        "palm",
        "special-site",
        "swidden",
        "threat",
        "tree",
        "plant"
    ],
    "line": [
	"line",
	"boundary-line",
	"river",
	"path",
	"stream",
	"threat"
    ],
    "point": [
        "point",
        "airstrip",
        "animal",
        "boundary-line",
        "building",
        "camp",
        "clay",
        "community",
        "fishing-site",
        "gathering-site",
        "house",
        "hunting-site",
        "palm",
        "cave",
        "plant",
        "salt-lick",
        "waterfall",
        "special-site",
        "swidden",
        "threat",
        "tree"
    ],
    "vertex": [
    ],
    "relation": [
    ]
}

What is a Project Key?

In the metadata.json file in your Mapeo configuration, you can include a projectKey, which is a random cryptographic string of characters to prevent unwanted devices from getting access to the data.

Once a Mapeo Mobile or Mapeo Desktop device has imported a configuration with a project key, it can only sync with another Mapeo Mobile or Mapeo Desktop device that has the same project key.

You can edit the project key (for example, if you want to make first 4 characters identifiable to a project) but it can only contain letters a-f and numbers 0-9.

It can also only be 64 characters long -- no more, no less.

Creating a Project Key

To create a projectKey, first open the Terminal.

Using mapeo-settings-builder

Copy and paste the following command into the terminal

mapeo-settings-builder generate-key

You'll see something like this (but with x replaced with real characters and numbers)

'380c02d32xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx1d'

Copy this string and add it to the metadata.json file so it looks like this:

{
  "dataset_id": "mapeo-jungle",
  "projectKey": "380c02d32xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx1d"
}

Notice that there are double quotes " around each value.

In the presets directory, customize the .json files

In the presets directory, each .json file needs:

• icon must mach the name of an icon in the icons folder - use prefix only, excluding the size refernce and file extension (eg. for fishing-24px.svg/fishing-100px.svg use fishing).

• name will be the human-readable label shown to the user

• geometry must be an array of point ,area, and/or line (All categories for use in Mapeo Mobile must include point.)

• sort (optional) is an integer that will determine the order in which categories are displayed on the Categories screen of Mapeo Mobile. If no sort is included, categories will be listed alphabetically by name.

• an array of fields (optional) which should match the key created in the fields directory. Fields will be displayed to users in the order they are listed in the fields array.

• color (optional) determines the color of observation dots on the map. (Dots fall back to orange if no color is defined.) Value can be a hex code, CSS color name or any string supported by validate-color.

Example preset file (fishing-site.json):

{
    "icon": "fishing",
    "name": "Fishing Site",
    "sort": 10,
    "color": "#13D5CF",
    "fields": [
        "name"
    ],
    "geometry": [
        "point",
        "area"
    ]
}

Inkscape is a free and open-source vector graphics editor used to create vector images, primarily in Scalable Vector Graphics (.svg) format. Inkscape is an alternative to the commercial software Adobe Illustrator, and can be used to generate .svg files that work in Mapeo.

Using Inkscape to vectorize images

A common workflow for generating Mapeo icons is to find photos or other raster images, and turn them into vector images, simplifying them until they will render well at a small size. In Adobe Illustrator, this can be done using the Image Trace tool.

In Inkscape, this can be done using the Trace Bitmap tool found in the Path menu. There are some options to manipulate like Smoothing corners, Optimizing corners, and setting the number of colors.

Saving .svg files with the right size and Viewbox in Document Properties

Once you have a vector image that is to your satisfaction (and in a square format), you need to set the correct width & height and Viewbox size before saving the .svg file. You can do this in Document Properties (File menu).

First, set the Display units to pixels (px). This dropdown is located at the very top of the Document Properties menu.

Locate the "Custom Size" and "Scale" boxes in Document Properties.

First, you may need to set the unit of measurement for the Custom size, if it is not in pixels. If Units is in a format like milimeters (mm), change this to px.

Set the Width and Height to 100 each.

Next, the Viewbox needs to be set to 100 as well. The easiest way to do this — once you've set the Display units and Custom size units to pixels — is to set the Scale x to 1. It should copy over the Width and Height values from the Custom Size to the Viewbox. If that didn't do the trick, manually enter 100 for both Width and Height here.

Once you've done this, you may need to resize the art to match the full size of the Viewbox:

The easiest way to do this is to use the sizing and placement parameters right above the Viewbox, as shown in the screenshot above. Set W and H to 100 (px), and make sure X and Y are set to 0 (px). The image will then fill the entire Viewbox:

You can now save the .svg file by going to File → Save / Save As / Save A Copy.

Your .svg file should now be ready to be used by Mapeo. See #naming-icon-files for more information on how to name the files and where to place them in the configuration directory.

Verify that your SVG file is built correctly

It should have an initial <svg> tag with width and height set to 100, and viewBox set to "0 0 100 100."

After some tags like <defs>, <sodipodi:namedview>, <metadata>, which don't matter for the purposes of creating icons for Mapeo, you should see tags like <g> with layer properties, and a series of <path> with vertices and style properties, which constitute your vectors.

If your .svg file looks like this, the Mapeo configurations builder script should process your icons just fine.

Additional resources

• Troubleshooting SVG image errors in Mapbox Studio

Prepare computer for building the configuration

Mapeo is built with JavaScript programming language. To get started, you'll need to installdevelopment environment. If you already have Node.js installed you can skip this section.

You need to be at least on Node.js version 8 (or higher) for the mapeo-settings-builder to work properly. Head over to page and select installer for your operating system.

Alternatively you can also use NVM (Node Version Manager) to install and manage multiple versions of Node.js on your computer.

Install nvm

Then close terminal and open again

Install homebrew (macOS)

Install npm

Install and use node 12

Install Mapeo Settings Builder

You'll see output on the terminal, but this is OK

Is your computer ready?

If your computer is ready to create configurations, type

You should see output that looks something like

Now you're ready to move to build your configuration!

Package Config Assets for MAPEO

Prep folder and build

Type, 'cd`, then a space, then drag and drop the folder where the prepared assets are and press enter. It will look something like this

You will then be ready to run scripts directly in the folder.

This -s tells npm to be silent, so that you only see errors that are meaningful to you.

You will see something like the following output. Errors will be highlighted in RED with hopefully some helpful description so that you can remedy the issue.

You'll also see a .mapeosettings file inside of the build directory.

What is a .mapeosettings file?

A .mapeosettings file is a tar file, similar to a zip file. You can see the contents of the file by changing the file extension to .tar and using any application that can extract tar files (such as 7zip, mentioned above).

Troubleshooting Checklist

Type the following into the terminal

You need to be at least on Node version 8 for the mapeo-settings-builder to work properly. If you need help, review the 'Preparing Computer' section and ensure you're on the latest version of mapeo-settings-builder.

You also may want to delete node_modules and install updated versions of the dependencies.

In Mac or Linux, in the terminal:

Versioning

Una vez que se haya decidido por el diseño o el concepto de sus íconos, deberá generar archivos .svg para que cada uno se guarde en el directorio de icons. Los iconos deben crearse como gráficos de 100x100 píxeles que sean claros cuando se visualizan al 100 %.

Actualmente, hemos documentado dos flujos de trabajo para generar archivos .svg compatibles con Mapeo mediante software, uno con un producto comercial (Adobe Illustrator) y otro con un producto de código abierto (Inkscape).

Nombrar archivos de iconos

Los iconos deben ser leídos por MAPEO en dos tamaños: 100 píxeles y 24 píxeles. Por ese motivo, existe una convención de nomenclatura de archivos específica:

• nombre-icono-100px.svg

• nombre-icono-24px.svg

Cada icono se puede duplicar y renombrar para que haya uno de cada tamaño. Son abiertos y leídos por los archivos .json en la carpeta de presets. Verifique que el nombre se haya ingresado correctamente donde sea necesario (más sobre esto en la siguiente sección). El script de compilación procesará el sufijo de tamaño de píxel.

Recursos adicionales

It is possible to build a Mapeo configuration file using GitHub Actions. This requires setting up your custom configuration directory as a repository on , adding a /.github/workflows/build.yml script to your repository, and committing changes to that repository.

Setting up a configuration repository on GitHub

The first step will be to set up your configuration as a repository on github.com, with the requisite build script files that will trigger a GitHub Actions Workflow to generate your .mapeosettings file. There are a few ways to do this.

If you do not have your own custom configuration already, and are starting from scratch:

1. You can fork or upload either the or the template to your own GitHub account. The choice you make will depend on how you will go about creating your own configuration, as detailed in .

2. Make sure that you have the .github/workflows directory in your configuration repository.

If you already have your own custom configuration:

1. Create a repository on GitHub for your custom configuration.

2. Commit your existing configuration content to the repository.

3. Download either the or the , and copy over the .github directory to the root directory of your custom configuration.

4. Commit these files to your repository on Github.com. (Github may ask you for additional permissions to add these files, by confirming via the browser.)

Getting ready to build

Navigate to the Actions screen, and Click "I understand my workflows, go ahead and enable them."

This will bring you to a view of your Workflows. You should see a message "There are no workflow runs yet" if you just enabled Workflows for the first time. You are now ready to start building .mapeoconfig files.

How it works

Once you have enabled Action Workflows on your configuration repository, GitHub will generate a Workflow to build a new version of your configuration every single time that you commit a change to your repository.

Once you have committed a change to your repository, and navigate to the Actions tab, you should see your commit message listed as a workflow.

You can click on your commit message to find out more about the status of your build. For example, if your build has encountered an error, there will be a log that can give you an idea of what went wrong. You can commit a change to fix the error, and return to the Actions screen to see if a new Workflow successfully bypasses the problem.

Use conventional commit messages to increment your configuration version

• feat: this will increase your version to 1.2.0. This commit prefix could be used for major configuration updates.

• fix: this will increase your version to 1.1.1. This commit prefix could be used for small updates like changing an icon, or adding a field to a category.

• chore: this will not increase your version. This commit prefix could be used for correcting typos or fixing errors.

You can also manually update the first number in your 1.1.0 version in your package.json file, but Digital Democracy's convention is to only do so to indicate breaking changes. That said, you are free to choose a versioning convention that makes the most sense to you.

Compile a final, versioned release of your configuration

• Navigate to the Actions tab for your GitHub repository. You should see all of your Workflows again.

• On the left sidebar, click on the Build & Release link.

• You should now see a box with the text "This workflow has a workflow_dispatch event trigger" and a button Run workflow. Click the button, and then click Run workflow again in the popup that will appear.

• Doing so will trigger another Workflow titled "Build and Release."

• Click on the release to download the versioned .mapeosettings file.

Compiling your configuration into a .mapeosettings file is the final step for testing and using your configuration in Mapeo Mobile and Desktop.

Building a configuration can be done in two ways:

• Via the command line(with Node.js and mapeo-settings-builder)

• Using GitHub Actions

The package.json file stores the name and version information users will see in Mapeo when using the configuration.

Edit the name and version properties when creating a new configuration. Additional information on incrementing versions will be covered in Building configuration file.

You can also add description, author, and license information to this file but these properties will not be rendered in the Mapeo interface.

Example package.json file:

{
  "name": "project-config",
  "version": "1.0.0",
  "description": "Mapeo configuration",
  "dependencies": {
    "mapeo-settings-builder": "^3.0.0",
    "mkdirp": "^0.5.1"
  },
  "devDependencies": {},
  "scripts": {
    "build": "basename=\"${npm_package_name}-v${npm_package_version}\"; mkdirp build/${basename}; mapeo-settings build -l 'en' -o build/${basename}.mapeosettings && tar -C \"build/${basename}\" -xf build/${basename}.mapeosettings",
    "test": "mapeo-settings lint"
  },
  "author": "Your Name",
  "license": "UNLICENSED",
  "private": true
}

Adobe Illustrator es un editor de gráficos vectoriales y un programa de diseño desarrollado por Adobe Inc. Aunque es un producto comercial con licencia, se usa muy comúnmente para crear gráficos vectoriales, y muchos usuarios también utilizan esta herramienta para crear íconos para Mapeo.

Exportar archivos .svg con las propiedades adecuadas

Cuando esté listo para exportar un archivo gráfico vectorial a un formato de archivo .svg compatible con Mapeo, el proceso es el siguiente:

• En el menú superior de Adobe Illustrator, haga clic en Archivo y luego seleccione Exportar, seguido de Exportar como.

• Asegúrese de que Use Artboards esté marcado.

• Guarde su archivo .svg en el directorio correcto (icons para las configuraciones de Mapeo) y con el nombre de archivo deseado, y haga clic en Exportar.

• En la siguiente ventana, asegúrese de que las siguientes propiedades estén configuradas y luego haga clic en Aceptar:

Su archivo .svg ahora debería estar listo para ser utilizado por Mapeo. Consulte #naming-icon-files para obtener más información sobre cómo nombrar los archivos y dónde colocarlos en el directorio de configuración.