Embedding Javascript

To include Javascript in your page:

1. use a Content Editor Webpart (CEWP)
2. edit via the Source Editor button (not Rich Text Editor), and
3. add your code within standard <script></script> tags

Within the script block just add your normal code, comments, etc. The only issue you’ll have is being able to indent the text and make it look pretty. Tab doesn’t help; you’ll need to use spaces (the horror!).

Don’t use the Rich Text Editor
Important! Always use the Source Editor function to manipulate your code, or any other content within the same CEWP. If you use the Rich Text Editor at any point it will delete all your script.

Linking to Javascript source files

Sometimes your javascript code may be a little too long to embed. Or, like me, you’ve been burnt once too often by clicking the Rich Text Editor button by mistake. At such times you might prefer to link to separate javascript files rather than embedding all directly.

To link to a separate file:

1. save the Javascript content as a separate .JS file and upload to somewhere on your site. I tend use a /scripts subfolder within the default documents library.
2. add/edit your CEWP to reference the script file:

<script type="text/javascript" src="full path to script file"></script>

For example, here’s a CEWP that includes a separate Javascript file and then references a function (presumably) defined within it.

I won’t provide any more oxygen to the hackers over what exactly happened, but here’s the steps taken to get back online.

(1) Run to Google

As always, find a friend who’s been through it before. In particular these two pages proved useful.

• http://codex.wordpress.org/FAQ_My_site_was_hacked
• http://ocaoimh.ie/2008/06/08/did-your-wordpress-site-get-hacked/

First steps taken after reading them (and they explain more about each step):

• change passwords (for both wordpress and mySQL)
• setup secret keys and salts
• check .htaccess
• delete all unused themes

(2) Install the exploit scanner

There is a plugin available that can help check for suspicious code:

http://ocaoimh.ie/exploit-scanner/

Follow the provided instructions to install.

When I ran the scanner it located dodgy code in a plethora of files. Comparing those files to a (sadly) old backup I discovered they were not part of the original wordpress installation. They also, suspiciously, all had an identical and recent install date/time.

Therefore next step was to delete them all. And that did most of the work. I got my site back. Almost….

(3) Fix the theme

After deleting all the extra files, the site was almost back. It now did not show the “you’ve been hacked page”. But instead it showed the contents of my theme’s CSS file. Obviously some corruption in there somewhere.

First step was to temporarily install a basic theme and switched to that. All worked well and my site was back up and running. Just ugly(er). To improve I then deleted the corrupted theme and re-installed from a backup. And everything was back to normal.

Conclusion

Thankfully my intrusion proved quite simple to remove. Whether I removed every element we’ll find out in the next days as we see how long the site stays up. However lessons learnt are quite simple:

1. get a recent/regular backup (of content and data). Having another folder listing what files should be there proved invaluable in quickly deleting what was added.
2. keep up to date with releases.
3. if you’re site suddenly gets blocked by a web filter, don’t blame a rude commenter!

After the fun of working out how to build these maps by hand, a colleague pointed out that there are online services available that can do all the hard work for you. One we tried, and recommend, was http://batchgeo.com/. Worth a look, even if you’re a masochist and want to go manually.

Getting started

All the information you need to work with Google Maps is published here:
http://code.google.com/apis/maps/documentation/javascript/basics.html

But all you really need to know for working it into your website is:

• the API is in Javascript
• it works very well with JQuery, and
• it’s free (commercial or otherwise) unless you’re hitting their server big time.

Tempting? Read on.

Step 1 – Drawing a map on your site

The basic code to include a Google Map on your site is very straightforward. Start with this template:

<html>
<head>>
  <script type="text/javascript"
          src="http://maps.googleapis.com/maps/api/js?sensor=false">
  

	function initialize() {
    		var myOptions = {
      		zoom: 5,
      		center: new google.maps.LatLng(-25.363882,131.044922),
      		mapTypeId: google.maps.MapTypeId.ROADMAP
    	}

	var map = new google.maps.Map(document.getElementById("map_canvas"),
                                      myOptions);

	}
  </script>
</head>

<body onload="initialize()">
  <div id="map_canvas"></div>
</body>
</html>

This will publish a Google Map, centred on Uluru, Australia, and zoomed to show the whole country. Play with the values in the options set to establish the default map you prefer.

Working with latitude and longitude

The centre of your map needs to be a position given in latitude and longitude. If you don’t happen to know the figures then there is a way to get them out of Google Maps.

1. Go to the location you want the coordinates for
2. Right-click on the location and select What’s Here from the menu

The coordinates you require will then appear when you hover over the location on the map. More usefully, they also are pasted into the search box, from where you can copy&paste them into your code.

Improvement 1: Adding points of interest

Each point you want to position on your new map is known as a marker.

http://code.google.com/apis/maps/documentation/javascript/overlays.html#Markers

It’s just one line of code to add one. Let’s put one at Mount Isa, near the centre of our new map.

var marker = new google.maps.Marker({
	position: new google.maps.LatLng(-20.722481,139.494781),
	map: map,
	title: "Mt Isa"
	});

The value for map must match the map object you previously created. The marker will then appear at the position you give, with the title appearing on hover.

A fourth option, icon allows you to specify a different icon for your marker to the Google default hot air balloon. Any image file is satisfactory, but for a decent range of alternatives check out http://mapicons.nicolasmollet.com/.

To use, just upload the icon somewhere you can link to it, and add the URL to your marker:

var marker = new google.maps.Marker({
	position: new google.maps.LatLng(-20.722481,139.494781),
	map: map,
	title: "Mt Isa",
        icon: "needsAttention.png"
	});

Adding a popup window

The title gives you room for brief information on the location, visible only on mouseover. For something a little more descriptive you can add a popup window to display when the user clicks on the point. The window remains in view until the user chooses to close it:

In Google Maps speak, these are known as InfoWindows. The key point when working with them is that you first need to create your window’s content (any valid HTML will do), and then you create the link so that the window appears when the user clicks on your marker.

	var info = "<p>Here's some extra information&lt/br />over two lines.</p>";
	google.maps.event.addListener(marker,'click', function() {
		infowindow = new google.maps.InfoWindow({content: info});
		infowindow.open(map, marker);
		});

Tips:

• The marker in the final line must match the variable name for the marker you’re connecting to.
• You can use any styling/layout tricks you want to make the popup look prettier.
• Google will try and size it for you automagically, unless you force specific sizing.

Scaling for multiple points

The code so far is great for just a few points, but soon becomes painful with any reasonable number. Moreso if the information you want to present needs to change (e.g. a status message for each location is updated regularly).

So for the final version we’ll start leveraging JQuery and JSON to generate our markers from a separate list. For now we’ll keep that list in the same file, but it’s relatively simple to integrate via a different file or format.

First the data. Obviously this can be any values that you want to present, just ensure each record has the same structure.

var branches =
[
	{
	"title":	"Uluru",
	"position":	[-25.363882,131.044922],
	"deploymentDate": "23 April 2012",
	"trainingDate": "13 March 2012",
	"status": "Not Started"
	},
	{
	"title":	"Alice Springs",
	"position":	[-23.700651,133.880038],
	"deploymentDate": "23 April 2012",
	"trainingDate": "13 March 2012",
	"status": "On Schedule"
	},
	{
	"title":	"Avalon Beach",
	"position":	[-33.636248,151.329197],
	"deploymentDate": "23 April 2012",
	"trainingDate": "13 March 2012",
	"status": "Needs Attention"
	},
	{
	"title":	"Kent St",
	"position":	[-33.866229,151.204190],
	"deploymentDate": "23 April 2012",
	"trainingDate": "13 March 2012",
	"status": "Not Started"
	}
]

Now the JQuery to loop through our data and add the markers:

$(branches).each(function() {
	var branch = this;
	var title = branch.title + ": " + branch.status;

//create the marker
	var marker = new google.maps.Marker({
		position: new google.maps.LatLng(branch.position[0], branch.position[1]),
		map: map,
		title: title,
		});

//create the infoWindow
	var info = "<h2>" + branch.title + "</h2>";
	info += "<p>training date: " + branch.trainingDate;
	info += "<br />deployment date: " + branch.deploymentDate + "</p>";
	info += "<p>status: <b>" + branch.status + "</b></p>";

//link marker to infoWindow
	google.maps.event.addListener(marker,'click', function() {
		infowindow = new google.maps.InfoWindow({content: info});
		infowindow.open(map, marker);
		});
});

Add this and the data into your initialise method. And remember to include the JQuery script reference in your head.

side note – How to publish this map in Sharepoint?

Adding this content to Sharepoint is complex because of the need to include the separate Javascript libraries. As a result the simplest approach is to use an iframe. Build your map as a standalone webpage, then embed it via an iframe defined within a Content Editor Webpart.

Conclusion

As you can see it’s reasonably simple to embed a smart map on your site that identifies and describes points of interest to your users.

If you want to try for yourself, here are some sample files to get you going:

• simple/manual (1 marker, 1 window) – good template if only a small number of locations
• multipoint (uses jQuery/JSON approach as described) – best if wanting to map too many points to manage manually.

If using the multipoint template, one “exercise for the reader” is to make it so that if a user has one infoWindow open, selecting a different point automatically closes the currently open window before opening the new one. Currently this code allows the user to open multiple windows simultaneously.

Hard to tell which one to choose when everything you want to know about the choices is unavailable. Should I get the “Lego Y..” or, mmmmm, the other “Lego Y..”?

Compare to Amazon, who manage to fit the full name in without issue:

If you’re going to allow a certain number of characters for a value, assume all of those characters may be important at some point. And make sure somewhere on your interface you let them all get their moment in the sun.

Turns out this “feature” is decided by Apple based on your region. They believe Australian weeks start on Sunday so that’s the way it is. To change the day, change your region.

For Australians wanting their calendar to start on a Monday:

1. Launch settings
2. Select General > International
3. change region format to Namibia

This bizarre choice seems to have the best option for calendar setting, as well as changes it makes to keyboards (what currency symbol you see), date and time formats, even which google you default to when you search. Namibia appears to leave all the other settings “just like Australia”, and still default to google.com.au for searching in Safari.

Thanks to the clever chaps on the Whirlpool forums, particularly dokh22, for uncovering this. Now how long before Apple gives us a calendar setting to do it properly?

This post was inspired by a colleague who had not uncovered that fact, and so had spent time arduously linking separate views with timers. This post shows how to use a single view and 3 lines of animation code to do all the work.

What to do?

What we’ll do as a test is animate the blinking eyes on a tennis-playing ninja splash screen. To trigger the animation will add a “blink” button on the same screen.

Don’t ask how we ended up with that as the example (thanks to the friend). But you can download the entire project, or just the images if wanting to join in.

• download the project
• download the images

The steps:

1. prepare the images
2. create the project
3. create/update a XIB with the image and button
4. add the animation code and link to the same image and button

All the neat animation stuff is described in the 4th step, so feel free to scroll straight to it. The previous three steps cover all that’s needed to get your project ready to animate. I’ve included it because I hate reading articles that assume you’ve covered all the basics already. Or worse just dismiss it with one line (first step, invent time travel).

Note this process was captured in xCode4/IOS5. None of the code in here has changed much in recent releases but you may have to adjust some of the steps if running an earlier setup (one thing that has changed in this version is the options when creating a project).

(1) prepare the images

Your imagery is limited only by your artistic talents, or abilities to search Google Images or Flickr (remember to honour their copyright, boys and girls).

