Commit 754f53a3 authored by Cerdic's avatar Cerdic

Documentation

parent 07f6cc1a
......@@ -11,7 +11,7 @@ $GLOBALS[$GLOBALS['idx_lang']] = array(
'offline_titre' => 'Offline',
'offline_info_telecharger_lecture_offline_active' => "Télécharger pour lire hors-ligne",
'offline_info_telecharger_lecture_offline_unactive' => "Téléchargement impossible",
'offline_info_telecharger_lecture_offline_unactive' => "Téléchargement non disponible",
// C
'cfg_exemple' => 'Exemple',
......
......@@ -57,7 +57,7 @@ function offline_inserer_head($page_html, $insert) {
}
/**
* #BOUTON_TELECHARGER_OFFLINE{rubrique,#ID_RUBRIQUE,'Télécharger cette documentation','Téléchargerment non disponible');
* #BOUTON_TELECHARGER_OFFLINE{rubrique,#ID_RUBRIQUE,'Télécharger cette documentation','Téléchargement non disponible'}
* @param $p
*/
function balise_BOUTON_TELECHARGER_OFFLINE_dist($p) {
......
......@@ -97,6 +97,50 @@ Si votre site n'est pas fréquenté ou que vous voulez en disposer immédiatemen
spip offline:build:services
```
#### Téléchargement d'une partie du site "pour lire plus tard"
Le plugin propose une balise `#BOUTON_TELECHARGER_OFFLINE` qui peut s'utiliser ainsi :
```
<BOUCLE_titre(RUBRQUES){id_rubrique}>
<h1>#TITRE</h1>
[(#BOUTON_TELECHARGER_OFFLINE{rubrique,#ID_RUBRIQUE})]
</BOUCLE_titre>
```
Vous pouvez également passer 2 arguments optionnels supplémentaires correspondant au libellé du bouton de téléchargement actif et inactif
```
#BOUTON_TELECHARGER_OFFLINE{rubrique,#ID_RUBRIQUE,'Télécharger cette documentation','Téléchargement non disponible'}
```
Le bouton télécharger repose sur 2 squelettes :
* le squelette `offline/urls-{objet}.html` (`offline/urls-rubrique.html` pour une rubrique) qui liste les URLs des pages à télécharger pour l'objet passé en `#ENV` du squelette. La liste est au format texte, une URL par ligne.
* le squelette `offline/bouton-telecharger.html` qui gère l'affichage du bouton
La balise `#BOUTON_TELECHARGER_OFFLINE` se charge de vérifier l'existence d'un squelette `offline/urls-{objet}.html`.
Si le squelette n'existe pas elle n'affichera rien.
La balise se charge également de vérifier qu'une liste d'URL a été construite pour cet objet, à partir de la liste des pages fournies par le squelette `offline/urls-{objet}.html`.
Si la liste des URLs n'a pas été construite, elle lance une tache cron pour construire cette liste et affiche le bouton dans un état `unactive`.
Pour des raisons de performance, le bouton n'est pas dynamique : il ne vérifie pas l'état de la liste à chaque affichage mais seulement à la mise à jour du cache.
Il faudra donc attendre la prochaine mise à jour du cache ou forcer avec un `?var_mode=calcul` pour qu'il sorte de cet état.
Quand la liste des URLs pour l'objet demandé est bien disponible, le bouton est affiché dans le HTML avec un état `unactive activable`.
C'est une fonction javascript qui va se charger, côté client, de vérifier que le service worker est bien chargé, et de passer alors le bouton dans l'état `active`.
Au même moment il vérifie aussi si la liste des URLs a déja été chargée pour cet objet, et dans ce cas la classe `offline-ok` est ajoutée.
Attention, cela ne prend pas en compte un éventuel changement de la liste des URLs suite à la mise à jour du contenu !
Enfin, quand l'utilisateur clique sur le bouton pour (re)télécharger le contenu, le bouton reçoit la classe `offline-download`
La construction de la liste des URLs de téléchargement d'un objet peut se faire automatiquement en cron, mais aussi manuellement, via spip-cli :
```
spip offline:build:urls --objet=rubrique --id_objet=1
```
Le build construit un fichier texte `config/offline/objets/urls-rubrique-1.txt` qui sera alors chargé au format json par le navigateur via l'URL `offline.api.urlsdownload.json?objet=rubrique&id_objet=1`
#### Utilisation sur un site multidomaines
......@@ -104,6 +148,15 @@ spip offline:build:services
La prise en compte de multidomaines n'est pas encore vraiment opérationnelle.
Les URLs à télécharger doivent être relatives au domaine consulté, et les éventuelles URLs croisées seront bloquées en l'absence de directives CORS.
### Mise à jour des listes d'URLs
[TODO] Pour assurer une mise à jour de toutes les listes d'URLs existantes, il est possible de lancer depuis un cron système la commande
```
spip offline:rebuild
```
qui va reconstruire le service worker en mettant à jour la liste d'URLs à charger à l'installation, mais également repasser sur chaque fichier `config/offline/objets/urls-{objet}-{id_objet}.txt` existant et recalculer la liste des URLs à charger pour cet objet.
## Considérations de performance
Pour optimiser le temps de chargement et revalidation des ressources (CSS, JS), il est préconisé de les minifier et concaténer en un seul fichier au sein de chaque page.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment