This repository holds default configurations used by AsTeRICS Grid. Data from the master
branch is made available via GitHub pages, which is used by the app to download default configurations.
These are the most important files and folders of this repository:
boards
: contains single boards about specific topicscommunicators
: contains self-contained communicators (shown by default at the import page for new users in AsTeRICS Grid)live_metadata.json
: contains metadata about allboards
andcommunicators
, used by AsTeRICS Grid to retrieve metadata about all existing configurations.
The following sections describe step-by-step how to add or alter board configurations from this repository in order to use them in AsTeRICS Grid afterwards.
In general most changes require to run npm run generate
after the changes have been applied. If you're editing the files locally and know how to run it, please do it before creating a pull request. If you're editing files directly on GitHub and creating a pull request, a maintainer of this repository will run it for you. Before running npm run generate
the first time, you need to run npm install
.
- find the folder containing the configuration in boards or communicators. You can also go to the import page in AsTeRICS Grid, show the details of the configuration and click on "Edit on GitHub" to find the folder.
- edit
info.json
updating the metadata in a separate branch / fork (you can directly use the "edit" button in GitHub to do this). - Commit changes and create a pull request in order to let others confirm your changes.
- find the folder containing the configuration in boards or communicators. You can also go to the import page in AsTeRICS Grid, show the details of the configuration and click on "Edit on GitHub" to find the folder.
- edit / add the screenshots in the folder. File format
.jpg
and resolution of1920x1080px
is recommended. - Run
npm run generate
in order to generate the updatedthumbnail.jpg
out of the first screenshot. - Commit changes and create a pull request in order to let others confirm your changes.
- Import the configuration you want to change to a new offline user in AsTeRICS Grid.
- Update the boards as needed within AsTeRICS Grid. Be sure to not change more than needed.
- Go to
Manage grids -> more -> Save backup to file
- find the folder containing the configuration in boards or communicators. You can also go to the import page in AsTeRICS Grid, show the details of the configuration and click on "Edit on GitHub" to find the folder.
- replace the existing file
.grd.json
in this folder with the.grd
backup file from step (3). You can rename it to.grd.json
, but don't have to, it's done automatically. - Commit changes and create a pull request in order to let others confirm your changes.
- Create the new configuration within AsTeRICS Grid.
- Go to
Manage grids -> more -> Save backup to file
- Decide the target folder for the new configuration in this repository. Configurations containing single boards (e.g. boards for a specific topic like "football") belong to the folder boards, while complete self-contained configurations (e.g. a full communicator) belong to the folder communicators.
- Create a new subfolder in "boards" or "communicators". The name of the folder is not important but should make it clear which kind of configuration it holds. For instance boards about the UEFA Euro 2024 by John Doe should go to a folder like
boards/UEFA Euro 2024 - John Doe
. - Move the backup from (2) to this folder.
- Create a file
info.json
containing metadata about the boards. See Content of info.json below for possible content of this file. - Create screenshots of the configuration (e.g.
1.jpg
,2.jpg
etc.) and add them to the folder. File format.jpg
and resolution of1920x1080px
is recommended. The first image (alphabetic order) will be copied to a lower resolutionthumbnail.jpg
used for an overview of configurations. - Commit changes and create a pull request in order to let others confirm your changes.
See docs about difference between multilingual and monolingual configurations.
Follow steps of Update the contents of the boards of existing configuration where step (2) is translating the configuration to a new language. For docs about how to add a translation see Translation of a multilingual default gridset in the docs.
See docs about difference between multilingual and monolingual configurations.
Follow these steps:
- Import the configuration you want to translate to a new offline user in AsTeRICS Grid.
- Follow the instructions how to translate the monolingual configuration from the docs
- find the folder containing the configuration in boards or communicators. You can also go to the import page in AsTeRICS Grid, show the details of the configuration and click on "Edit on GitHub" to find the folder.
- add a new subfolder with the 2-digit language code of your newly translated language, e.g.
en
if you translated the configuration to English. - Add the backup
.grd
file resulting from (2) to the new folder (e.g.en
). - Optionally add a file
info.json
or screenshots of the configuration to the new folder (e.g.en
). These files override data from the parent folder. - Commit changes and create a pull request in order to let others confirm your changes.
The contents of the subfolders of boards
and communicators
are managed in the same way. The name of subfolders is not important. They (may) contain:
info.json
: information about the configuration*.img, *.png
: screenshots of the configuration (resolution should be1920x1080
). The special imagethumbnail.jpg
is automatically created from the first screenshot (alphabetic order) with a width of500px
. It's used by AsTeRICS Grid for the preview miniature on the import page.*.grd.json
: AsTeRICS Grid backup file containing the actual configuration (*.grd
files are automatically renamed to*.grd.json
- causes use of gzip compression by GitHub pages)- folders like
en
,de
,es
contain translated versions of this configuration. These folders contain an own.grd.json
backup file and may contain additional images (.png, .jpg
) or an additionalinfo.json
which overwrite information from the base folder.
Look at boards/Hora de la ducha for an example. It contains:
- folders
en
,es
,it
,pt
: containing.grd.json
files representing the backup files containing the content, translated to different languages info.json
: contains metadata shared by all translated configurations of "Hora de la ducha".jpg files
: full-size screenshots shown in details modal,thumbnail.jpg
for preview in grid view
The file info.json may contain the following properties in JSON format:
name
: the name of the configurationauthor
: the author of the configurationwebsite
: optional URL for more information about the authorlanguages
: an array of 2-digit codes of languages of this configuration, e.g.["en", "de", "es"]
.description
: a short description of the configurationpriority
: optional integer value, where a higher value means higher priority and will cause the result be listed first in AsTeRICS Grid.wordPrediction
: optional boolean property to indicate that the configuration contains a keyboard with word prediction. This can be used in order to ask the user if they want to import a dictionary after importing.tags
: an array of tags, indicating the properties of the configuration (e.g. topic and grid size, example:["BASIC", "4x5", "MEDICAL"]
)