demos | ||
src/js | ||
Jakefile.js | ||
LICENSE | ||
list.txt | ||
README.md |
jsHtml2Ods
Conversion d'un tableau HTML en fichier ODS disponible en téléchargement.
Le principe de cette bibliothèque est de pouvoir écrire un lien proposant une version ODS (en fait au format .fods) d'un tableau HTML existant. L'exportation est opérationnelle sans aucune modification du tableau mais l'aspect du fichier résultant peut être substantiellement amélioré en ajoutant des attributs spéciaux (data-od-*
) aux éléments du tableau et en proposant des styles suivant la syntaxe CSS.
Cette bibliothèque est testée sous Firefox ou Chromium pour des tableaux de petite taille.
Développement et compilation
Le code Javascript est décomposé en plusieurs fichiers contenus dans src/js/, l'exemple dev.html du répertoire demos/ charge ces fichiers séparément.
Ces fichiers sont compilés dans un fichier unique via l'outil jake et le fichier JakeFile.js via la commande jake build[version]
. Par défaut, ce fichier nommé html2ods.js est placé dans build/ et est utilisé par l'exemple build.html du répertoire demos/.
Le répertoire dist/ contient la dernière compilation avec numéro de version.
En mode développement, les fichiers de src/js/currency, src/js/xmlwriter et src/js/opendocument sont des bibliothèques séparées avec leur propre « espace de nom ». À la compilation, ils sont placés dans Html2Ods
pour n'avoir qu'un seul « espace de nom », c'est pourquoi il ne faut pas supprimer la ligne //compile target
dans le fichier src/js/Html2Ods.js
Attributs spéciaux des éléments HTML
L'exportation peut être configurée à l'aide d'attributs nommés data-od-*
. Ils sont tous facultatifs et sont placés au niveau des différents éléments composants le tableau.
Il est à noter que les attributs colspan
et rowspan
sont reconnus et appliqués ainsi que l'attribut span
pour les éléments <col>
ou <colgroup>
.
Élément <table>
data-od-sheetname
: nom de la feuille dans le fichier résultantdata-od-currency
: code ISO en trois lettres de la monnaie par défaut de la tabledata-od-fixed-rows
: nombre de lignes fixesdata-od-fixed-columns
: nombre de colonnes fixes
Éléments <col>
ou <colgroup>
data-od-style
: style de la colonnedata-od-width
: largeur de la colonne (avec l'unité, par exemple « 6cm »), prend le pas sur la largeur définie dans le style, permet de définir la largeur sans avoir à définir le style
Élément <tr>
data-od-style
: style de la ligne (en cas d'absence de valeur, un élément<tr>
a comme style Header s'il appartient à un élément<thead>
, Standard sinon)
Éléments <td>
ou <th>
data-od-style
: style de la cellule (en cas d'absence de valeur, un élément<th>
a comme style Header et un élément<td>
a comme style Standard)data-od-type
: type des données de la cellule (valeurs possibles :number
,date
oucurrency
)data-od-text
: texte de la cellule (alias :data-text
), voir ci-dessousdata-od-currency
: code ISO en trois lettres de la monnaie de la cellule, n'a d'intérêt que si la cellule est de typecurrency
et peut être défini au niveau de l'élément<table>
Texte d'une cellule
Par défaut, le texte de la cellule dans le fichier résultant est le texte brut de l'élément <td>
ou <th>
. Il est possible d'indiquer un texte alternatif via l'attribut data-od-text
. Ce texte alternatif est souvent nécessaire dans le cas de cellule de type number
, date
ou currency
; en effet, la valeur de la cellule doit être un nombre valide ou une date au format ISO pour être traitée correctement lors de l'exporation.
Au lieu de l'attribut data-od-text
, la valeur peut être définie dans l'attribut data-text
, ce qui permet la comptabilité avec l'extension JQuery TableSorter. Si les deux attributs sont présents, data-od-text
a la préséance.
Lorsque le texte de la cellule est le texte brut de l'élément, il est possible d'ignorer un élément enfant direct de l'élément <td>
ou <th>
en lui donnant l'attribut data-od-hidden
avec n'importe quelle valeur non nulle (1 ou true sont conseillés).
Définition des styles via une syntaxe CSS
Dans le format OpenDocument, la mise en forme des éléments (colonne, ligne, cellule) sont définies par des styles attachés aux éléments. Si de nombreux noms de propriété rappellent ceux des propriétés courantes du CSS, il y a quelques différences de taille :
- Un élément possède un style et un seul
- La seule hiérachie possible est un parent pour un style
- Il n'y a évidemment aucune possibilité de définition en « cascade » via les sélecteurs CSS.
Pour définir des styles dans le fichier résultant (par exemple, mettre un fond rouge à une cellule), jsHtml2Ods propose un mécanisme de conversion d'éléments suivant la syntaxe CSS vers le format XML d'OpenDocument.
Point important : il s'agit d'une forme de détournement du CSS, aucun sélecteur CSS ne va fonctionner de manière habituelle ; l'idée est de pouvoir définir les styles de l'exportation au même endroit que le reste du HTML, c'est à dire dans les fichiers CSS chargés pa la page (ou le CSS d'éléments <style>
). L'idée, c'est qu'il n'y ait pas d'interférence avec le reste du CSS ni rejet à la validation du CSS par le navigateur.
Le principe est qu'un style va être défini par les selecteurs suivants : cell.NomDuStyle
pour une cellule, row.NomDuStyle
pour une ligne, column.NomDuStyle
. Les éléments cell
, row
et column
n'exitant pas en HTML, il n'y a pas d'interférence. NomDuStyle
correspond aux valeurs des attributs data-od-style
des éléments du tableau.
Le nombre de propriétés acceptées est limitée et dépend du type d'éléments. On consultera les exemples situés dans le répertoire demos/ pour une meilleure compréhension.
Propriétés de column
width
: largeur de la colonne (ne pas oublier l'unité)
Propriétés de row
background-color
: couleur de fond de la ligneheight
: hauteur de la ligne (ne pas oublier l'unité)
Propriétés de cell
background-color
: couleur de fond de la celluleborder
: bordure suivant la syntaxe 0.75pt solid #333 (les déclinaisons enborder-top
,border-left
, etc. sont possibles)color
: couleur du textefont-size
: taille de la policefont-style
: style de la police (italic)font-weight
: graisse de la police (bold)overflow-wrap
: passage à la ligne si la valeurs est break-word ou anywherepadding
: remplissage (les déclinaisons enpadding-top
,padding-left
, etc. sont possibles)text-align
: alignement horizontal du textevertical-align
: alignement vertical du texte
Styles prédéfinis
L'exportation propose des styles prédéfinis qui peuvent être directement utilisés dans les attributs data-od-style
d'une cellule sans besoin de les déclarer dans le CSS :
Bold
: Texte en grasBoldItalic
: Texte en gras et italiqueHeader
: Entête de colonne, appliqué par défaut aux éléments<th>
et<th>
Italic
: Texte en italiqueStandard
: Style appliqué par défaut aux éléments<td>
, sans indication particulière
Les lignes ont également comme style par défaut Header
(si la ligne fait partie d'un <thead>
) ou Standard
.
Ces styles peuvent être surchargés par le CSS. Même si le nom est le même, cell.Standard
et row.Standard
sont deux styles différents.
Parenté entre les styles
Le seul lien possible entre les styles est celui de la parenté, le style enfant héritant des propriétés du style parent. Pour indiquer cette parentée, on utilisera l'opérateur CSS +
(qui est donc détourné de sa signification habituelle en CSS) sous la forme cell.NomDuStyleEnfant + cell.NomDuStyleParent
(fonctionne aussi pour row
et column
).
Correspondance avec les classes CSS
Il est fort probable que certaines éléments du tableau disposent déjà de classes CSS pour la mise en forme de la version HTML. Pour éviter d'utiliser l'attribut data-od-styles
pour ces éléments, il est possible d'établir une correspondance entre un style et une classe CSS. Pour cela, on utilisera l'opérateur CSS ~
(qui est donc détourné de sa signification habituelle en CSS) sous la forme cell.NomDuStyle ~ .ClasseHtml
.
L'opérateur ~
doit être placé à la fin (notamment après l'indication d'une éventuelle parenté avec +
) car le style peut correspondre à plusieurs classes différentes : cell.NomDuStyle ~ .Classe1 .Classe2
.