Projects and Packages

Projects

Arches Projects facilitate all of the customizations that you will need to make one installation of Arches different from the next. You can update html to modify web page branding, and add functions, datatypes, and widgets to introduce new functionality. A project sits outside of your virtual environment, and can thus be transferred to any other system where Arches is installed.

The general structure of a new Arches project is::

my_project/
└─ manage.py
└─ my_project/
      └─ settings.py
      └─ datatypes/
      └─ functions/
      └─ media/
      └─ templates/
      └─ widgets/

Note that not all files are shown

settings.py

Many project-specific settings are defined here. You should use settings_local.py to store variables that you may want to keep out of the public eye (db passwords, API keys, etc.).

templates

This directory holds HTML templates that you can modify to customize the branding and general appearance of your project.

datatypes, fuctions, and widgets

These directories will store the custom datatypes, functions, and widgets that you can create for the project. Developers interested in pursuing these customizations should start with this customization documentation.

Packages

A package is an external collection of arches data (resource models, business data, concepts, collections) and customization files (widgets, datatypes, functions, system settings) that you can load into an arches project.

Loading a Package

To load a package simply run the load_package command using your *project’s manage.py file:

python manage.py packages -o load_package -s https://github.com/package/archive/branch.zip -db true
-db true to run setup_db to rebuild your database. default = ‘false’
-ow overwrite to overwrite concepts and collections. default = ‘ignore’
-st stage to stage concepts and collections. default = ‘stage’
-s a path to a zipfile located on github or locally
-o operation name
-y accept defaults (will overwrite existing branches and system settings with those in the package)

If you do not pass the -db True to the load_package command, your database will not be recreated. If you already have resource models and branches with the same id as those you are importing, you will be prompted to confirm whether you would like to keep or overwrite each model or branch.

Note

It is important to note that you cannot load a package directly into core Arches. Packages must be loaded into a project.

If you are a developer running the latest arches you probably want to create a project with a new Arches installation. This ensures that the arches_project create command uses the latest project templates.

  1. Uninstall arches from your virtualenv

    pip uninstall arches
    
  2. Navigate into arches root folder delete the build directory

  3. Reinstall arches

    python setup.py install
    python setup.py develop
    
  4. Navigate to where you want to create your new project and run:

    arches-project create mynewproject
    
  5. Finally run the load_package command using the projects manage.py file.

    python manage.py packages -o load_package -s https://github.com/package/archive/branch.zip -db true
    

Creating a New Package

If you want to create additional projects with the same data or share your data with others that need to create similar projects, you probably want to create a package.

The create_package command will help you get started by generating the folder structure of a new package and loading the resource models of your current project into your new package.

  1. To create new package simply run the create_package command. The following example would create a package called mypackge.

    python manage.py packages -o create_package -d /Full/path/to/mypackage
    
    -d

    full path to the package directory you would like to create

    -o

    operation name

  2. Below is a list of directories created by the create_package command and a brief description of what belongs in each. Be sure not to place files that you do not want loaded into these directories. If, for example, you have draft business_data that is not ready for loading, just add a new directory and stage your files there. Directories other than what is listed below will be ignored by the loader.

    business_data

    Resource instance .csv and corresponding .mapping files, each sharing the same base name.

    business_data/files

    Files to be added to the uploaded files directory

    business_data/relations

    Resource relationship files (.relations)

    business_data/resource_views

    sql views of flattened resource models

    extensions/function

    Each function in this directory should have its own directory with a template (.htm), viewmodel (.js) and module (.py). Each file must share the same base name.

    extensions/datatypes

    Each datatype in this directory should have its own directory with a template (.htm), viewmodel (.js) and module (.py). Each file must share the same base name.

    extensions/widgets

    Each widget in this directory should have its own folder with a template (.htm), viewmodel (.js) and configuration file (.json). Each file must share the same base name.

    graphs/branches

    arches.json files representing branches

    graphs/resource_models

    arches.json files representing resource models

    map_layers/mapbox_styles/overlays*

    Each overlay should have a directory with a mapbox style as exported from mapbox including a style.json file, license.txt file and an icons directory

    map_layers/mapbox_styles/basemaps*

    Each basemap should have a directory with a mapbox style as exported from mapbox including a style.json file, license.txt file and an icons directory

    map_layers/tile_server/overlays*

    Each overlay should have a directory with a .vrt file and .xml to style and configure the layer. Each file must share the same base name.

    map_layers/tile_server/basemaps*

    Each overlay should have a directory with a .vrt file and .xml to style and configure the layer. Each file must share the same base name.

    preliminary_sql

    sql files containing database operations necessary for your project.

    reference_data/concepts

    SKOS concepts .xml files

    reference_data/collections

    SKOS collection .xml files

    system_settings

    The system settings file for your project

    package_settings.py

    The django settings relevant to your project not managed in system settings. For example, you may want to include your time wheel configuration and your analysis SRID settings in this file so that users do not have add these settings manually to their own settings file after loading your package.

    * map layer configuration

    By default mapbox-style layers will be loaded with the name property found in the layer’s style.json file. The default name for tile server layers will be the basename of the layer’s xml file. For both mapbox-style and tile server layers the default icon-class will be fa fa-globe. To customize the name and icon-class, simply add a meta.json file to the layer’s directory with the following object:

    {
        "name": "example name",
        "icon": "fa example-class"
    }
    
  3. It is not necessary to populate every directory with data. Only add those files that you would like to share.

    Once you’ve added the necessary files to your package, simply compress it as a zip file or push it to a github repository and it’s ready to be loaded.

Updating an Existing Package

If you make changes to the resource models in your project you may want to update your package with those changes. You can do that with the update_package command:

python manage.py packages -o update_package -d /Full/path/to/mypackage
-d full path to the package directory you would like to update
-o operation name
-y accept defaults (will overwrite existing resource models with those from your project)

Bear in mind that this command will not update a package directly on Github. It will however update a package in a local directory that you have cloned from an existing package on Github or created yourself with the create_package command.