Nunaliit Tutorial: Replacing the atlas title text with an image

Description: One of the simplest ways to give your atlas a custom look is by replacing the atlas title text with your own atlas logo. This tutorial provides instructions on this task, producing similar results as shown in the comparison example below.

Default Text Title (left) vs. Image Title (right)

Default Text Title (left) vs. Image Title (right)

Step 1: Start by copying the replacement title image file to the atlas htdocs directory. For this example I’ve created an images directory containing a file called logo.png, which is 200px in width and 50px in height.

Note: If you’re creating an image, the Nunaliit title bar’s height is 70px by default. If you want to maintain the dimensions of the original title bar, you should make the height of the logo no larger than that.

Step 2: Replace the existing navigation document title attribute (located in the nunaliit_navigation.json file) with an empty string, “” (see example below). Note: This is required to prevent the title text from appearing over top of the image.

{
	"nunaliit_type": "navigation"
	,"title": ””
	,"items":[
	. . .
	]
}

Step 3: With the title text removed and the image file added to the htdocs directory, the remaining steps focus on updating the atlas CSS style rules. All style changes made to the atlas should be defined in the atlas.css file located in the htdocs/css/ atlas directory.

The first style change is to assign the image as the background of the previous title text location, identified by the class ‘.nunaliit_title’ which is located within the ‘.nunaliit_atlas’ div. Copy the following example CSS code to the atlas.css file which defines the background as using the image file logo.png located in the images directory. Note: you will need to update the background URL to your file’s location in the htdocs directory and also update the dimensions to your desired image size.

.nunaliit_atlas .nunaliit_title {
    background: url(../images/logo.png);
    background-size: contain;
    background-repeat: no-repeat;
    width: 200px;
    height: 50px;
}

At this point, your atlas should display your image in the atlas title location, once the atlas is updated. If its not appearing, make sure the location of the file is correct for the background URL.

Step 4: The final step is to increase the size of the title link to match the size of the new title image using padding. This will result in the background image behaving similar to the text title when clicked by a user.

Copy the following CSS code into the atlas.css file and update the padding to match the dimensions of your image. For example if your image is 180px wide and 60px high, you will need the following rule “padding: 30px 90px”.

.nunaliit_atlas .nunaliit_title_link {
	/* 	25px padding added to the top and bottom sides
		100px padding added to the left and right sides */
	padding: 25px 100px;
}

Congratulations, you have now successfully replaced your default title text with a logo.

Advertisements

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.