====== snap Plugin ======

---- plugin ----
description: Affiche un site sous forme de miniature / Displays a site as a snapshot
author     : Etienne M.
email      : emauvaisfr@yahoo.fr
type       : helper, syntax
lastupdate : 2008-10-17
compatible : 2008-05-05
depends    : 
conflicts  :
similar    :
tags       : snapshot, capture, écran, thumbnail, miniature, site

downloadurl: http://emauvaisfr.free.fr/dokuwiki/snap.tar.gz
bugtracker :
sourcerepo :
donationurl: https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=79ZVTRTJ52DDY&lc=FR&item_name=Plugin%20dokuwiki%20%28Etienne%20M%2e%29&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donate_SM%2egif%3aNonHosted
----

===== Description =====
  * helper : génère la capture (//snapshot//) d'une adresse donnée (//id// d'une page Dokuwiki ou adresse web complète). Voir la [[#reference_du_helper|référence du helper]].
  * syntax : appelle le //helper// pour insérer une capture dans vos pages au moyen d'une [[#syntaxe|syntaxe très simple]].
  * Français et anglais. Il est facile d'ajouter d'autres langues.

===== Pré-requis =====
  * Ce //plugin// ne fonctionne que sous linux (pas le //plugin// lui même, mais le serveur de captures).
    * L'ensemble de la chaine de capture a été testé sur une distribution Debian v4.0.
    * Faites-moi savoir si vous arrivez à le faire fonctionner sous Windows (ou autre) !
    * Utilisez-le à vos risques et périls ! ;-)
  * Vous devrez pouvoir être //root// sur votre serveur Dokuwiki.
    * Ceci n'est peut-être pas le cas si vous utilisez un hébergeur pour publier votre Dokuwiki...

  * Logiciels nécessaires à la réalisation de la capture :
    * ''html2image'' : l'outil qui réalise la capture d'une adresse web.
      * Voir http://www.guangmingsoft.net/htmlsnapshot/html2image.htm (page en anglais).
    * ''Xvfb'' : un serveur //X// virtuel.
      * Voir http://en.wikipedia.org/wiki/Xvfb (page en anglais).
    * ''convert'' : une commande de traitement d'image issue d'''ImageMagick'', qui permet, entre autres choses, de redimensionner et de recadrer des images.
      * Voir http://www.imagemagick.org/script/convert.php (page en anglais).

  * Logiciel nécessaire à la mise en place du serveur de captures :
    * ''netcat'' : un petit utilitaire réseau qui sait faire plein de choses, dont écouter sur un port donné et répondre avec un programme spécifié.
      * Voir http://fr.wikipedia.org/wiki/Netcat

  * Voir [[#installation|ce chapitre]] pour le détail de l'installation.



===== Comment ça marche ? =====
  * Plusieurs modules sont nécessaires pour réaliser la capture :
  - Un serveur de captures (''server.sh'')
    * Il écoute sur un ou plusieurs ports et redirige les appels vers le script ci-dessous (//via// ''netcat'')
  - Un script qui effectue la capture (''snap.sh'')
    * Il récupère les paramètres passés au serveur et déroule les différentes étapes de la capture :
      * La capture proprement dit (//via// ''html2image'')
      * Le recadrage de l'image obtenue (//via// ''convert'')
      * Son redimensionnement (//via// ''convert'')
  - Un //helper// (''helper.php'') qui déclenche la capture en se connectant au serveur de captures et en lui passant les paramètres nécessaires
    * Vous pouvez utiliser ce //helper// dans vos propres //plugins// pour en utiliser les fonctionnalités (voir [[#reference_du_helper|la référence du helper]]).
  - Un //plugin// (''syntax.php'') qui interprète la [[#syntaxe|syntaxe]] pour en extraire les paramètres et appelle le //helper//.

  * Pourquoi est-ce si compliqué ?!
    * Parce que quand on tente d'appeler ''html2image'' directement depuis une page php, on obtient un erreur de pagination (''pagination fault'').

  * Après la capture, l'image est disponible sous forme d'un fichier ''.jpg'' sur le disque dur (dans  ''./data/snap'' par exemple).
    * Le nom de ce fichier garde la trace de l'adresse qui a été capturée et de la taille de la capture (ex : ''start_300x200.jpg'')
    * Un mécanisme de cache est utilisé pour éviter de générer des captures sans arrêt. Si une capture est trouvée sur le disque dur, ayant les mêmes dimensions et pas encore trop vieille (par rapport à ''$conf['cachetime']''), elle n'est pas générée à nouveau (à moins que vous n'ayez spécifié de ne pas utiliser le cache et de forcer la capture (voir [[#syntaxe|ci-après]]))

===== Important =====
  * Gardez à l'esprit que des personnes pourront afficher des captures de pages auxquelles ils n'ont peut-être pas accès normalement (ceci est dû à l'utilisation d'un cache de captures). Cela dit, les captures sont normalement assez petites pour ne pas autoriser une lecture aisée du contenu des pages capturées ;-)
  * Si votre Dokuwiki n'est pas ouvert en lecture à tous (utilisation d'authentification), il vous faut configurer le //helper// pour ajouter les informations de connexion à l'adresse à capturer. Voyez le fichier ''helper.php'' pour faire cela correctement.
    * Il est recommandé d'utiliser [[fr:tips:phashlogin|cette astuce]] pour éviter d'avoir des mots de passe en clair dans les adresses, mais plutôt un //hash// du mot de passe.
  * Actuellement le serveur de captures et le Dokuwiki doivent être sur la même machine.
    * Une prochaine version essayera de faire en sorte que les deux fonctions puissent se trouver sur des machines distinctes.
    * Cependant, vous pouvez d'ores et déjà utiliser un serveur spécifique pour les captures si vous faites un montage de //filesystem// pour mettre les fichiers de captures à disposition de votre Dokuwiki (non testé dans le monde réel).
  * La version de ''html2image'' utilisée par le serveur de captures ne sait pas capturer les objets flash.

===== Installation =====
  * Les exemples donnés sont valides pour une distribution linux Debian v4.0.

==== html2image ====
  * En tant que ''root'', installation de ''html2image'' dans ''/usr/lib/html2image'' par exemple (télécharger le paquet ici : http://www.guangmingsoft.net/htmlsnapshot/html2image.htm)
  * Configurer les options du proxy dans le fichier ''./html2image/greprefs/all.js''. Exemple :<code javascript>
pref("network.proxy.autoconfig_url",        "http://monProxy/monScript");
pref("network.proxy.type",                  2);
</code>
  * Ajout de la ligne ''<chemin vers html2image>'' (à savoir ''/usr/lib/html2image'') dans le fichier (à créer) ''/etc/ld.so.conf.d/html2image.conf''
    * Lancement de ''ldconfig'' pour prise en compte des changements.
    * Si vous ne souhaitez pas modifier ce fichier, il vous faudra définir la variable LD_LIBRARY_PATH à chaque fois que vous voudrez utiliser ''html2image''.

==== Xvfb ====
  * Vérification que ''Xvfb'' est installé (''Xvfb -'' -> doit afficher la liste des options)
    * Si non installé : ''apt-get install xvfb''
  * (Ré)installation des polices xfonts-base (''apt-get remove xfonts-base; apt-get install xfonts-base'')

==== Test de fonctionnement de html2image ====
  * Lancement de ''Xvfb :1 -screen 0 640x480x24 -nolisten tcp -fp /usr/share/fonts/X11/misc&'' (indiquez un autre ''fp'' selon où se trouvent vos polices (''fp=font path'')
  * Définition de la variable DISPLAY : ''export DISPLAY=:1''
  * Lancement d'une capture : ''<nowiki>cd /usr/lib/html2image; ./html2image www.google.com /tmp/essai.jpg</nowiki>''
  * -> Vérifier la présence et le contenu de ''/tmp/essai.jpg''
  * Arrêt de Xvfb (''pkill Xvfb'')

==== netcat ====
  * Vérification que ''nc'' est installé (''nc -h'' -> v1.10)
    * Si non installé : ''apt-get install netcat''

==== convert ====
  * Vérification que ''convert'' est installé (''convert -version'' -> v6.2.4)
    * Si non installé : ''apt-get install imagemagick''
    * Aide de convert : http://www.imagemagick.org/script/convert.php

==== Plugin snap ====
  * Utilisez le //Plugin Manager// pour ajouter le //plugin// ''snap'' (voir l'adresse de téléchargement en haut de cette page)


===== Configuration =====
  * Toujours en tant que ''root'' :
    * Création du dossier ''/var/www/wiki/data/snap'' (par exemple)
    * On lui donne les droits 777 (''chmod 777 /var/www/wiki/data/snap'')

  * Repassage possible sous un profil "non ''root''"
  * Vérifier que le paramétrage du serveur est correct (chemins, ports, etc...) dans le fichier ''/var/www/wiki/lib/plugins/snap/server.sh''
  * Lancement du serveur : ''/var/www/wiki/lib/plugins/snap/server.sh &''
  * Vérification que le paramétrage du plugin est en phase avec le serveur (voir le fichier ''/var/www/wiki/lib/plugins/snap/helper.php'')
  * Vérification que la méthode d'authentification utilisée dans le //helper// correspond à votre configuration.
    * Voyez [[fr:tips:phashlogin|cette astuce]] pour autoriser un //phash// du mot de passe pour la connexion dans les adresses (plutôt qu'un mot de passe en clair).

==== Test ====
  * Ajoutez ceci dans votre bac à sable (//playground//) : <nowiki>{{[[start]]}}</nowiki>
  * → La miniature doit apparaitre

===== Syntaxe =====
  * Comme un lien (''<nowiki>[[adresse_d'un_site]]</nowiki>'') transformé en image (''<nowiki>{{adresse_d'une_image}}</nowiki>'') -> ''<nowiki>{{[[adresse_d'un_site]]}}</nowiki>''
    * L'adresse du site en question peut être une adresse "normale" ([[http://www.dokuwiki.org]]) ou l'//id// d'une page de votre Dokuwiki (''start'', ''fr:plugin:snap'', etc...)

  * Exemples : 
    * Basique : ''<nowiki>{{[[start]]}}</nowiki>'' ou ''<nowiki>{{[[http://www.dokuwiki.org]]}}</nowiki>''\\ {{http://emauvais.multimania.com/dokuwiki/snap_start_200x150.jpg}} ou {{http://emauvais.multimania.com/dokuwiki/snap_web_www.dokuwiki.org_200x150.jpg}}
    * Définir la largeur : ''<nowiki>{{[[start|150]]}}</nowiki>''\\ {{http://emauvais.multimania.com/dokuwiki/snap_start_150x113.jpg}}
    * Définir la hauteur : ''<nowiki>{{[[start|x100]]}}</nowiki>''\\ {{http://emauvais.multimania.com/dokuwiki/snap_start_133x100.jpg}}
    * Définir la largeur et la hauteur : ''<nowiki>{{[[start|300x100]]}}</nowiki>''\\ {{http://emauvais.multimania.com/dokuwiki/snap_start_300x100.jpg}}
    * Ne pas utiliser le cache (forcer la capture) : ''<nowiki>{{[[start|!]]}}</nowiki>''
    * Tout mélangé : ''<nowiki>{{[[start|100!]]}}</nowiki>'' (largeur de 100 px et ne pas utiliser le cache)

===== Notes =====
  * La taille par défaut des captures est de 200x150 pixels.
  * Il existe également des paramètres de largeur max et de hauteur max pour éviter de trop grandes captures (400x300)
  * Lorsque seule la largeur ou la hauteur est spécifiée, le //plugin// utilise un facteur de 4/3 pour calculer la dimension manquante.
  * Voyez le fichier ''helper.php'' pour modifier ces valeurs, et bien d'autres ([[#reference_du_helper|référence du helper]]).

===== Référence du helper =====
  * La fonction getSnap() permet de réaliser la capture d'un site.
    * Paramètres :
      * Adresse du site à capturer ou //id// de page Dokuwiki (obligatoire)
      * Largeur de la capture (facultatif)
      * Hauteur de la capture (facultatif)
        * Si ni la largeur ni la hauteur ne sont fournies, utilise la taille par défaut (200x150).
        * Si seule la largeur ou la hauteur est fourni, utilise le paramètre ''imFactor'' pour calculer la dimension manquante.
      * Utiliser le cache (facultatif. Vrai par défaut.)
    * Retourne un tableau contenant :
      * Le chemin et le nom de la capture.
      * Le titre de la page (si un //id// de page Dokuwiki a été capturé).
      * La cible du lien vers le site capturé.
    * Toutes les propriétés de l'objet //snap// sont également accessibles (voir ci-dessous).

  * Exemple d'utilisation dans un plugin de type ''syntax'' :<code php>
[...]
$snap=plugin_load('helper','snap');
if (!$snap) {
  $renderer->doc .= "<b>SNAP :</b> Snap helper non trouv&eacute;<br />";
  return false;
}

list($imagePath, $titrePage, $target)=$snap->getSnap($param, $larg, $haut, $checkCache);
if (!$snap->succeed || !$imagePath) {
  $renderer->doc .= "<b>SNAP :</b> Probleme lors du snap de $param<br />";
  return false;
}
[...]
</code>
  * <file>
helper_plugin_snap Object
(
    //Propriétés en lecture/écriture --------------------------------------------------------------------------------
    [defaultWiki] => http://monServeurDokuwiki/wiki/doku.php?id=       //Adresse de base utilisée pour capturer des id de pages de votre Dokuwiki.
    [screenx] => 1280                                                  //Largeur du navigateur virtuel dans lequel se fera la capture.
    [screeny] => 1024                                                  //Hauteur du navigateur virtuel dans lequel se fera la capture.
    [imFactor] => 1.33333333333                                        //Proportion largeur/hauteur des images.
    [defLarg] => 200                                                   //Largeur par défaut des captures.
    [defHaut] => 150                                                   //Hauteur par défaut des captures.
    [maxLarg] => 400                                                   //Largeur maximale autorisée pour une capture.
    [maxHaut] => 300                                                   //Hauteur maximale autorisée pour une capture.
    [snapServer] => localhost                                          //Adresse du serveur de captures.
    [snapPorts] => 8888 8889 8890 8891 8892                            //Port(s) d'écoute du serveur de captures.
    [snapTimeout] => 5                                                 //Durée maximale d'une capture (en secondes).
    [tryTimeout] => 3                                                  //Nombre d'essais avant d'arrêter d'essayer de se connecter au serveur de captures.
    [checkCache] => 1                                                  //Utiliser le cache (true/false).
    [width] => 200                                                     //Largeur de la capture.
    [height] => 150                                                    //Hauteur de la capture.
    [outputPath] => /var/www/wiki/data/pages/../snap/                  //Répertoire où sont stockées les captures.

    //Propriétés en lecture seule -----------------------------------------------------------------------------------
    [imagePath] => /var/www/wiki/data/pages/../snap/start_200x150.jpg  //Chemin et nom de la capture courante.
    [titrePage] => Mon titre de page                                   //Titre de la page (si un id de page a été indiqué).
    [snapTime] => 1224068749                                           //Date de la capture.
                                                                       //Peut être différente de la date de lancement de la capture si l'image a été trouvée dans le cache.
    [snapTimeFormatted] => 15/10/2008 13:05                            //Date formatée de la capture (utilise $conf['dformat']).
    [fromCache] =>                                                     //Capture trouvée dans le cache (true/false).
    [succeed] => 1                                                     //Capture réussie (true/false).
    [target] =>                                                        //Cible du lien (utilise $conf['target']['extern'] et $conf['target']['wiki']).
    [selectedPort] => 8890                                             //Port qui a été choisi pour cette capture.
    [snapLog] => Width :1280                                           //Journal de la capture (les mots de passe sont maquillés).
Height :1024
Time Out :5000
URL :http://monServeurDokuwiki/wiki/doku.php?id=start&u=monLogin&phash=******
Output image :/var/www/wiki/data/pages/../snap/start_200x150.jpg
content size:1280X1281
Convert html to image succeeds
Resize 200
Crop 200x150+0+0
    [timeout] =>                                                       //Un timeout a-t-il été détecté pendant la capture (true/false).
    [snapDuration] => 2                                                //Durée de la capture (en secondes).
    [snapTotalDuration] => 2                                           //Durée totale du traitement (en secondes).
                                                                       //Peut être plus long que la capture elle-même si plusieurs tentatives de connexion
                                                                       //ont été nécessaires pour se connecter au serveur de captures.
    [tries] => 1                                                       //Nombre de tentatives de connexion au serveur de captures.
    [url] => http://monServeurDokuwiki/wiki/doku.php?id=start          //Adresse de la page capturée.

    //Propriétés héritées -------------------------------------------------------------------------------------------
    [allowedModesSetup] =>
    [localised] => 
    [lang] => Array
        (
        )
    [configloaded] => 
    [conf] => Array
        (
        )
    [Lexer] => 
    [allowedModes] => Array
        (
        )
)
</file>

===== Versions =====
  * 2008-10-17 : la première !


===== Discussion =====
  * Dites-moi tout...