Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
package.json
file: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.
Then close terminal and open again
If you are using Windows Subsystem for Linux (WSL) to build a configuration, you need to install some dependencies for puppeteer.
https://docs.npmjs.com/cli/install
You'll see output on the terminal, but this is OK
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!
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.
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).
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:
If you're having more issues, please open an issue on the GitHub repository or e-mail our support hotline.
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.
For more on versions with standard-version, see #use-conventional-commit-messages-to-increment-your-configuration-version
Mapeo configuration files (.mapeosettings
) are compiled from a set of files and folders that contain all the information Mapeo needs to display the categories, icons and details fields you want users to see when collecting and viewing data. This section will walk you through translating all of the information you've defined in Planning configuration & data structure into a Mapeo configuration file.
To begin preparing your files, you can download or clone our default configuration repository or this empty configuration repository from GitHub. These repositories contain the core files and folders you will need for editing.
When authoring custom configurations, you will edit files within the following configuration folders:
icons
fields
presets
(categories)
And the following configuration files:
metadata.json
defaults.json
package.json
Download the default configuration repository or empty configuration repository.
Unzip the contents to a new folder using a program like 7zip.
Rename the folder from "mapeo-default-settings" to use your own project name, "mapeo-config-projectname".
To review key information on defining categories, see Categories.
presets
directory, customize the .json
filesIn 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.
fishing-site.json
):To review key information on defining details fields, see Details fields.
fields
directory customize the .json
filesEach .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_multiple
fields, you will need to define an array of answer options.
name.json
):sample-type.json
):To review key information on designing icons, see Icons.
Once you've settled on the design or concept for your icons, you'll need to generate .svg
files for each one to be saved in the icons directory. Icons should be created as 100x100 pixel graphics that are clear when viewing at 100%.
To generate .svg
icons for Mapeo, there is an online Mapeo Icons Generator tool accessible here.
We have also documented two workflows to generate Mapeo-compatible .svg
files using software, one using a commercial product (Adobe Illustrator) and another using a open-source product (Inkscape).
Icons need to be read by MAPEO in two sizes: 100 pixels and 24 pixels. For that reason there is a specific file naming convention:
icon-name-100px.svg
icon-name-24px.svg
Each icon can be duplicated and renamed so that there is one of each size. They are opened and read by the .json
files in the presets folder. Verify that name
is correctly entered where needed (more on this in the next section). The build script will process the pixel size suffix.
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.
defaults.json
file:Adobe Illustrator is a vector graphics editor and design program developed by Adobe Inc. Although it is a commercial, licensed product, it is very commonly used to put together vector graphics, and many users utilize this tool for creating icons for Mapeo as well.
.svg
files with the right propertiesWhen you're ready to export a vector graphic file into a Mapeo-compatible .svg
file format, the process is as follows:
On the Adobe Illustrator top menu, click on File and then select Export, followed by Export As.
Ensure that Use Artboards is checked.
Save your .svg
file in the correct directory (icons
for Mapeo configurations) and with your desired filename, and click Export.
In the following window, ensure that the following properties are set, and then click OK:
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.
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:
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.
.svg
files with the right size and Viewbox in Document PropertiesOnce 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.
If you want to verify that the parameters in your .svg
file are correct, open it in a text editor like Visual Studio Code or Notepad++.
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.
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:
Make sure that you have the .github/workflows
directory in your configuration repository.
If you already have your own custom configuration:
Create a repository on GitHub for your custom configuration.
Commit your existing configuration content to the repository.
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.)
NOTE: Depending on your operating system and setup, it is possible that you do not see a .github/
directory anywhere. You may need to enable viewing hidden files in your system file manager.
On MacOS, you can do so by pressing Command + Shift + . (period) in your Finder window.
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.
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.
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.
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.
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.
To create a projectKey
, first open the Terminal.
Copy and paste the following command into the terminal
You'll see something like this (but with x replaced with real characters and numbers)
Copy this string and add it to the metadata.json
file so it looks like this:
Notice that there are double quotes "
around each value.
(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.
Your .svg
file should now be ready to be used by Mapeo. See for more information on how to name the files and where to place them in the configuration directory.
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.
If you haven't already used GitHub, you may want to study the of how GitHub works before proceeding.
Note that since this process relies on using github.com, that you will need internet access to run the build action and download the .mapeosettings
configuration file. Hence, unlike building a configuration , this process will not work in an offline context.
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 .
Download either the or the , and copy over the .github
directory to the root directory of your custom configuration.
a circular check indicates that the build has completed successfully.
a yellow circle indicates that the build is in process.
a red circle with an X indicates that the build has encountered an error.
This is the same log that you would see when building a configuration .
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 .
The Mapeo GitHub Actions Workflow is set up to dynamically bump the version of your configuration per each workflow. It does so using 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:
To see a few examples of configuration conventional commit messaging, see the screenshot above in , or check out the commit history on the repository.
Once you are done making changes, have tested your configuration using a temporary .mapeosettings
file (as described in ) and in accordance to the process described in , you can generate a versioned release of your configuration. The way to do so is as follows:
When that finished with a green check mark, your versioned build release will be ready. On the top navigation bar, click on Code and your release should appear under the Releases panel in the right sidebar.
For instructions on how to install mapeo-settings-builder, see Building configuration file .