Resumen del proceso

Hay varios pasos para crear una configuración personalizada que requerirán diferentes habilidades y la participación de diferentes actores dentro de un proyecto. Debe dejar suficiente tiempo antes del inicio previsto de la recopilación de datos para permitir la consulta, las pruebas y las iteraciones de su configuración por parte de la comunidad.

Si bien las estructuras de datos en Mapeo se pueden modificar durante el curso de un proyecto, muchos cambios a lo largo del tiempo pueden generar datos desordenados. Vale la pena probar y refinar su configuración en la medida de lo posible antes de ponerla en uso para la recopilación de datos.

Una vez que haya completado este proceso, tendrá un archivo de configuración de Mapeo (.mapeosettings) que se puede importar y usar en Mapeo Mobile y Destop.

Las siguientes páginas lo guiarán a través de los pasos clave para crear una configuración personalizada:

• Planeando la configuración y la estructura de datos Esta sección describirá los elementos personalizables clave en una configuración y algunas consideraciones al trazar cada área. *No se requieren conocimientos técnicos.

• Codificar la configuración Esta sección lo guiará para adaptar de la estructura de datos planificada al formato requerido para su proyecto y la compilación del archivo de configuración de Mapeo. *Es necesario editar archivos JSON, generar archivos .svg y trabajar con la línea de comandos o GitHub.

Acerca de las configuraciones personalizadas

Las configuraciones personalizadas son una poderosa herramienta para la personalización en Mapeo, que permite a los usuarios definir categorías, íconos y cuestionarios específicos para sus proyectos. La categoría personalizada y el texto del cuestionario se pueden escribir en cualquier idioma que se pueda escribir, lo que garantiza que las partes clave de la interfaz de recopilación de datos de Mapeo puedan aparecer en el idioma nativo de los grupos que la utilizan.

En la versión actual de Mapeo, las configuraciones también contienen una clave de proyecto que permite a los participantes del mismo proyecto de Mapeo sincronizar datos entre sí y evita la sincronización con otros dispositivos.​

Creación de configuraciones personalizadas

Si ha identificado que la de Mapeo no se adapta a las necesidades de su proyecto, tiene la opción de crear una configuración personalizada.

El proceso de personalización, detallado en , requiere familiaridad y conocimientos para editar archivos JSON, generar archivos de imagen SVG y usar acciones de GitHub o instalar y usar paquetes de nodos a través de la línea de comandos.

¿Qué son las categorías?

Al recopilar o crear datos con Mapeo, a cada observación o elemento del mapa se le asigna una categoría. Los usuarios deben seleccionar una sola categoría al crear una nueva observación o elemento de mapa. Las categorías pueden ser amplias o específicas, según el contexto y las necesidades del proyecto.

¿Cómo se ven las categorías en Mapeo?

El listado de categorías en Mapeo Mobile (usando la configuración predeterminada):

Listado de categorías en el panel de Filtros de Mapeo Desktop (usando la configuración predeterminada):

Consideraciones al definir categorías

Para cada categoría que elija incluir en su configuración, deberá determinar lo siguiente:

• Nombre La etiqueta que verán los usuarios en Mapeo al visualizar o seleccionar la categoría

• Geometría Cada elemento en el mapa se marcará como un punto, línea (p. ej., un camino) o área (p. ej., una zona o un lago). Deberá determinar cuál de estas geometrías podrán usar las personas usuarias para cada categoría.

  • Todos los datos recopilados con Mapeo Mobile serán puntos. Si está utilizando Mapeo Mobile, debe incluir punto como geometría para cada categoría.

  • Si utiliza el modo Territorio de Mapeo Desktop como parte de su proyecto, también puede incluir una línea o un área para las categorías cuando corresponda.

• Color (opcional) Tiene la opción de establecer un color personalizado para los puntos o marcadores del mapa para cada categoría en el modo de observaciones de Mapeo Mobile y Mapeo Desktop.

• Orden de clasificación (opcional) Tiene la opción de determinar el orden en el que desea que aparezcan las categorías en la pantalla Categorías de Mapeo Mobile (en la imagen de arriba). Si no se agrega ningún orden, las categorías aparecerán en orden alfabético por nombre.

Al definir categorías, tenga en cuenta lo siguiente:

• Las categorías son una de las formas clave en que se pueden filtrar los datos en Mapeo. Pensar en cómo verá y usará los datos una vez que se hayan creado ofrece una perspectiva útil al definir categorías.

• Como regla general, las categorías no deben superponerse: los usuarios deben ver solo una opción que se ajuste al hacer una selección.

• Las categorías y lo que caería dentro de ellas deben ser claro para quienes recopilarán datos. Las sesiones de capacitación e información pueden ser críticas para garantizar que las personas participantes del proyecto sepan cómo recopilar datos de manera consistente, pero la claridad y la simplicidad en la creación de configuraciones son de gran ayuda.

• El espacio disponible para mostrar los nombres de las categorías es limitado, especialmente en Mapeo Mobile, por lo que, en general, los nombres deben ser breves.

Generación de archivos de categoría

Toda la información que defina para las categorías se formateará en JSON en el proceso Codificar la configuración, que se detalla en la siguiente sección.

¿Qué es un icono?

Cada una de las categorías que incluya en su configuración debe tener asignado un icono o un pequeño gráfico para mostrar a los usuarios al seleccionar una categoría. Puede asignar el mismo ícono a varias categorías, o cada categoría puede tener su propio ícono.

¿Cómo se ven los íconos en Mapeo?

Listado de categorías con iconos en Mapeo Mobile (usando la configuración predeterminada):

Puede encontrar ejemplos de los archivos de iconos de nuestra configuración predeterminada .

Consideraciones al diseñar iconos

Si bien la creación de los archivos de íconos .svg requiere cierto conocimiento de las herramientas de edición de imágenes, esbozar y generar ideas para los íconos puede ser una excelente manera de involucrar a los miembros de la comunidad y a los participantes del proyecto que pueden no tener habilidades técnicas. Con papel y lápices, los grupos pueden generar ideas para íconos que representen cada categoría en su proyecto.

Si no está preparado para diseñar sus propias imágenes de íconos, hay bibliotecas de imágenes en línea con licencias Creative Commons que puede utilizar.

Al diseñar iconos, tenga en cuenta lo siguiente:

• Los iconos se muestran como imágenes muy pequeñas en Mapeo Mobile (24x24px) y Mapeo Desktop (100x100px). Los diseños muy simples con detalles mínimos se mostrarán más claramente a los usuarios.

  • Cuando piense en el tamaño y la escala, imagine dibujar sus íconos con un marcador en una moneda de diez centavos.

• Las líneas y formas en negrita y de colores sólidos serán más claramente visibles.

Generación de archivos de iconos

¿Qué son los campos de detalles?

Para cada categoría en la configuración, puede incluir uno o más campos de datos estructurados (como un mini formulario o cuestionario) que los usuarios pueden completar opcionalmente al crear una nueva observación o elemento de mapa con esa categoría.

Los campos de detalles pueden ser campos de texto (escriba su propia respuesta) o de opción múltiple (seleccione una o varias de un conjunto de respuestas predefinidas).

¿Cómo se ven los campos de detalles en Mapeo?

Pantalla de campo de detalles que se muestra durante la recopilación de datos con Mapeo Mobile:

Consideraciones al definir campos de detalles

Al planificar su estructura de datos, debe pensar qué campos de detalles (si corresponde) le gustaría incluir para cada categoría. El mismo campo de detalles se puede utilizar para muchas categorías.

Para cada campo de detalles que desee incluir, deberá definir lo siguiente:

• Etiqueta El texto principal que se mostrará a los usuarios ("Nombre" en la imagen de arriba).

• Marcador de posición Una pista o subtexto que puede aclarar el campo a los usuarios o brindar orientación sobre cómo usarlo ("Nombre común de este lugar" en la imagen de arriba).

• Tipo de campo Cómo los usuarios podrán ingresar información para el campo o pregunta.

  • Escriba su propia respuesta en texto (en la imagen de arriba)

  • Seleccione uno de una lista de opciones

  • Seleccione varios de una lista de opciones

  • Opciones Para los campos Seleccionar uno y Seleccionar varios, deberá definir una lista de posibles respuestas para mostrar.

Al definir campos de detalles, tenga en cuenta lo siguiente:

• Puede ser muy difícil para los usuarios escribir información detallada al recopilar datos en el campo. Los usuarios pueden estar bajo un estrés significativo, en situaciones de riesgo o interactuando con la pantalla de Mapeo bajo el sol o la lluvia. Al crear campos de texto, tenga en cuenta las condiciones a las que se enfrentarán las personas usuarias y tenga expectativas razonables sobre la cantidad de detalles y el trabajo necesarios para completar sus campos de detalles.

• Si hay un conjunto consistente de respuestas que puede anticipar para un campo o pregunta, puede ser mucho más rápido o más fácil para los usuarios seleccionar de una lista como parte de un campo Seleccionar uno o Seleccionar varios. Tenga en cuenta que no hay una opción automática para escribir información para "Otro" o una opción no incluida en la lista.

