# 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émonstration de la bibliothèque

Une démonstration est visible ici : [jshtml2ods.exemole.fr/demo.html](https://jshtml2ods.exemole.fr/demo.html), également disponible via le site [Jsfiddle](https://jsfiddle.net/vcalame/4fxrkzgs/23/) pour faire des tests en direct.

## Utilisation de la bibliothèque

La bibliothèque est contenue dans un seul fichier sans dépendance. La dernière version stable se trouve dans le répertoire *dist/*, voir aussi les versions dans la forge : [forge.chapril.org/vcalame/jsHtml2Ods/releases](https://forge.chapril.org/vcalame/jsHtml2Ods/releases). La dernière version est utilisable directement en ligne : [https://jshtml2ods.exemole.fr/latest/html2ods.js](https://jshtml2ods.exemole.fr/latest/html2ods.js).

L'utilisation se fait en trois étapes :

1. Inclure la bibliothèque

```html
<script type="text/javascript" src="https://jshtml2ods.exemole.fr/latest/html2ods.js"></script>
```

2. Avoir dans le texte un lien et une table dotées d'identifiant HTML

```html
<a href="blob:" download="table.fods" id="link" onclick="fodsLink()">Version ODS</a>

...

<table id="table">
...
</table>

```

3. Définir la fonction fodsLink indiquée dans l'attribut onclick="fodsLink()" du lien

```html
<script>

function fodsLink() {
	let link = document.getElementById("link");
	link.href = URL.createObjectURL(
		Html2Ods.blob("table")
	);
	setTimeout(function () {
		URL.revokeObjectURL(link.href);
	}, 4E4); // 40s
	return true;
}
</script>
```

Cette fonction construit un objet de type Blob associé au lien de téléchargement.


## Options disponibles

La construction du blob de téléchargement se fait avec l'appel de la fonction Html2Ods.blob qui prend deux arguments : la table (instance de HtmlTableElement ou chaine de caractères indiquant l'identifiant de l'élément) et un objet d'options facultatif. Ce dernier peut avoir les propriétés suivantes :

- *currency* : monnaie par défaut des valeurs monétaires (peut être modifiée au niveau de la table ou de la cellule)
- *datePattern* : formatage par défaut des dates (peut être modifié au niveau de la table ou de la cellule) ; `YYYY-MM-DD` par défaut
- *textAlias* : nom de l'attribut à utiliser comme alias de `data-od-text` ; le nom doit être exprimée sous la forme javascript (si l'attribut à utiliser est `data-mon-texte-personnalise`, il faut indiquer *monTextePersonnalise*) ; `text` par défaut



## 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ésultant
- `data-od-currency` : monnaie par défaut de la table (voir ci-dessous)
- `data-od-date-pattern` : formatage des dates de la table (voir ci-dessous)
- `data-od-fixed-rows` : nombre de lignes fixes 
- `data-od-fixed-columns` : nombre de colonnes fixes

_Note_ : `data-od-sheetname` est obligatoire pour utiliser `data-od-fixed-rows` ou `data-od-fixed-columns`

### Éléments `<col>` ou `<colgroup>`

- `data-od-style` : style de la colonne
- `data-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)
- `data-od-hidden` : avec la valeur 1 ou true, la ligne est cachée dans le fichier résultant, avec la valeur -1 ou false, la ligne est affichée dans le fichier résultant même si la ligne est cachée dans la version HTML 

### É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` ou `currency`)
- `data-od-text` : texte de la cellule (alias : `data-text`), voir ci-dessous
- `data-od-currency` : monnaie de la cellule, n'a d'intérêt que si la cellule est de type `currency` (voir ci-dessous)
- `data-od-date-pattern` : formatage de la date, n'a d'intérêt que si si la cellule est de type `date` (voir ci-dessous)

#### 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 la valeur 1 ou true.

#### Formatage des dates

Par défaut, les dates sont affichées au format ISO (année-mois-jour). Une autre format d'affichage peut être indiqué à trois endroits différents (classés par ordre de préséance) : l'attribut `data-od-date-pattern` de la celulle, l'attribut `data-od-date-pattern` de la table et la propriété *datePattern* de l'objet *options* passé en argument.

Ce format doit est une chaine où les lettres suivantes sont remplacées par les valeurs de la date :

- D : numéro du jour à un ou deux chiffres
- DD : numéro du jour à deux chiffres
- M : numéro du mois à un ou deux chiffres
- MM : numéro du mois à deux chiffres
- Y : année à deux chiffres
- YY : année à quatre chiffres

Par exemple, le code ISO correspond au format `YYYY-MM-DD` ; `DD/MM/YY` affiche le trois novembre 2021 sous la forme 03/11/21).

**Point important** : ce formatage concerne l'affichage dans le fichier résultant mais pas la date telle qu'elle est représentée dans le tableau HTML ; dans ce dernier cas, la date doit impérativement être fournie au format ISO.

#### Code des monnaies

Les valeurs monétaires doivent avoir l'indication de la monnaie correspondante. Cette monnaie peut être indiquée à trois endroits différents (classés par ordre de préséance) : l'attribut `data-od-currency` de la cellule, l'attribut `data-od-currency` de la table, la propriété *datePattern* de l'objet *options* passé en argument.

La monnaie est indiquée par son code ISO en trois lettres : *EUR*, *USD*, etc.

## 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 ligne
- `height` : hauteur de la ligne (ne pas oublier l'unité)


### Propriétés de `cell`

- `background-color` : couleur de fond de la cellule
- `border` : bordure suivant la syntaxe *0.75pt solid #333* (les déclinaisons en `border-top`, `border-left`, etc. sont possibles)
- `color` : couleur du texte
- `font-size` : taille de la police
- `font-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 *anywhere*
- `padding` : remplissage (les déclinaisons en `padding-top`, `padding-left`, etc. sont possibles)
- `text-align` : alignement horizontal du texte
- `vertical-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 gras
- `BoldItalic` : Texte en gras et italique
- `Header` : Entête de colonne, appliqué par défaut aux éléments `<th>` et `<th>`
- `Italic` : Texte en italique
- `Standard` : 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`.


## À propos du code et de sa 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*