Nunaliit Tutorial: Atlas Directory Structure

This overview provides details on the structure of a Nunaliit atlas, with a focus on the files which are most relevant to a new user. For additional information on the atlas directory structure, please consult the nunaliit atlas builder wiki page.

Tree view of basic atlas:
atlas/
├── config
│ ├── install.properties
│ ├── mail.properties
│ ├── multimedia.properties
│ ├── nunaliit_manifest.json
│ ├── nunaliit.properties
│ ├── sensitive.properties
│ └── upload.properties
├── docs
│ ├── approved
│ ├── help.browsers
│ ├── help.demo
│ ├── module.demo
│ ├── navigation.demo
│ ├── org.nunaliit.email_template.daily_vetter
│ ├── org.nunaliit.email_template.form_email
│ ├── org.nunaliit.email_template.password_recovery
│ ├── org.nunaliit.email_template.password_reminder
│ ├── org.nunaliit.email_template.submission_approval
│ ├── org.nunaliit.email_template.submission_rejection
│ ├── org.nunaliit.email_template.upload
│ ├── org.nunaliit.email_template.user_creation
│ ├── org.nunaliit.user_agreement
│ ├── public
│ ├── schema.demo_comment
│ ├── schema.demo_doc
│ ├── schema.demo_media
├── extra
│ └── nunaliit.sh
├── dump
│ └── dump_2016-11-25_14:55:07
├── htdocs
│ ├── css
│ ├── favicon.ico
│ ├── index.html
│ ├── js
│ ├── nunaliit_custom.js
│ └── nunaliit_lang.en.js
├── logs
│ └── nunaliit.2016-11-25
├── media
└── site
└── views

As seen in the tree view above, every Nunaliit atlas contains a number of sub-directories which each relate to specific aspects of an atlas. For the purpose of simplicity, this overview will focus on the two directories which new atlas builders spend most of their time in; the docs and htdocs directories. The config, extra, dump, logs, media and site sub-directories will be ignored for the time being but future lessons will provide greater details on these excluded directories.

The Docs Directory:
The docs directory contains documents which are pushed into the CouchDB database used by Nunaliit, and provide much of the structure of how data is viewed, edited and collected in an atlas. When you create a schema, module, layer, import profile, help document, or want to change the appearance of the navigation bar, this is the directory where you will need to work in.

The docs tree view below is of a newly created docs directory, which contains a variety of documents used to created the initial template of an atlas.

Docs Tree Structure:
docs/
├── approved
├── help.browsers
├── help.demo
├── module.demo
├── navigation.demo
├── org.nunaliit.email_template.daily_vetter
├── org.nunaliit.email_template.form_email
├── org.nunaliit.email_template.password_recovery
├── org.nunaliit.email_template.password_reminder
├── org.nunaliit.email_template.submission_approval
├── org.nunaliit.email_template.submission_rejection
├── org.nunaliit.email_template.upload
├── org.nunaliit.email_template.user_creation
├── org.nunaliit.user_agreement
├── public
├── schema.demo_comment
├── schema.demo_doc
└── schema.demo_media

In order to aid the understanding of what each of these files control in an atlas, the atlas screenshot shown below, describes which documents control which aspects of an atlas’s design.

labelled_atlas_window

An overview of which atlas files control which portions of the atlas template (screenshot)

The Htdocs Directory:

The htdocs directory contains the documents typically found in most web pages, including html, javascript and css files. When you need to edit the appearance of the atlas, add additional javascript libraries, or provide custom functionality, these changes typically occur in the htdocs directory.

Htdocs Tree Structure:
htdocs/
├── css
│ └── atlas.css
├── favicon.ico
├── index.html
├── js
│ └── index.js
├── nunaliit_custom.js
└── nunaliit_lang.en.js

Tips for naming atlas files:
When creating new content in an atlas, consistency between directory names can prevent confusion (and in some cases errors) from arising. When creating a new files in the docs directory, the following format has proven useful.

<document_type>.<group_name>_<document_name>

e.g.
module.testatlas_about
module.testatlas_map
schema.testatlas_person
schema.testatlas_bank
navigation.testatlas
help.testatlas_map
layer.testatlas_banks

Although you’re not prevented from using your own directory structure, adopting something consistent in format will make identifying atlas content easier.

Tips for editing files:
When editing atlas files, ensure that your text editor is set to utf-8 character encoding when editing and saving files. In some cases, text editors can add special characters or may leave temp files in the directory you’re editing in, so take care when selecting a text editor to edit files.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s