Only suggestion is to limit the animation element to the smallest possible; keeps sizes small. For example, for the blinking ninja, instead of 3 different ninjas with different eye positions (open, half closed, closed), I created one ninja with no eyes, and then three images of just the different eyes. What we’ll do in the project is then add the main ninja as one image view, and put the eyes over the top in a separate image.

Whatever approach you take, ensure all the images that will be animated are the same size. This will ensure when animated they appear over each other.

create the project

Crack open Xcode and choose File > New Project. I’m in the latest and greatest (4.2) so your options may vary, but for this version:

• choose Single View Application
• choose not to use storyboard (so we get a XIB to mess with)

Once created we have a simple project containing the key source files:

• appDelegate.h
• appDelegate.m
• ViewController.h
• ViewController.m
• ViewController.xib

The good news is we’re only going to be editing the three ViewController files. Which means you can pretty much follow all of these steps to add an animation to an existing view within your current application; just join in from the next step.

Now add your animation images to the project. Either right-click in the folder view and select Add Files To.., or choose File > Add Files To.. from the menu.

(2) create/update XIB with the image and button

Our XIB has already been created in the project. What to do now is setup the images and buttons we meed, including the outlets needed so we can communicate with them from our code.

Firstly the images. Remember we need to add two: 1 as the background (which we don’t need to interact with) and one for the animated eyes (which we will need to talk to).

To hook things up let’s create the outlets first, and then link in the XIB. Open ViewController.h and add our definition (new text in bold):

#import 

@interface ViewController : UIViewController {
    IBOutlet UIImageView *eyesImage;
    IBOutlet UIButton *blinkButton;
}

@property (nonatomic, retain) IBOutlet UIImageView *eyesImage;
@property (nonatomic, retain) IBOutlet UIButton *blinkButton;

@end;

Then switch over to ViewController.m (tip: 3 fingers down gesture if using a trackpad) and synthesize them:

@import "ViewController.h"

@implementation ViewController

@synthesize eyesImage;
@synthesize blinkButton;

Remember if we create them, we should also destroy them:

- (void)viewDidUnload
{
    [superviewDidUnload];
    // Release any retained subviews of the main view.
    // e.g. self.myOutlet = nil;
    self.eyesImage = nil;
    self.blinkButton = nil;
}

That gives us our outlets so we can link to, and manipulate these items on our XIB.  Note we don’t currently need to manipulate the button but the outlet is there just in case (for example if needing to disable the button at some point).

The only other item to add in the code before we edit the XIB is the method to be called when we click the button.

Back into viewController.h and add the definition:

#import 

@interface ViewController : UIViewController {
    IBOutlet UIImageView *eyesImage;
    IBOutlet UIButton *blinkButton;
}

@property (nonatomic, retain) IBOutlet UIImageView *eyesImage;
@property (nonatomic, retain) IBOutlet UIButton *blinkButton;

- (IBAction) blink;

@end;

And then back to ViewController.m, and insert the method somewhere in the list:

- (IBAction) blink {
  //blink
}

Save the files and we’re ready to connect them to elements in the XIB.

Firstly open the XIB and drag an imageView onto the work area.
Set the size and content to be our background/static image for the animation.    Don’t worry with any outlets as we never need to talk to this image.

Now add a 2nd image view to the work area.  Set its position and size to match where the animation is to be presented.  If it helps you with positioning, set the default image to the first of your animation frames.

Once the animated image view is in place, hook up the outlet.  We need to link this to our eyesImage outlet so we can manipulate it.  Just select the Outlets panel for the view, click in the circle for Referencing Outlet and then drag to File’s Owner on the left side of the work area.  if all has worked you’ll then get a dropdown list in which you can select eyesImage.  Once selected your outlet will be added.

That’s all you need to do for the animation.  Now for the button.

