Le fichier de navigation NCX

Navigation Center eXtended

Le format NCX est un format XML qui permet de décrire la structure de navigation d’un livre numérique. La spécification de ce format est dirigé et maintenu par le DAISY Consortium.

The Navigation Control file for XML applications (NCX) exposes the hierarchical structure of a Publication to allow the user to navigate through it. The NCX is similar to a table of contents in that it enables the reader to jump directly to any of the major structural elements of the document

Il est employé dans le cadre du format epub avec quelques modifications apportées par la spécification epub OPF.

Tout comme le format OPF, la bibliothèque python-epub propose un module à part entière pour manipuler ce format plus simplement.

La classe Ncx permet au développeur d’utiliser ce contenu au travers de ses différents attributs :

• Ncx.nav_map pour l’élément <navMap>

• Ncx.page_list pour l’élément <pageList>

• Ncx.nav_lists pour les éléments <navList>

Comprendre la structure

La clé pour comprendre comment utiliser le format NCX est sans doute de comprendre le principe d’une table de matière ; prenez l’exemple suivant :

• Volume 1

  • Partie I

    • Chapitre 1

    • Chapitre 2

    • Chapitre 3

  • Partie II

    • Chapitre 1

    • Chapitre 2

    • Chapitre 3

Cette structure est finalement très simple : un arbre aux ramification descendantes. Cette liste est une <navMap>, dont chaque élément est un <navPoint>.

Voici la même chose au format xml :

<navMap>
    <navPoint playOrder="1" id="vol1">
        <navLabel><text>Volume 1</text></navLabel>
        <content src="Text/vol1.html"/>
        <navPoint playOrder="2">
            <navLabel><text>Partie I</text></navLabel>
            <content src="Text/vol1/part1.html"/>
            <navPoint playOrder="3">
                <navLabel><text>Chapitre 1</text></navLabel>
                <content src="Text/vol1/part1.html#chap1"/>
            </navPoint>
            <navPoint playOrder="4">
                <navLabel><text>Chapitre 2</text></navLabel>
                <content src="Text/vol1/part1.html#chap2"/>
            </navPoint>
            <navPoint playOrder="5">
                <navLabel><text>Chapitre 3</text></navLabel>
                <content src="Text/vol1/part1.html#chap3"/>
            </navPoint>
        </navPoint>
        <navPoint playOrder="6">
            <navLabel><text>Partie II</text></navLabel>
            <content src="Text/vol1/part2.html"/>
            <navPoint>
                <navLabel><text>Chapitre 1</text></navLabel>
                <content src="Text/vol1/part2/chap1.html"/>
            </navPoint>
            <navPoint>
                <navLabel><text>Chapitre 2</text></navLabel>
                <content src="Text/vol1/part2/chap2.html"/>
            </navPoint>
            <navPoint>
                <navLabel><text>Chapitre 3</text></navLabel>
                <content src="Text/vol1/part2/chap3.html"/>
            </navPoint>
        </navPoint>
    </navPoint>
</navMap>

Vous aurez sans doute remarqué plusieurs choses :

• L’attribut playOrder est global : il indique l’ordre de lecture

• Cet attribut est cependant optionnel

• Un <navPoint> représente une entrée de la navigation

• Un <navPoint> peut avoir lui-même plusieurs <navPoint> en fils

• Le contenu pointé par un <navPoint>, via sa balise <content> n’est pas un chemin d’accès mais une url relative à l’emplacement du fichier NCX

Armée de cette nouvelle compréhension, utiliser un objet Ncx ne devrait plus être un gros problème.

API du module

La fonction parse_ncx

epub.ncx.parse_ncx(xml_string)

Analyse les données xml au format NCX, et retourne un objet de la classe Ncx représentant ces données.

Paramètres:

xml_string (string) – Le contenu du fichier xml NCX.

Type renvoyé:

Ncx

La classe Ncx

class epub.ncx.Ncx

Représente le fichier NCX d’un livre numérique. Un fichier NCX est un fichier xml respectant les spécifications de la norme NCX avec les modifications apportées par la spécification Epub.

xmlns

Namespace utilisé pour le document NCX, dont la valeur devrait toujours être 'http://www.daisy.org/z3986/2005/ncx/'.

version

Version du fichier NCX, dont la valeur devrait toujours être '2005-1'.

lang

Langue du contenu du fichier NCX.

uid

Identifiant unique du livre.

depth

Représente la meta-donnée dtb:depth.

total_page_count

Représente la meta-donnée dtb:totalPageCount.

max_page_number

Représente la meta-donnée dtb:maxPageNumber.

