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’.

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.

Nunaliit Tutorial: Adding a Schema

What is a schema?:

A schema provides guidelines for Nunaliit in the creation, editing and viewing of documents. They allow atlas builders a means to define what data to collect and how it should be viewed by the user. However, it’s important to note that how a schema is defined shouldn’t be viewed as hard set rules, but rather suggestions of the type of content expected in a document.

By default each atlas provides a demo document schema, a demo comment schema and a demo media schema. These schemas provide a new atlas builders a place to start testing out the functionality of the atlas right away. However, if you continue to use Nunaliit, you will likely need to build your own schema for a specific project. This tutorial provides the steps for creating your own schemas.

Designing a schema definition:

Typically when designing a schema, an atlas builder should first consider what data will be collected, and how to segment it into it’s core components. For example, an atlas which focuses on financial institutions, may contain data on banks, bank staff, bank clients, and transactions. This data can be simplified into three schemas: bank, person, and transaction. Notice that both bank staff and bank clients are merged into a single person schema, since their data will likely contain similar information. See below for an example of the fields needed for these three schemas.

schemadesign

Schema designs for Bank, Person and Transaction schemas.

Add a schema to the atlas:

To add a new schema to the atlas, you will need to run the command ‘nunaliit add-schema –id schemaid’ from the root directory of the atlas (similar to how you would run the update or run commands).

 e.g. ../nunaliit2-couch-sdk-2.2.6/bin/nunaliit add-schema --id bank

This command will create a new schema, which is added to the atlas’ docs folder with the name ‘schema.groupname_schemaid’. Within the new schema’s directory, you will see the required files which define the structure of a schema. Initially these files contain the basic structure of the schema, and will need to be updated to represent the schema design mentioned above.

schemadircontents

List of files within a schema directory

schema.testatlas_bank/
├── brief.txt
├── create.json
├── csvExport.json
├── definition.json
├── display.txt
├── export.json
├── form.txt
├── _id.txt
├── isRootSchema.json
├── label.txt
├── name.txt
├── nunaliit_schema.txt
├── nunaliit_type.txt
└── relatedSchemas.json

Updating the schema’s design can be performed by defining the structure of the schema in the definition.json file. Instructions on how to create defintion.json files, including a complete list of field options, can be found on the atlas builder wiki pages.

Using the schema designs shown above, I’ve included three examples of the definition files for the bank, person and transaction schemas.

Bank Schema Definition:

{
    "group": "testatlas"
    ,"id": "bank"
    ,"label": "Bank"
    ,"relatedSchemas": [ ]
    ,"initialLayers": [ "public" ]
    ,"attributes":[
    {
        "type":"string"
        ,"id":"name"
        ,"label":"Name"
        ,"includedInBrief":true
    }
    ,{
        "type":"string"
        ,"id":"branch_number"
        ,"label":"Branch #"
    }
    ,{
        "type":"string"
        ,"id":"address"
        ,"label":"Address"
        ,"textarea": true
    }
    ,{
        "type":"string"
        ,"id":"phone_number"
        ,"label":"Phone #"
    }
    ,{
        "type": "array"
        ,"elementType":"reference"
        ,"id":"employees"
        ,"label":"Employees"
    }
    ,{
        "type":"checkbox"
        ,"id":"atm"
        ,"label":"ATM location?"
    }
    ]
}

Person Schema Definition:

{
    "group": "testatlas"
    ,"id": "person"
    ,"label": "Person"
    ,"relatedSchemas": [ ]
    ,"initialLayers": [ ]
    ,"attributes":[
    {
        "type":"string"
        ,"id":"name"
        ,"label":"Name"
        ,"includedInBrief":true
    }
    ,{
        "type":"string"
        ,"id":"address"
        ,"label":"Address"
        ,"textarea": true
    }
    ,{
        "type":"string"
        ,"id":"phone_number"
        ,"label":"Phone #"
    }
    ]
}