Drag a Round Rect Button onto the work area and position somewhere appropriate.  Then add a suitable label (“blink” comes to mind).  View the Outlets panel for the button and drag from the Referencing Outlet to File’s Owner (as we did for the image) and select the blinkButton outlet.  And then, to link to our blink method, drag from the TouchUpInside outlet to the same File’s Owner.  If all has worked you’ll then be able to select blink and connect it up.

So that’s all the XIB sorted.  We’ve got a background/static image.  We’ve got a smaller image with an eyesImage outlet for the animation.  And we’ve got a button that when clicked will trigger our blink() method.  Only one step to go.

Save your XIB and then run your project.  You won’t see anything moving but at least your background image should be in view.

add the animation code and link to the image and button

Now for the fun part.

To animate an image we load up the image view with an array of images, set some parameters for how fast and how long the animation runs, and then start it off.  For efficiency we’ll put all the animation setup into viewDidLoad (so done once when the view first appears), and then just trigger the animation each time we click the button.

So back into viewController.m, let’s first setup the animation:

- (void)viewDidLoad
{
    [superviewDidLoad];
    
        
       //setup animation
    NSArray *eyeFrames = [NSArrayarray];
    eyeFrames = [[NSArrayalloc] initWithObjects:
                 [UIImageimageNamed:@"eyes1-open.png"],
                 [UIImageimageNamed:@"eyes2-half.png"],
                 [UIImageimageNamed:@"eyes3-closed.png"],
                 nil];
    eyesImage.animationImages = eyeFrames;
    eyesImage.animationDuration = 0.25;
    eyesImage.animationRepeatCount = 1;
    [eyeFrames release];   
    

}

We’ve added an array of three images to our eyesImage outlet. The animation will take a quarter of a second and will only run once.  Once implemented you’ll return to these settings (often!) to get the appearance just right.

Once setup, triggering it is just one line of code:

- (void) blink {
    [eyesImage startAnimating];
}

Save and run your project. Then everytime you click the button, magic happens.

Conclusion

While it took a while to get there, animating our image took only 7 lines of code.  Armed with that code you are limited by only your graphical capabilities.  Just build your images, repeat the 7 lines, and then spend an age tweaking the duration to get it looking right.  

After a while you may find this approach a bit too limited as it scrolls through the image frames at a regular pace.  If wanting a bit more control over the animation  pace, then you’ll need to step up and start using proper animation blocks.  Next time.

However what wins is the wireless synchronisation feature. Now I can update my library (songs, books, tv) on my computer and click Sync. And the iPad gets updated while not connected. While not even switched on. While in my briefcase in another room.

Sweet.

[Although I'll admit it's probably sweet because Apple kept us tethered for far too long!]

When I’m editing frame properties, don’t present a tooltip that has the unerring habit of appearing directly over the top of where I’m trying to type!! B!@#y annoying.

This article expands that earlier introduction with some tips and tricks we collating when implementing this for one client:

• working outside Sharepoint
• presenting a URL
• sorting items
• grouping items
• showing a message if a filter set is empty

Note: You can download sample XML and XSL here. These files show all the techniques described in this article.

the original XML	filtered view	grouped view

Working outside SharePoint

It can be painful to develop your XML/XSL solution in Sharepoint because of the need to upload new versions (or edit webparts), then refresh to see the results, or lack thereof. Easier to work outside and just upload when done.

To link your XML and XSL outside SharePoint edit your XML file to include a link to your XSL file:

<!--?xml version="1.0" encoding="utf-8"?-->
<!--?xml-stylesheet type="text/xsl" href="calendar.xsl"?-->
....

Now when you open your XML file in a browser it will use your XSL to present.

Save your XLS as a file with a name to match the XML link and you’re nearly there. The only other change you may need to make is to extend your XSL so it generates a full webpage, not just a fragment.

For example our standard calendar presentation XSL generates a paragraph:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="calendar">
<p>
<xsl:for-each select="event[program='Leadership Foundations']">
...
</xsl:for-each>
</p>
</xsl:template>
</xsl:stylesheet>

To work outside SharePoint it needs to generate a proper page; make it do so by simply adding HTML and BODY tags:

<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="calendar">
<html>
<body>
<p>
<xsl:for-each select="event[program='Leadership Foundations']">
...
</xsl:for-each>
</p>
<body>
<html>
</xsl:template>
</xsl:stylesheet>

Just remember to remove these bonus lines when re-inserting into your SharePoint site.

Presenting a URL

If one element you’re recorded in your XML is a URL then chances are you’ll want to use XSL to convert that into a link. And the obvious approach you’d think would be the simplest:

<a href='<xsl:value-of select="link">'>link text</a>

Other than the issue over nested quotes, all looks pretty straightforward. Except it doesn’t work.

The solution is to use a different format for the URL selection:

<a href="{link}">link text</a>

Now it works fine.

Sorting items

One feature we wanted to implement was the automatic sorting of results. This meant anyone maintaining the master XML list did not need to worry about where to add individual items to preserve their order. They could just add anywhere in the file and be confident they’d appear in the correct sequence when displayed.

To sort results, add the <xsl:sort> command as the first element within your loop. For example to sort by a date element:

<xsl:for-each select="event">
    <xsl:sort select="date" />
    ...
</xsl:for-each>

Check W3Schools if wanting to do something more complicated than an ascending text order.

As you can see from this example, what we were wanting to search on were dates. And early on we’d decided that users would enter dates in “human” format (ie ’23 May 2011″, not 20110523). One issue we had on sorting dates was the chestnut of how to sort “2 May 2011″ to appear before “15 May 2011″. Our solution was to require all dates in the XML to be two characters (“02 May 2011″ not “2 May 2011″) and then use XSL to remove the ugly leading zero when displayed. The code to remove that zero is straightforward:

<xsl:choose>
    <xsl:when test="substring(date,1,1)=0">
         <xsl:value-of select="substring(date,2)" />
    <xsl:otherwise>
</xsl:choose>

You have to use the <xsl:choose> construct because while XSL does have an IF statement (not surprisingly <xsl:if>), it does not have an equivalent ELSE.

Note: The alternative would be to define the date in a nice sortable format (I vote for YYYYMMDD). And then use similar XSL transformations to present in a more readable format. Either way you’re putting some overhead on the user. We stuck with this simple approach because it was (a) less user effort and (b) allowed a wider range of dates to be acceptable. For example we had some programs that only specified a month. Sorting this way meant we could accept “May 2011″ as a valid date.

Grouping items

Now this I thought would be easy. Since we’re working on a calendar, let’s group entries according to the month. ie:

April 2011
- This course (12 April, London)
- That course (19 April, Helsinki)
May 2011
- That course (2 May, Romford)
- The other course (30 May, Malaka)

After several false starts, all roads do eventually lead to a fabled Meunchian method. Trouble is, even after building it, I’ve no idea how it works. Of all the articles uncovered to try and explain it, this one came closest. Cut&paste their approach (or our example using it) and you should be able to get it to work.

Showing a message if the filter set is empty

In the first article we covered how simple it is to present a subset of your entries. However once implemented we discovered we needed to address the situation where a subset was empty. Rather than just showing a blank list we wanted to show a messsage directing the visitor to other sources.

Simplest way to implement this is to repeat the same filter query used to generate the subset. Just place within a COUNT() and use as a test:

<xsl:choose>
     <xsl:when test="count(event[program='First Program']) > 0">

          <xsl:for-each select="event[program='First Program']">
          ...
          </xsl:for-each>

     </xsl:when>
     <xsl:otherwise>
          <xsl:text>No events recorded for this program.</xsl:text>
     </xsl:otherwise>
</xsl:choose>

Only potential issue may be around your formatting. Be mindful of where your layout tags appear depending on which data is presented.

Conclusion

With just these techniques you can present and manipulate your content in quite ingenious ways. Just good luck trying to understand the Muench.

