Nunaliit Tutorial: Switching from classic to tiled display format

By default atlas documents are shown in the side panel using the classic display format. However, the Nunaliit framework can also display documents in a tile format which can be easily adjusted in an atlas with a single line of code.

The tile display can be applied to a single module, or applied to all modules throughout the atlas. To display documents in a tile display format for a specific module, you can edit the display.json file, located in the nunaliit_module directory. Within the display.json file you will need to add the key “type” and the value “tiled”.

Where to find the display.json file:

module name (e.g. module.demo)/
└── nunaliit_module
 –└── display.json

Example display.json:

{
"defaultSchemaName":"demo_doc",
"type":"tiled"
}

Alternatively, if you prefer the tile display over the classic format you can apply this preference to all modules in the atlas. This option can be applied by adding the displayFormat custom service option within the custom service portion of the window.nunaliit_custom.configuration function (located in the nunaliit_custom.js file).

Location of the nunaliit_custom.js file in your atlas:

atlas/
└── htdocs
 –└── nunaliit_custom.js

Example nunaliit_custom.js code addition:

customService.setOption('displayFormat','tiled');
Tiled Display

Screenshot of a Nunaliit atlas using the tiled display (showing four related documents as tiles)

Quick Tip: How to unfreeze your terminal after typing CTRL + s

Every once in a while (usually when my morning coffee hasn’t kicked in yet), I’ll type Ctrl+s to save a document while using vi. Obviously this isn’t how documents are saved in vi, and the result causes your terminal to freeze, becoming completely unresponsive to keyboard commands.

Solution: To unfreeze you terminal after accidentally typing CTRL + s, you simply need to type CTRL + q, and you should now have control of you terminal again.

 

Nunaliit Tutorial: Update the Module Title

The title of the module (seen in the thin bar beneath the larger navigation bar in the atlas), can easily be updated to any string of text. Within the module’s directory you will find the nunaliit_module directory, which will contains the title.json file that you will need to  update.

Where to find the title.json file:
module.demo/
└──  nunaliit_module
 –└── title.json

Example title.json:

{
"nunaliit_type":"localized"
,"en":"Demo Atlas"
,"fr":"Atlas Demo"
}

Update the title of the module:

As seen in the example above, the title.json file can contain multiple versions of the module title for different languages. Each version of the title is identified with the language code key (e.g. “en” for English) and corresponding value of the title in that language (e.g. “Demo Atlas”).  If you wish to update the module’s title, simple update the title’s text value for each required language used in your atlas (e.g. “en”:”Demo Atlas” could be updated to “en”:”Test Atlas Map”).

Note: If your atlas uses other languages in addition to the default English (en) and French (fr), simply include the language code and corresponding translated title, in the same manner as the en and fr examples above.

Nunaliit Tutorial: Updating the atlas’ default module

When accessing your atlas from the root domain (e.g. http://127.0.0.1:8080) it should load a default module. Initially this is set to the demo module but can be updated to a different module within the nunaliit_custom.js file, located in the htdocs directory.

Location of nunaliit_custom.js file in your atlas:
atlas/
└── htdocs
­└── nunaliit_custom.js

Updating nunaliit_custom.js:

Within the custom service configuration portion of the nunaliit_custom.js file, you should see a line of code which looks like the following;

customService.setOption('defaultModuleIdentifier','module.demo');

You will notice that the final parameter being passed to the setOption method, states the id of the demo module ‘module.demo’. To change the default module, simply replace the ‘module.demo’ id with the id of the new module you wish to have as the default.

Nunaliit Tutorial: Creating a Module

Modules provide a means to organize the atlas into related content. They can contain a variety of data, and be presented in numerous formats including the use of dynamic maps, canvases, or if you prefer a simple html page containing traditional content like text and media.

The easiest method to create a new module, is to simply copy an existing module and update the id file. The following tutorial will provide instructions on how to accomplish this task.

Basic Structure of a Module:
module.demo/
├── _id.txt
├── nunaliit_module
│ ├── display.json
│ ├── edit.json
│ ├── help.json
│ ├── introduction
│ │ ├── content
│ │ │ ├── en.html
│ │ │ ├── fr.html
│ │ │ └── nunaliit_type.txt
│ │ └── type.txt
│ ├── map.json
│ └── title.json
└── nunaliit_schema.txt

Copying an existing module:

Within the docs directory of your atlas, first locate an existing module which you can copy.  Note: If you’ve just created an atlas, a template for a module called module.demo should be available for copying.

To copy an existing module via the terminal, type the following command (Note: the Unix copy command ‘cp’ requires you to add the ‘-r’ recursive option in order to copy the directory and its contents):

cp -r <the name of the original module directory>
 <the name of the new module directory>

e.g. cp -r module.demo module.testatlas_map

Note: If you’re working in a GUI, you can alternatively copy the directory and paste it with a new name in the docs directory, as you would copy any directory on your OS.

Updating the ID of the new module:

Following the copying of the module, you should now have two modules with different directory names. However you still need to update the id of the new module, so that its different from the original module it was copied from.

Using a text editor, update the _id.txt file (located within the new module directory) with the new module id. The file will consist of a single line of text containing the id of the module. Using the example above the _id.txt file will contain the text ‘module.demo’ and will need to be updated to something else, such as ‘module.testatlas_map’.

Quick Tip: Subversion Change Logs For Files

Yesterday I needed to determine who last edited portions of a file with subversion, and came across a couple great suggestions on stack overflow which I’d like to share here.

Subversion offer a few ways to perform this task, including the following two methods I learned yesterday;

1. The first method returns the log of previous revisions on the file and is ideal when you need to review a more detailed change log.

 svn log --diff filename 

2. The second method is more concise, and only provides the revision number and author name for the last change to a specific file’s line. This approach is performed with the aptly named subcommand blame.

 svn blame filename 

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.