• Puede ser muy claro para usted al crear su configuración lo que cada campo de detalles significa o pretende comunicar. Sin embargo, tenga en cuenta quiénes recopilarán datos como parte de su proyecto y cómo podrían leer o interpretar cada campo. Un lenguaje muy claro y explícito puede contribuir en gran medida a garantizar que su configuración se utilice según lo previsto.

• Mapeo Desktop actualmente le permite filtrar las observaciones por opciones en los campos Seleccionar uno. Para filtrar por opciones en los campos Seleccionar varios o campos de texto, deberá exportar sus datos y verlos en otra herramienta de software.

Generación de archivos de campo de detalles

Aunque algunos pasos clave de la codificación de configuraciones requieren habilidades técnicas, la planificación inicial y la consulta con las personas participantes del proyecto son esenciales para diseñar estructuras de datos efectivas y no requieren habilidades de codificación.

Para comenzar el proceso de personalización, las personas participantes del proyecto deben reflexionar sobre los objetivos del proyecto, qué tipo de datos se necesitarán y qué propiedades podrían requerirse para los datos de salida.

Si aún no lo ha hecho, siga la sección de la guía como primer paso.

Estructura de datos

Al planificar su configuración, deberá pensar en qué incluir para cada una de las áreas personalizables de Mapeo. Las siguientes páginas lo guiarán a través de algunas consideraciones al determinar el contenido de cada área:

• Al recopilar o crear datos con Mapeo, los usuarios asignan una categoría de nivel superior a cada observación o elemento del mapa.

• Cada categoría que incluya debe tener un icono o un pequeño gráfico para mostrar a los usuarios al seleccionar una categoría.

• (opcional) Para cada categoría en su configuración, puede incluir uno o más campos de datos estructurados (como un mini formulario o cuestionario) que los usuarios pueden completar opcionalmente al crear una nueva observación o elemento de mapa con esa categoría.

Documentación de la estructura de datoso

Para crear un archivo de configuración de Mapeo, la información que asigne para las áreas anteriores deberá traducirse a archivos JSON y archivos de imagen .svg y luego compilarse. Los detalles de este proceso se cubrirán en .

Si no tiene las habilidades técnicas necesarias para codificar la configuración usted mism@, la información que defina en las siguientes páginas para , y se puede documentar y pasar a una persona desarrolladora o persona con habilidades técnicas para codificar y compilar el archivo de configuración.

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 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 o este 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 o el .

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

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

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": [
    ]
}

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).

• Crear y exportar archivos SVG usando Adobe Illustrator

• Crear y exportar archivos SVG usando 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

• Troubleshooting SVG image errors in Mapbox Studio

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"
}

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 .

Example preset file (fishing-site.json):

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.

Prepare computer for building the configuration

Mapeo is built with JavaScript programming language. To get started, you'll need to install Node.js development 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 Node.js download 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

touch ~/.bash_profile

curl -o- <https://raw.githubusercontent.com/creationix/nvm/v0.32.1/install.sh> | bash

Then close terminal and open again

Install homebrew (macOS)

http://brew.sh/

Install npm

https://docs.npmjs.com/cli/install

Install and use node 12

nvm install 12
nvm alias default 12

Install Mapeo Settings Builder

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

npm install -g mapeo-settings-builder

Is your computer ready?

If your computer is ready to create configurations, type

mapeo-settings-builder

You should see output that looks something like

→ Using version x.x.x of mapeo-settings-builder
Usage: mapeo-settings-builder [options] [command]

Options:
  -h, --help                   display help for command

Commands:
  build [options] [sourceDir]  Build config from presets in current working dir
  lint [sourceDir]             Lint preset files for errors
  extract-messages [options]   Extract messages for translation
  generate-key                 Generate a random project key
  help [command]               display help for command

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

cd /Users/jen/Documents/Dd_LOCAL_project-files/Dd-Tools/Mapeo/Presets/CREATION\\ LAB/Strathcona-KX-v1.0.0

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

npm install

npm run -s build

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.

→ Using version x.x.x. of mapeo-settings-builder
! Warning: no category json files found in /home/okdistribute/node_modules/mapeo-default-settings/mapeo-default-settings-2.1.0/categories
✓ Built presets and categories (37ms)
✓ Generated svg sprite for iD (544ms)
✓ Generated png sprite for Mapbox (81ms)
✓ Generated png icons for Mapeo Mobile (607ms)
✓ Successfully created file 'build/mapeo-default-settings-v2.1.0.mapeosettings' (total 1299ms)

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

