Nunaliit Tutorial: Navigation Documents

The atlas navigation bar provides an easy way to access atlas content. This content is commonly divided between different modules and hyperlinks to those modules are listed in the navigation bar.

This tutorial provides instructions on: 1) how to alter the navigation bar by editing a navigation document, 2) how to create new navigation documents, and 3) how to update the default navigation document used by an atlas.

Structure of the navigation document:

navigation.demo/
├── _id.txt
├── nunaliit_navigation.json
└── nunaliit_schema.txt

The structure of the navigation document consists of three files; the _id.txt, nunaliit_navigation.json, and the nunaliit_schema.txt. The _id.txt file provides the id of the navigation document (e.g. navigation.demo). The nunaliit_schema.txt states the schema is of type ‘navigation’. The nunaliit_navigation.json contains the substance of the navigation document, organizing various links to different content.

How to define a new navigation bar:
By default Nunaliit provides a demo navigation document, navigation.demo. Although the navigation.demo can be updated and used for the atlas’ navigation bar, atlas builders often replace these demo files with atlas specific versions. This is generally a good practice since it makes the document easier to identify as being related to a specific atlas.

To define a new navigation document, make a copy of the existing navigation.demo directory. For consistency, new navigation documents often receive the name navigation.atlas_name. For example if you created an atlas about World War II called wwii, than the navigation document would be called navigation.wwii.

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 navigation.demo navigation.wwii

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.

Once the navigation document is copied and renamed, edit the _id.txt file so that the id matches the new directory name (e.g. navigation.wwii).

You now have a new navigation document with the same content as the navigation.demo.

Tip: You can make as many navigation documents as you want. Navigation documents which are not used by default, can still be viewed as a document in the side content panel. This is a useful way of creating a list of links to content which are still in development but aren’t ready for being included on the main navigation bar.

Sample nunaliit_navigation.json file:
As previously mentioned the nunaliit_navigation.json file provides the structure for a list of links included in the navigation bar. Three attributes are used to define the structure of this json file: 1) the nunaliit_type which is given the value of “navigation”, 2) title which defines the label used for the atlas, and 3) an items attribute, which defines the links included in the navigation bar and how they’re organized. See the sample nunaliit_navigation.json file with corresponding sketch of the navigation bar below.

{
    "nunaliit_type":"navigation"
    ,"title":{
        "nunaliit_type":"localized"
        ,"en":"Atlas Title"
    }
    ,"items":[
        {
            "title": {
                "nunaliit_type":"localized"
                ,"en":"a"
            }
            ,"module": "module.a"
        }
        ,{
            "title": {
                "nunaliit_type":"localized"
                ,"en":"b"
            }
            ,"module": "module.b"
            ,"items":[
                {
                    "title": {
                        "nunaliit_type":"localized"
                        ,"en":"b1"
                    }
                    ,"module": "module.b1"
                }
                ,{
                    "title": {
                        "nunaliit_type":"localized"
                        ,"en":"b2"
                    }
                    ,"module": "module.b2"
                    ,"items":[
                        {
                            "title": {
                                "nunaliit_type":"localized"
                                ,"en":"b2a"
                            }
                            ,"module": "module.b2a"
                        }
                        ,{
                            "title": {
                                "nunaliit_type":"localized"
                                ,"en":"b2b"
                            }
                            ,"module": "module.b2b"
                        }
                    ]
                }
                ,{
                    "title": {
                        "nunaliit_type":"localized"
                        ,"en":"b3"
                    }
                    ,"module": "module.b3"
                }
            ]
        }
        ,{
            "title": {
                "nunaliit_type":"localized"
                ,"en":"c"
            }
            ,"href": "./c.html"
        }
    ]
}
Navigation-Bar layout sketch

Navigation-Bar layout sketch

How to add new links to the navigation document:
Links in the navigation bar are represented by an object placed in an items array, which results in a list of hyperlinks in an atlas’ navigation.

Each link object, consists of a title attribute, and a link URL represented by either a ‘module’ attribute (used for hyper-links to other modules in an atlas) or a ‘href’ attribute (used for any website URL, including external content). In addition to these two attributes, an item in a list can have nested content (i.e. other links) by including an items array.

In the above sketch and corresponding nunaliit_navigation.json, there are three top level items a, b, and c, with the b link having three nested links, and once again the b2 having another nested list of two more links.

For example if I wanted to add a nested link under the c top level item to the nunaliit homepage, I would update the c item to look like the following;

...
,{
	"title": {
		"nunaliit_type":"localized"
		,"en":"C"
	}
	,"href": "./c.html"
	,"items":[
		{
		"title": {
			"nunaliit_type":"localized"
			,"en":"Nunaliit"
		}
		,"href": "http://nunaliit.org"
		}
	]
}

How to change the default atlas navigation document:

When an atlas is created, the default navigation document used by the atlas is the navigation.demo document. Although it is acceptable to use this navigation doc, you will likely want to change it as your atlas develops.

If you have another navigation document that you wish the atlas to use by default, you will need to change a single line of code in the nunaliit_custom.js file (located in the atlas’ htdocs directory). Within the window.nunaliit_custom.configuration function (typically located at the bottom of the nunaliit_custom.js file), you will see the following line;

customService.setOption('defaultNavigationIdentifier','navigation.demo');

To update the default navigation document, simply replace where it states navigation.demo with the replacement navigation document name.

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 )

Google+ photo

You are commenting using your Google+ 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 )

Connecting to %s