generator

Représente la meta-donnée dtb:generator.

title

Titre du livre.

authors

Liste des auteurs du livre.

nav_map

Objet de la classe NavMap représentant l’élément <navMap> du fichier NCX. Cet attribut permet d’accéder à la structure de navigation principale.

page_list

Objet de la classe PageList représentant l’élément <pageList> du fichier NCX.

nav_lists

Liste d’objets de la classe NavList représentant les éléments <navList> du fichier NCX.

Il peut n’y avoir aucun élément dans cette liste.

add_nav_list(nav_list)

Ajoute un object NavList à la liste des NavList.

Paramètres:

nav_list (epub.ncx.NavList) – la liste à ajouter

as_xml_document()

Retourne l’élément XML Dom correspondant à la structure de l’objet.

Type renvoyé:

xml.dom.Element

Les classes NavMap et NavPoint

class epub.ncx.NavMap

identifier

Identifiant de la NavMap. Chaîne de caractère (peut être vide).

labels

Liste des labels de la NavMap : chaque label et un tuple de la forme (label, lang, dir), indiquant respectivement le titre du label, sa langue, et la direction d’écriture (ltr ou rtl).

infos

Liste des infos de la NavMap : chaque info et un tuple de la forme (info, lang, dir), indiquant respectivement le contenu de l’info, sa langue, et la direction d’écriture (ltr ou rtl).

Une « info » est simplement une description de l’élément.

nav_point

Liste des éléments <navPoint> en fils direct de l’élément <navMap> (et pas ses petits fils). Chaque élément de cette liste est un objet de la classe NavPoint.

add_label(label, lang='', direction='')

Paramètres:

• label (string) – Texte de l’élément navLabel.

• lang (string) – Langue de l’élément.

• direction (string) – Direction du texte rtl ou ltr.

add_info(label, lang='', direction='')

Paramètres:

• label (string) – Texte de l’élément navInfo.

• lang (string) – Langue de l’élément.

• direction (string) – Direction du texte rtl ou ltr.

add_point(point)

Ajoute un objet NavPoint à la liste des navPoint.

Paramètres:

point (epub.ncx.NavPoint) – ajoute un NavPoint à la liste de navPoint.

as_xml_document()

Retourne l’élément XML Dom correspondant à la structure de l’objet.

Type renvoyé:

xml.dom.Element

class epub.ncx.NavPoint

identifier

Chaîne de caractère, identifiant du <navPoint>.

class_name

Chaîne de caractère, indique la classe css proposée.

play_order

Chaîne de caractère, indique le placement dans l’ordre de lecture de l’élément. Peut être vide.

labels

Liste des labels du <navPoint> : chaque label et un tuple de la forme (label, lang, dir), indiquant respectivement le titre du label, sa langue, et la direction d’écriture (ltr ou rtl).

src

Chaîne de caractère, indique l’url relative à l’emplacement du fichier NCX, et pouvant pointer vers des fragments de fichiers du fichier epub.

Exemple : Text/chap1.xhtml#p36 indique le fichier Text/chap1.xhtml et plus spéficiquement à l’emplacement du fragment p36.

nav_point

Liste des éléments <navPoint> fils directs. Chaque élément est un objet de la classe NavPoint.

add_label(label, lang='', direction='')

Paramètres:

• label (string) – Texte de l’élément navLabel.

• lang (string) – Langue de l’élément.

• direction (string) – Direction du texte rtl ou ltr.

add_point(point)

Ajoute un objet NavPoint à la liste des navPoint.

Paramètres:

point (epub.ncx.NavPoint) – ajoute un NavPoint à la liste de navPoint.

as_xml_document()

Retourne l’élément XML Dom correspondant à la structure de l’objet.

Type renvoyé:

xml.dom.Element

Les classes PageList et PageTarget

class epub.ncx.PageList

identifier

Chaîne de caractère, identifiant du <pageList>.

class_name

Chaîne de caractère, indique la classe css proposée.

labels

Liste des labels du <navPoint> : chaque label et un tuple de la forme (label, lang, dir), indiquant respectivement le titre du label, sa langue, et la direction d’écriture (ltr ou rtl).

infos

Liste des infos de la NavMap : chaque info et un tuple de la forme (info, lang, dir), indiquant respectivement le contenu de l’info, sa langue, et la direction d’écriture (ltr ou rtl).

Une « info » est simplement une description de l’élément.

page_target

Liste des éléments <pageTarget> fils directs. Chaque élément est un objet de la classe PageTarget.

add_label(label, lang='', direction='')