node -v

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.

npm install -g mapeo-settings-builder@latest

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

In Mac or Linux, in the terminal:

npm install

If you're having more issues, please open an issue on the GitHub repository or e-mail our support hotline.

Versioning

It's important to increment the version when releasing new changes to your configuration. When you are ready to release a new version, you can use standard-version in the command line to automatically increment your config version and update the CHANGELOG.md file in your repository.

Una vez que haya compilado su configuración personalizada, tendrá un archivo .mapeosettings que se puede importar a Mapeo Mobile y Desktop para probarlo y usarlo.

¿Qué es un archivo .mapeosettings?

Un archivo .mapeosettings es un archivo tar, similar a un archivo zip. Para fines de depuración, puede ver el contenido del archivo cambiando la extensión del archivo a .tar y usando cualquier aplicación que pueda extraer archivos tar.

Importar una configuración a Mapeo

For instructions on how to import a configuration file (.mapeosettings) into Mapeo, see:

Importar configuraciones a Mapeo Mobile

Importar configuraciones a Mapeo Desktop

Probando tu configuración

Vale la pena probar a fondo su nueva configuración antes de introducirla en su proyecto y comenzar la recopilación formal de datos.

Algunas cosas a tener en cuenta al probar configuraciones:

• Iconos ¿Los íconos se muestran claramente? Compruebe cómo aparecen los iconos, especialmente en Mapeo Mobile en dispositivos con pantallas más pequeñas.

• Categorías ¿Aparecen las categorías en un orden lógico en la pantalla Categorías de Mapeo Mobile? Los cambios se pueden realizar a través de la propiedad de clasificación en Creating categories

• Campos de detalles ¿Las etiquetas de texto y los marcadores de posición son fáciles de entender? ¿Aparecen los campos de detalles en un orden lógico? Los campos se mostrarán a los usuarios en el orden en que aparecen en la matriz de campos en Creating categories.

• Colores Si agregó color a los marcadores del mapa de categoría, ¿se distinguen entre sí y se ven en el fondo del mapa?

• Nombre y versión ¿El nombre y la versión de su configuración aparecen como se desea en la pantalla de Configuración del proyecto en Mapeo Mobile o en la pantalla de Sincronizar de Mapeo Desktop?

Hacer cambios

Los cambios se pueden hacer fácilmente a su configuración a través de los pasos en la sección Codificar la configuración. A menudo probamos, modificamos, recompilamos y volvemos a probar varias veces antes de lanzar una nueva versión de configuración.

Como se indica en Planeando la configuración y la estructura de datos, las configuraciones pueden evolucionar y, a menudo, evolucionarán con el tiempo. A medida que comience a recopilar datos, probablemente encontrará categorías, campos de detalles y opciones que le gustaría agregar o modificar.

A diferencia de otras herramientas de recopilación de datos o encuestas, Mapeo permite mucha flexibilidad para cambiar las configuraciones con el tiempo y no requiere que se borre la base de datos cuando se realizan cambios. Si bien los cambios en los íconos o los campos de color, nombre, etiqueta o marcador de posición serán menores, las modificaciones más importantes, como eliminar una categoría, afectarán la forma en que se muestran los datos existentes en Mapeo y las exportaciones de datos. Independientemente de estos cambios, ningún dato anterior se perderá o no se podrá ver.

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
}

It is possible to build a Mapeo configuration file using GitHub Actions. This requires setting up your custom configuration directory as a repository on Github.com, 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 Mapeo Default Configuration or the Empty Mapeo Configuration 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 Planeando la configuración y la estructura de datos.

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 Mapeo Default Configuration or the Empty Mapeo Configuration, 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.

By opening the Workflow with your commit message, you can also download a .zip file of your configuration, which includes a temporary .mapeosettings file. This is helpful for testing out your configuration before building a versioned file to distribute to users, as described in Probando e iterando.

Use conventional commit messages to increment your configuration version

The Mapeo GitHub Actions Workflow is set up to dynamically bump the version of your configuration per each workflow. It does so using conventional commit messaging of adding feat:, fix:, or chore: before your commit message. For example, if you have a configuration with version 1.1.0, the specific version bumps are as follows:

• 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

Once you are done making changes, have tested your configuration using a temporary .mapeosettings file (as described in #how-it-works) and in accordance to the process described in Probando e iterando, you can generate a versioned release of your configuration. The way to do so is as follows:

• 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.

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.

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:

• (with Node.js and mapeo-settings-builder)

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.

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