Create a new skin

Prerequisites

Changing a skin can be as easy as creating some new icons for the on-screen buttons or as complex as programming new functionality into the user interface (for example, the way you navigate through the places). The required skills are different.

To change to look and feel of a skin you need experience in graphic design and familiarity with CSS (Cascading Style Sheets) and HTML. To create new functionality you also have to be proficient in the Javascript programming language and possibly know the Google Maps^TM API.

The structure of a skin

Skins are stored in the skin directory contained in the distribution. Each skin is contained in a directory of its own and in any JourneySat distribution you should find the Basic and Maya skins.

Every skin directory should conform to this structure:

• README.txt, the instructions to use the skin.
• skin.html, a file containing the HTML elements required by the skin and the minimal code that can turn the skin in a valid HTML page.
• skin.js, a file that contains the entry point of the Javascript code for the skin.

Any other file (HTML, Javascript, XML or CSS) should be placed into this directory. Icons and pictures should be placed in subdirectories.

As a reference, you can check how the files are arranged in the Maya and Basic skins.

Changing the appearence of a skin

If you like the functionality provided by a skin and all you want to do is changing it's look and feel you have to find out where it stores its icons, its CSS and its HTML code.

The Basic and Maya skins share the same directory structure. The icons are stored inside a directory called icons, the CSS is in style.css and the HTML in skin.html. By reading the README.txt file you'll also find out that there are two small files, named en.xml and it.xml that contain the English and Italian translations of the user interface.

To change the icons, the colors of the elements on the screen and to the translations you have to change the contents of the graphic files inside icons, the definitions in style.css and the text in the two small XML files. To change the position of HTML elements in the user interface you have to work on skin.html.

If you want to add new HTML elements or new translations you'll have to work on skin.html and possibly also on skin.js (check for the occurrences of the lang object). However this is on the borderline between cosmetic and functional changes so it is covered in the next section.

Changing the behaviour of a skin

The skin behaviour is programmed in skin.js. Every skin can have its own behaviour and that should be documented in README.txt. This section explains how the Basic and Maya skins work.

Those skins are started by the HTML code in skin.html by Javascript code such as:

    var travel = new JourneySat.Travel();
    travel.setDataFile("template.xml");
    var skin = new JourneySat.BasicSkin();
    //skin.showCoordinates(true);
    startSkin(travel, skin, "en");

The last line activates the skin. This is a complex procedure made of the following steps (check skin.js for reference)

• Creation of a JourneySat.ResourceBundle object that stores the strings in the user interface given the selected language. One of the parameters of the constructor is a function (named i18n) that puts some of those strings on-screen.
• Definition of the names (the values of id attributes) of the relevant HTML elements and of the URLs of files it has to load.
• Registration of a callback of the JourneySat.Travel object. That callback is triggered when the XML data file describing the travel has been loaded and parsed. The callback runs the function initScreen that creates the user interface.
• Registration of the callbacks for all the buttons of the user interface.
• Initiation of the XML data file loading process with the line skin.start(travel);

skin.start performs a few checks and calls travel.load(). This function is defined in travel.js and as it is in the core of JourneySat it is out of the scope of the present discussion.

What we need to know for now is that control goes back to the code in skin.js when travel.load eventually triggers the callback previously registered in startSkin, running the initScreen function. Among the other things it displays the icons of the photos and registers the callbacks that open the popup windows for the photos.

However the single most important thing to know is how to navigate the tree-like data structure that stores the information about the travel. The travel is stored in an object of type JourneySat.Travel. The method getCurrentDay() returns an object of type JourneySat.Day which contains the date and sequence number of the day.
The method getCurrentPlace() returns a JourneySat.Place object containing the description, latitude, longitude, name and zoom level of the place.
JourneySat.Place has the getContentArray method that returns the contents defined in the current place as an array of JourneySat.Content objects. The order of the array is the order of contents definition in the XML file. The contents inside a place can also be browsed using the prevContent, nextContent and getCurrentContent methods.

The JourneySat.Travel object has methods to navigate through days, places and contents: firstDay, nextDay, prevDay, lastDay, firstPlace, nextPlace, prevPlace, lastPlace, goToPlace, prevContent, nextContent.

Details on the attributes and methods of those classes can be found in the API reference

Learning how to navigate through days, places and contents and alter the callbacks registered for the HTML elements should be enough to create user interfaces for JourneySat.
If you want to change anything related to the satellite map you have also to use the Google Maps^TM API.
Creating something totally diffent might involve using the <type>, <cbody> and <zoom> tags inside <content> in creative ways.

The Next Step

After modifying or creating a skin or two you might want to add new features to JourneySat. Maybe you want to add new kinds of information to the data file and extend the Place or the Content classes. The next section describes the internals of the current implementation of JourneySat.