Transaction Schema Definition:

{
    "group": "testatlas"
    ,"id": "transaction"
    ,"label": "Transaction"
    ,"relatedSchemas": [ ]
    ,"initialLayers": [ ]
    ,"attributes":[
    {
        "type": "reference"
        ,"id":"payer"
        ,"label":"Payer"
    }
    ,{
        "type": "reference"
        ,"id":"payee"
        ,"label":"Payee"
    }
    ,{
        "type":"string"
        ,"id":"amount"
        ,"label":"Amount"
    }
    ,{
        "type":"date"
        ,"id":"date"
        ,"label":"Date"
    }
    ,{
        "type":"string"
        ,"id":"details"
        ,"label":"Details"
        ,"textarea": true
    }
    ]
}

Updating Schemas:
Once the definition.json files are updated with the new schema design structures, you can update the schemas in a number of ways. You can either update each schema individually or you can update all of the schemas at once.

Update a specific schema:

 e.g. ../nunaliit2-couch-sdk-2.2.6/bin/nunaliit update-schema --name testatlas_bank

Note: The name of the schema is typically the groupname_schemaid. If you are unsure of the name of the schema, you should consult the name.txt file within the schema’s directory

Update all schemas:

 e.g. ../nunaliit2-couch-sdk-2.2.6/bin/nunaliit update-schema --all

Updating the Atlas:

The update-schema tool updates each of the files in the schema directory with the newly defined schema’s structure. However these changes won’t be seen in the atlas until the atlas it’s self is updated.

 e.g. ../nunaliit2-couch-sdk-2.2.6/bin/nunaliit update

Following the update of the atlas, you should now be able to use these schemas in your atlas. See a screenshot of the schema form view below.

screenshotofschemadisplay

Nunaliit form view of the Bank schema

Customizing your schema:

Using the add-schema and update-schema tools allows for quick creation and updating of schema documents in Nunaliit. However, you are not limited to the use of these tools. You can edit the files in the schema directory, allowing an atlas builder to customize your schema’s design. Note: If you decided to customize a schema, you will likely want to delete your definition.json file from the schema directory to prevent your custom changes being overwritten accidentally with the nunaliit update-schema –all.

Nunaliit Tutorial: Installing Nunaliit

Introduction:

Nunaliit is an open source web mapping framework, designed for a Linux operating system (OS) and uses a number of open source software packages. However, this tutorial recognizes that most users are coming from a Windows OS background, and are not accustom to working with Linux.

This tutorial instructs how to install Nunaliit using a virtual machine, which is available to deploy in most OS environments, including; Windows, Mac OS or various Linux distributions. Using a virtual machine allows users to try Nunaliit without forcing them to completely abandon their OS of choice, creating a Linux partition, or needing to invest in a server to see Nunaliit’s potential as a free web mapping framework.

If you’re currently a Linux user and have Ubuntu installed on your desktop or server environment, you can skip steps 1 and 2 and start on step 3. Note: Nunaliit officially supports being run on Ubuntu, but can also work on other distributions.

Step 1 – Download Linux distribution:

Before you can install a new Linux OS as a virtual machine, you will need to download a copy of the OS. For this exercise we will download the popular distribution Ubuntu, which can be downloaded from http://www.ubuntu.com/download. Note: If you’re familiar with Linux, you may want to download the server version of Ubuntu instead of the desktop version, if you have no need for a graphical user interface for your virtual machine.

When downloading the distribution, make sure it’s in an iso file format, and is supported by your hardware (note: if the 64 bit OS is not possible in VirtualBox, then you will likely need to use the 32 bit version of Ubuntu).

Step 2 – Creating a virtual machine with VirtualBox:

With a copy of Ubuntu downloaded, you will now create a virtual machine using the popular open source software VirtualBox.

Step 2.1 – Download VirtualBox:

First you will need to download VirtualBox, a free piece of software allowing you to create virtual machines within your own OS (i.e. you can run a copy of Ubuntu within Windows, MacOS or Linux environment). Go to https://www.virtualbox.org/, to download the software required for your computer, and install it on your system.

Step 2.2 – Create a new virtual machine:

Once successfully installed, run VirtualBox and click the New button.

virtualboxscreenshot

VirtualBox Main Window – Create a new virtual machine (screenshow)

Step 2.3 – Create a new virtual machine:

Provide the name of the OS and select the correct type and version. In our case it will be;

  • Name: Ubuntu 16.04

  • Type: Linux

  • Version: Ubuntu (32bit) (Note: this may be 64 bit depending on Step 1)

newlinuxvm

VirtualBox create a new virtual machine window (screenshot)

Step 2.4 – Define the memory size available for the virtual machine:

Note: A minimum of 2048 MB should be used for Ubuntu. (Note you can change this value afterwards through the settings. If you have memory to spare, providing more than 2048 MB is recommended for improved performance of Nunaliit)

memorysize

VirtualBox define memory size window (screenshot)

Step 2.5 – Create a virtual hard disk:

Select ‘Create a virtual hard disk now’ and click Create.

virtualharddisk

VirtualBox window for creating a virtual hard disk (screenshot)

Step 2.6 – Virtual disk type:

Select the hard disk file type: ‘VirtualBox disk image’, and then click Next.

virtualdisktype

VirtualBox window – Select a hard disk file type (screenshot)

Step 2.7 – Select dynamically allocated for the disk:

dynamicorfixedsize

VirtualBox storage on physical hard disk (screenshot)

Step 2.8 – Set the file location and size:

Set the size of the virtual hard disk and the folder location. Make sure to provide enough space for the work you intended to do in the virtual environment.

filelocationandsize

VirtualBox File location and size window

Step 2.9 – Run the virtual machine:

Select the virtual machine you wish to run (if you only have one, it will automatically be selected). Under the Storage section click ‘[Optical Drive] Empty’, select the option ‘Choose disk image …‘ and then select the Ubuntu iso file you downloaded in Step 1. Lastly click the Start button. Note: If you see an error message stating, ‘FATAL: No bootable medium found! System halted.’ This likely means you need to select the iso file you downloaded in Step 1 to be booted.

runcreatedvm

VirtualBox run Ubuntu 16.04 virtual machine (screenshot)

Step 2.10 – Installing Ubuntu on the virtual machine:

After a couple minutes, an Ubuntu install window should pop up. Next, click the Install Ubuntu button.

installubuntu

Ubuntu installation welcome window (screenshot)

Check both boxes on the preparing to install Ubuntu screen and click the Continue button

preparingtoinstallubuntu

Ubuntu preparation to install window (screenshot)

Select the option Erase disk and install Ubuntu, and then click the Install Now button.

installationtype

Ubuntu installation type window (screenshot)

You will then be asked to confirm you want to write these changes to disk, and you will need to click Continue.

writechangestodisk

Ubuntu confirmation to write changes to disk (screenshot)

Define where you are in the world (this will set your timezone/clock on the desktop) and then click Continue.

whereareyou

Ubuntu Installation window – Selection your location (screenshot)

Define the keyboard layout, and click the Continue button.

definekeyboardlayout

Ubuntu keyboard layout selection window (screenshot)

Provide your user information for your user account in Ubuntu, and then click Continue. Make sure to remember your username and password (you will need these to log into the system after your installation and for downloading/installing new software).

whoareyou

Ubuntu installation window for creating a new account (screenshot)

When the installation is complete it will prompt you to restart your virtual machine. Click Restart Now.

restartnow

Ubuntu installation complete window (screenshot)

Note: If the machine doesn’t restart automatically go to machine -> reset, or you can try closing the window and selecting the option ‘power off machine‘ if the virtual machine is unable to restart and then run it again.

Your virtual machine should now be up and running.

Step 3 – Installing Nunaliit prerequisites:

Now that Ubuntu is installed on your virtual machine and you have logged in with your Ubuntu username and password. Open the program called terminal (you can find it by clicking the window’s key or clover leaf key and type terminal into the search window)

Step 3.1 – Get the latest updates and upgrade software:

In the terminal, type the following commands:

sudo apt-get update

‘sudo apt-get update’ retrieves the latest list of software available via apt-get (Note: You will be prompted for your password when you type sudo for the first time. This is the same password as the one provided for your user account).

sudo apt-get upgrade

‘sudo apt-get upgrade’ downloads the latest software for your system. Next type Y to install the latest software updates.

Step 3.2 – Install Java on your system:
sudo apt-get install -y openjdk-8-jre-headless

Step 3.3 – Install Couchdb:
sudo apt-get install -y couchdb

Step 3.4 – Install FFMpeg:
sudo apt-get install -y ffmpeg libav-tools ubuntu-restricted-extras libavcodec-extra

Step 3.5 – Install ImageMagick:
sudo apt-get install -y imagemagick

Step 4 – Download the Nunaliit software development kit:

Nunaliit can be downloaed from the following website.

Pick the latest release (2.2.6 at the time of this instruction) and download the Nunaliit development kit (SDK) tar ball (e.g. http://central.maven.org/maven2/ca/carleton/gcrc/nunaliit2-couch-sdk/2.2.6/nunaliit2-couch-sdk-2.2.6-nunaliit.tar.gz). Note: v. 2.2.7 is now released.

Next you will need to uncompress/extract the tar-ball’s files. You can either double click the file and uncompress/extract it to the desired directory using the graphical user interface, or you can uncompress/extract the files through the terminal (see command below).

tar –xzvf nunallit2-couch-sdk-2.2.6-nunaliit.tar.gz

Step 5 – Change CouchDB Admin Password:

Before you can run an atlas you will first need to add an admin account in CouchDB. Start by opening a browser by going to the following url: http://127.0.0.1:5984/_utils (CouchDB’s futon page). Note: If CouchDB is installed by not running, you may need to start the service from the terminal, see this post for instructions.

Click on the link ‘Fix this’, located at the bottom right-hand corner. Then in the create server admin window, add an admin password by typing admin into the username text field and then a password into the password field (Note: make sure to write this password down, you will need it to run Nunaliit).

changecouchdbpassword

CouchDB Futon – Creating a server admin (screenshot)

Step 6 – Create a new Nunaliit Atlas:

You can create a new Nunaliit atlas using the following command in terminal. Note: make sure your current directory contains the extracted SDK sub-directory from the tar-ball:

./nunaliit2-couch-sdk-2.2.6/bin/nunaliit create

Provide the information for configuring a new atlas.

  • Enter the name/location where the atlas will be created (keep the name lowercase and without spaces or special characters)

  • Note: many of the fields used for creating an atlas have default values (shown in [ ]), to accept these values simply hit enter/return.

  • Update the admin password to the new CouchDB admin password provided in Step 5.

  • See the screenshot of the create atlas configuration questions below;

createanewatlas_config

Creating a new atlas (called testatlas) with Nunallit (screenshot)

Step 7 – Update and Run a Nunaliit Atlas:

Once the atlas has been created, it will need to be updated first and then run. Start by changing the directory to the new atlas sub-directory, and then run the atlas update command as follows (Note: you may need to update the command below, if your copy of Nunaliit is located elsewhere):

../nunaliit2-couch-sdk-2.2.6/bin/nunaliit update

and then type the following to run the atlas:

../nunaliit2-couch-sdk-2.2.6/bin/nunaliit run

To see your atlas up and running go to the URL http://127.0.0.1:8080 (Note: replace the port 8080 with the port you provided in the initial create procedure if it’s different).

newnunaliitschema

New Nunaliit atlas shown in a browser. (Screenshot)

Step 8 – Stop a running atlas:

To stop the running atlas, type CTRL+C in the terminal