This article assumes you are creating/editing your ePUB source content directly. If generating an ePUB via a development tool (eg Pages, InDesign) then it can automatically generate the TOC for you. However even if doing so this article will help describe what is being built for you.

To help, I’ve included a smorgasbord of sample ePUBs to demonstrate how tables of contents are included. There’s a basic book (single level/standard TOC) as well as books with 2, 3, 4, or 5 level TOCs.
Download the one you want or take the whole pack. Note that because WordPress considers EPUBs a security risk, they’ve all be zipped.

Do I need to do this?

A table of contents is optional (your ePUB is valid and usable without one). What’s more how it actually presents for your readers is dependent on the reader. As such you should decide for each book, and your target market, whether worth the development effort.

How do I do this?

Adding a table of contents to your ePUB has two key steps:

1. Creating a valid .NCX file
2. Including the .NCX file in your book

Let’s work through these steps in turn.

Creating a valid .NCX file

The .NCX file defines your table of contents. There’s no rule about what filename to give it, but the default option for most eBooks appears to be TOC.NCX. So we’ll assume we’ve called it that too.

The definition for your TOC.NCX file is not part of the ePUB specification but is instead maintained by the DAISY Consortium and co-opted by IPDF who manage ePUBs for us. Browse the detailed specification and see if you can find out what NCX stands for.

In essence an .NCX file is an XML file. It lists the elements for your table of contents within a simple and standard framework:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ncx
  PUBLIC "-//NISO//DTD ncx 2005-1//EN"
  "http://www.daisy.org/z3986/2005/ncx-2005-1.dtd">
<head>
	-- insert required metadata
</head>
<docTitle><text>DOCTITLE</text></docTitle>
<docAuthor><text>DOCAUTHOR</text></docAuthor>
<navMap>
	-- insert required navigation structure
</navMap>
</ncx>

Copy that and use as the basis for your TOC.NCX, while we fill in the missing bits: metadata, title, author, navigation structure.

(1) insert required metadata

Every .NCX file needs to define four metadata elements:

• dtb:uid – this is the unique ID for your publication.  It needs to match the ID given in content.opf.
• dtb:depth – this is the number of levels in your TOC. Normally this would be 1 but you can add more levels – see hierarchical contents below
• dtb:totalPageCount – this is not used: set to zero
• dtb:maxPageNumber – this is not used: set to zero

For example, here’s the .NCX header for a standard table of contents with only 1 layer of entries.

<head>
	<meta name="dtb:uid" content="a897sad23fd23ds" />
	<meta name="dtb:depth" content="1" />
	<meta name="dtb:totalPageCount" content="0" />
	<meta name="dtb:maxPageNumber" content="0" />
</head>

(2) record title and author

The document title and author should match those recorded in the main metadata within content.opf (DC:Title, DC:Creator respectively). Some readers may reference these values when displaying the contents, although those in my limited test suite all seem to ignore these values and focus on those in content.opf.

In the sample ePUBs included with this article I deliberate added “(NCX)” to the end of the title and author in each .NCX file. Just to see if/where it appeared. Never did. But your mileage may vary.

(3) insert required navigation structure

The navMap is where the entries in your table of contents are defined using special XML elements called navPoints.

<navPoint playOrder="x">
     <navLabel>Text to show in the table</navLabel>
     <content src="url" />
</navPoint>

The playOrder is numeric, indicating the sequence that the content elements should be traversed in when navigating.  Note that this does not need to match the order you list them (and they appear) in the TOC. Nor does it need to match the sequence in the <spine> section of content.opf.

My testing (and the OPF specification) indicate that the playOrder is not used to determine the sequence content is browsed. When users move through the content sequentially, this sequence is defined by the <spine> element in content.opf. However, even though playOrder is not used, it is recommended that meaningful values are recorded “just-in-case”. It also ensures your ePUB validation, if using epubcheck, will be successful.

The text will present as entered in your TOC; be mindful that not all readers will have a lot of room so don’t make the entries too long.

The URL needs to be the reference to the file/location that is the target of this TOC entry. This will be the filename if you have created separate chapter files. Else you could reference separate sections within a single document via anchor tags.

For example, here are sample entries from the start of one EBook.

<navPoint playOrder="1">
  <navLabel><text>cover</text></navLabel>
  <content src="00-cover.xhtml" />
</navPoint>
<navPoint playOrder="2">
  <navLabel><text>preface</text></navLabel>
  <content src="10-frontis.xhtml#preface" />
</navPoint>
<navPoint playOrder="3">
  <navLabel><text>credits</text></navLabel>
  <content src="10-frontis.xhtml#credits" />
</navPoint>
<navPoint playOrder="4">
  <navLabel><text>Chapter 1 - Background</text></navLabel>
  <content src="chapter1.xhtml" />
</navPoint>

Note: If using anchor tabs, the other end of the link needs to be to an ID, not name tag. Read this for the explanation.

Including the .NCX file in your book

Only two small changes are made to your existing eBook to include your .NCX content, both made to content.opf:

• add your TOC.NCX file to the ebook manifest. Application type needs to be
  application/x-dtbncx+xml
• add a reference to the new TOC.NCX to your ebook spine. This is added as an attribute in your <spine> tag:

<manifest>
  <item href="toc.ncx" id="ncx" media-type="application/x-dtbncx+xml"/>
  ...
</manifest>

<spine toc="ncx">
  <itemref idref="chapter1" />
  ...
</spine>

That’s it. Save CONTENT.OPF, build and test.

Next steps

Once you’ve mastered the basic table of contents, you’re ready to investigate some more advanced options:

hierarchical contents

You can create multiple levels in your table of contents simply by nesting your navPoint elements.

...
<navPoint id="navpoint" playOrder="1">
          <navLabel>Chapter 1
          <navPoint playOrder="2">
Section 1</navPoint>
          <navPoint playOrder="3">
Section 2</navPoint>
...

Don’t forget to work through the playOrder values to retain a logical sequence to your content. Even though not sure who/where these values are used

How hierachical contents are displayed or navigated depends very much on the reader. It also appears to vary how many levels of content are supported. The standard itself sets no limits (or tells you what to call them: chapter, part, section, ..). However mileage may vary with different readers so don’t go overboard. The following table shows results with the two readers I spend most of my time with: Adobe Digital Editions (ADE) and iBooks (on the iPad). The two columns for ADE show the default view (when first opening your book) and the expanded view.

single level (basic book)
two levels
three levels
four levels
five levels

Notice:

• for iBooks, it gives up after 2 levels of contents. Unable to find anything official that states that’s a limit, but if aiming for that platform I’d stop at 2.
• for Adobe Digital Editions, the menu gets a little confused at the deeper levels – notice at 5 levels of contents the first level does not appear. Not sure if anything can be done to fix that, but also reason to avoid going that deep.

The above images are taken from the sample ebooks included with this article. Feel free to use to test how well supported in your chosen reader.

multiple tables (pageLists and navLists)

The standard table of contents is defined within a navMap. This is the complete, logical structure of your book. However the .NCX specification also allows you add two additional types of references to your TOC:

• pageList – use if needing to offer navigation by page (rather than topic/section). Your ePUB can only include one pageList, and it cannot be hierarchical – one layer only.
• navList – use if wanting to offer other any other arbitrary collection of topics, for example a list of illustrations or a collection of chocolate recipes taken from your complete recipe book. You can have as many navLists as you want, although they too can only be single level. An additional element, navLabel, can be added to give a title to your collection.

The steps involved in defining and including these tables is complex enough to warrant their own article, coming soon.

Conclusion

A table of contents is a valuable addition to most books, particularly non-fiction or reference titles. Adding one is reasonably simple, and thus worth the effort. However keep to the basics if wanting to be functional in the widest range of readers.