Paramètres:

• label (string) – Texte de l’élément navLabel.

• lang (string) – Langue de l’élément.

• direction (string) – Direction du texte rtl ou ltr.

add_info(label, lang='', direction='')

Paramètres:

• label (string) – Texte de l’élément navInfo.

• lang (string) – Langue de l’élément.

• direction (string) – Direction du texte rtl ou ltr.

add_target(page_target)

Ajoute un élément PageTarget à la liste des pageTarget.

Paramètres:

page_target (epub.ncx.PageTarget) – l’élément à ajouter

as_xml_document()

Retourne l’élément XML Dom correspondant à la structure de l’objet.

Type renvoyé:

xml.dom.Element

class epub.ncx.PageTarget

identifier

Chaîne de caractère, identifiant du <pageList>.

labels

Liste des labels du <navPoint> : chaque label et un tuple de la forme (label, lang, dir), indiquant respectivement le titre du label, sa langue, et la direction d’écriture (ltr ou rtl).

value

Chaîne de caractères, représente l’attribut value de l’élément.

target_type

Chaîne de caractères.

class_name

Chaîne de caractère, indique la classe css proposée.

play_order

Chaîne de caractère, indique le placement dans l’ordre de lecture de l’élément. Peut être vide.

src

Chaîne de caractère, indique l’url relative à l’emplacement du fichier NCX, et pouvant pointer vers des fragments de fichiers du fichier epub.

Exemple : Text/chap1.xhtml#p36 indique le fichier Text/chap1.xhtml et plus spéficiquement à l’emplacement du fragment p36.

add_label(label, lang='', direction='')

Paramètres:

• label (string) – Texte de l’élément navLabel.

• lang (string) – Langue de l’élément.

• direction (string) – Direction du texte rtl ou ltr.

as_xml_document()

Retourne l’élément XML Dom correspondant à la structure de l’objet.

Type renvoyé:

xml.dom.Element

Les classes NavList et NavTarget

class epub.ncx.NavList

identifier

Chaîne de caractère, identifiant du <navList>.

class_name

Chaîne de caractère, indique la classe css proposée.

labels

Liste des labels du <navPoint> : chaque label et un tuple de la forme (label, lang, dir), indiquant respectivement le titre du label, sa langue, et la direction d’écriture (ltr ou rtl).

infos

Liste des infos de la NavMap : chaque info et un tuple de la forme (info, lang, dir), indiquant respectivement le contenu de l’info, sa langue, et la direction d’écriture (ltr ou rtl).

Une « info » est simplement une description de l’élément.

nav_target

Liste des éléments <navTarget> fils directs. Chaque élément est un objet de la classe NavTarget.

add_label(label, lang='', direction='')

Paramètres:

• label (string) – Texte de l’élément navLabel.

• lang (string) – Langue de l’élément.

• direction (string) – Direction du texte rtl ou ltr.

add_info(label, lang='', direction='')

Paramètres:

• label (string) – Texte de l’élément navInfo.

• lang (string) – Langue de l’élément.

• direction (string) – Direction du texte rtl ou ltr.

add_target(nav_target)

Ajoute un élément NavTarget à la liste des navTarget.

Paramètres:

nav_target (epub.ncx.NavTarget) – l’élément à ajouter

as_xml_document()

Retourne l’élément XML Dom correspondant à la structure de l’objet.

Type renvoyé:

xml.dom.Element

class epub.ncx.NavTarget

identifier

Chaîne de caractère, identifiant du <pageList>.

labels

Liste des labels du <navPoint> : chaque label et un tuple de la forme (label, lang, dir), indiquant respectivement le titre du label, sa langue, et la direction d’écriture (ltr ou rtl).

value

Chaîne de caractères, représente l’attribut value de l’élément.

class_name

Chaîne de caractère, indique la classe css proposée.

play_order

Chaîne de caractère, indique le placement dans l’ordre de lecture de l’élément. Peut être vide.

src

Chaîne de caractère, indique l’url relative à l’emplacement du fichier NCX, et pouvant pointer vers des fragments de fichiers du fichier epub.

Exemple : Text/chap1.xhtml#p36 indique le fichier Text/chap1.xhtml et plus spéficiquement à l’emplacement du fragment p36.

add_label(label, lang='', direction='')

Paramètres:

• label (string) – Texte de l’élément navLabel.

• lang (string) – Langue de l’élément.

• direction (string) – Direction du texte rtl ou ltr.

as_xml_document()

Retourne l’élément XML Dom correspondant à la structure de l’objet.

Type renvoyé:

xml.dom.Element