Using the Laws.Africa Table of Contents API in your application.
This guide will take you through how to use the Table of Contents (TOC) API, part of Laws.Africa's Content API. After reading this guide you will know:
what the Table of Contents API is and why it's useful
how to call the Table of Contents API
how to integrate the Table of Contents into your website or application
how to display the Table of Contents and link it to the text of a work
how to use the Table of Contents to fetch a section, chapter or part of a work
What is the Table of Contents API?
The Table of Contents (TOC) API is a JSON description of the hierarchy and structure of a work. It's useful for including a Table of Contents in your website or application, or for helping your users navigate or explore the structure of a work.
For example, here's a screenshot of the Table of Contents for Cape Town's Animal By-law generated using the TOC API:
Here's an extract of the corresponding JSON from the Table of Contents API:
There is rich information about each element in the Table of Contents, including a type, number, heading, well-formatted title and URL. Each element may also contain nested children. For example, a part or chapter may contain sections.
Why the Table of Contents API is useful
The Table of Contents API simplifies the task of navigating the structure of a work, both for the user and programatically. It takes care of the complications of dealing with Akoma Ntoso, such as handling different legislative traditions, doing translations and formatting titles, so that you don't have to.
Use the Table of Contents API to:
put a clickable Table of Contents alongside a work on a webpage
help the user navigate the structure of a work
fetch certain parts, chapters and sections of a work directly from the API
The TOC API automatically adapts to the local legislative tradition of a country. For example, in South African legislation the Section is the basic unit. In other traditions, the Paragraph or Article is the basic unit. Laws.Africa handles this for you and generates a Table of Contents that takes local tradition into account.
Showing a Table of Contents alongside a work
The most common use of the Table of Contents API is to put a clickable Table of Contents alongside a work in a website. This helps the user understand the structure of the text and navigate to the sections that are most important to them.
We're going to add the Table of Contents as a series of nested ul and li elements, and each entry will be a clickable a element with a link to the matching portion of the text.
We're going to use three key attributes of a Table of Contents entry:
title – a formatted title for this entry, combining num and heading;
id – the ID of this element in the HTML body of the work returned by the Content API; and
children – a list of sub-entries underneath this entry.
First, let's assume you have fetched the work's HTML content from the /frbr-uri.html Content API and it's already on your webpage along with an empty element for the TOC:
1
<asideid="toc"></aside>
2
<articleclass="akoma-ntoso">(HTML from Content API goes here)</article>
Copied!
Let's also assume we have fetched the Table of Contents JSON from the API, and stored it the variable toc.
Now we're ready to add the Table of Contents as HTML to the page:
1
functionmakeToc(entries){
2
// the container for these entries
3
var ul = document.createElement('ul');
4
5
entries.forEach(function(entry){
6
var li = document.createElement('li'),
7
a = document.createElement('a');
8
9
// make a link such as <a href="#chapter-1">Chapter 1</a>
10
a.innerText = entry.title;
11
// the entry.id matches the corresponding HTML body element's ID attribute
<ahref="#section-2">2. Restriction on number of dogs</a>
19
</li>
20
<li>
21
<ahref="#section-3">3. Dog registration and licensing</a>
22
</li>
23
...
24
</ul>
25
</li>
26
</ul>
27
</aside>
Copied!
Fetching only a section, chapter or part of a work
The Table of Contents API also makes it easier to fetch portions of a work, such as a particular chapter, part or section. You can do this by using the url attribute of the TOC entry. Not all entries have a URL, so be sure to check first.
In this example we'll fetch the portion of the Cape Town's Animal By-law chosen by the user. Again, we'll assume that the Table of Contents JSON has been fetched and stored in the toc variable.
We'll use the TOC to populate a select element and then respond to a change by loading the HTML into a div.
1
<label>Choose a section:</label><selectid="toc-selector"></select>