DokuWiki

It's better when it's simple

User Tools

Site Tools

Trace: • snap
plugin:snap

Table of Contents

snap Plugin

Compatible with DokuWiki

2008-05-05

plugin Displays a site as a snapshot (fr: Affiche un site sous forme de miniature)

Last updated on
2008-10-17
Provides
Syntax, Helper

This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.

Tagged with images, links, media

By Etienne M.

Description

  • helper: do the snapshot of a given URL (DokuWiki page ID or full URL). View helper reference.
  • syntax: calls the helper to insert a snapshot into your pages using an easy syntax.
  • French and English. It's easy to add you own language.

Requirements

  • This plugin will only work on Linux (not the plugin itself, but the snapshot server…)
    • The whole snap process was tested on a Debian distribution v.4.0.
    • Tell me if you make it work on a Windows box (or another)!
    • Use it at your own risks! ;-)
  • You must have root access to your DokuWiki server.
    • This may not be possible if your DokuWiki is hosted…
  • Software needed to set up the snap server:
    • netcat: a small network software that does a lot of things, such as listen on a port and answer with a specified program.

How it works?

  • Some modules are needed to do the snapshot:
  1. A snapshot server (server.sh)
    • It listens on one or more ports and sends the connections to the following script (using netcat)
  2. A script that does the snapshot (snap.sh)
    • It reads the parameters sent to the server and passes through the steps of the snapshot:
      • The snapshot itself (using html2image)
      • The crop of the resulting image (using convert)
      • Its resize (using convert)
  3. A helper (helper.php) that launches the snapshot by connecting the snapshot server and sending it the required parameters.
    • You can use this helper into your own plugins to use their functionality (See the helper reference).
  4. A plugin (syntax.php) that reads the syntax to get the parameters and call the helper.
  • Why is it so complicated?!
    • Because when you try to call html2image directly from a PHP page, you get a pagination fault error.
  • After the snapshot, the snap image is available as a .jpg file on the hard drive (into ./data/snap for example).
    • The name of this file keeps track of the URL that was “snapped” and the snap size (ex: start_300x200.jpg)
    • A snap cache mechanism is used to avoid generating a snapshot over and over. If the snap is found on the drive, having the same dimensions and not too old (regarding $conf['cachetime']), it is not generated again (unless you ask to force snapshot without using the cache (see below))

Important

  • Be aware that people can read snap of pages they may not have right to access (this is due to snap caching). However, the snap is normally small enough to prevent a comfortable reading ;-)
  • If your DokuWiki is not open for reading to everyone (use of authentication), you must configure the helper to add login parameters to the URL to snap. See the helper.php file to do this right.
    • It is recommended to use this tip to avoid clear password into the URLs, but an password hash instead.
  • By now, the snap server and the DokuWiki server have to be on the same computer.
    • A next version will try to make it possible to have separate computers.
    • However, you can use a dedicated snap server if you do a filesystem mount to make the snap files available to your DokuWiki (not tested in the real world).
  • The version of html2image used by the snap server doesn't render the flash objects.

Installation

  • Given examples are valid for a Linux Debian v4.0 distribution.

html2image

  • As user root, install html2image into /usr/lib/html2image for example (download it here: http://www.guangmingsoft.net/htmlsnapshot/html2image.htm)
  • Configure the proxy options into ./html2image/greprefs/all.js. Example :
    pref("network.proxy.autoconfig_url",        "http://myProxy/myScript");
pref("network.proxy.type",                  2);
  • Add the line <path to html2image> (for example /usr/lib/html2image) into the file /etc/ld.so.conf.d/html2image.conf (create it)
    • Run ldconfig to activate the changes.
    • If you don't want to modify this file, you will have to define the LD_LIBRARY_PATH variable each time you wish to use html2image.

Xvfb

  • Verify if Xvfb is installed (Xvfb - → doit afficher la liste des options)
    • If not: apt-get install xvfb
  • (Re)install the xfonts-base fonts (apt-get remove xfonts-base; apt-get install xfonts-base)

Test if html2image is working

  • Run Xvfb :1 -screen 0 640x480x24 -nolisten tcp -fp /usr/share/fonts/X11/misc& (provide another fp if your fonts are elsewhere (fp=font path)
  • Define the DISPLAY variable: export DISPLAY=:1
  • Launch a snapshot: cd /usr/lib/html2image; ./html2image www.google.com /tmp/try.jpg
  • → Verify that the file /tmp/try.jpg exists and it contains a pretty snapshot
  • Stop Xvfb (pkill Xvfb)

netcat

  • Verify that nc is installed (nc -h → v1.10)
    • If not: apt-get install netcat

convert

snap plugin

  • Use the Plugin Manager to install the snap plugin (see download at the top of this page).

Configuration

  • Still as user root:
    • Create this directory /var/www/wiki/data/snap (for example)
    • Give it the 777 rights (chmod 777 /var/www/wiki/data/snap)
  • You can go back to a “non root” profile
  • Verify that the server parameters are correct (paths, ports, aso…) into /var/www/wiki/lib/plugins/snap/server.sh
  • Launch the server: /var/www/wiki/lib/plugins/snap/server.sh &
  • Verify that the plugin parameters are in phase with the server (see into /var/www/wiki/lib/plugins/snap/helper.php)
  • Verify that the authentication method used by the helper fits your DokuWiki configuration.
    • See this tip to allow phash password login into the URL (instead of a readable password).

Test

  • Add this into your playground page: {{[[start]]}}
  • → The snapshot must appear.

Syntax

  • Like a link ([[site_url]]) changed into a picture ({{picture_url}}) → {{[[site_url]]}}
    • The site url can be a “normal” one (http://www.dokuwiki.org) or a DokuWiki page ID (start, fr:plugin:snap, aso…)
  • Examples:
    • Basic: {{[[start]]}} or {{[[http://www.dokuwiki.org]]}}
      emauvais.multimania.com_dokuwiki_snap_start_200x150.jpg or emauvais.multimania.com_dokuwiki_snap_web_www.dokuwiki.org_200x150.jpg
    • Define width: {{[[start|150]]}}
      emauvais.multimania.com_dokuwiki_snap_start_150x113.jpg
    • Define height: {{[[start|x100]]}}
      emauvais.multimania.com_dokuwiki_snap_start_133x100.jpg
    • Define width and height: {{[[start|300x100]]}}
      emauvais.multimania.com_dokuwiki_snap_start_300x100.jpg
    • Don't use the snap cache (force snapshot): {{[[start|!]]}}
    • Mixed: {{[[start|100!]]}} (100 px width and don't use snap cache)

Notes

  • The default snap size is 200×150 pixels.
  • There are also maxWidth and maxHeight parameters to avoid too big snaps (400×300).
  • When just width or height is provided, the plugin uses a 4/3 factor to calculate the missing dimension.
  • See helper.php to change those values, and others (helper reference).

Helper reference

  • The getSnap() function is used to do the snapshot of a site.
    • Parameters:
      • URL to snap or DokuWiki page ID (required)
      • Snap width (optional)
      • Snap height (optional)
        • If no width and height are provided, uses the default dimensions (200×150).
        • If only the width or the height is provided, uses the imFactor parameter to calculate the missing dimension.
      • Use the snap cache (optional. Default is true.)
    • Returns an array with:
      • The path and name of the snapshot.
      • The page title (if a DokuWiki page id was submitted).
      • The target frame for the link to the “snapped” site.
    • All the snap object properties are also available (see below).
  • Usage example into a syntax plugin:
    [...]
$snap=plugin_load('helper','snap');
if (!$snap) {
  $renderer->doc .= "<b>SNAP:</b> Snap helper not found<br />";
  return false;
}
 
list($imagePath, $pageTitle, $target)=$snap->getSnap($param, $width, $height, $checkCache);
if (!$snap->succeed || !$imagePath) {
  $renderer->doc .= "<b>SNAP:</b> Problem during the snap of $param<br />";
  return false;
}
[...]
  • helper_plugin_snap Object
(
    //Read/Write properties -----------------------------------------------------------------------------------------
    [defaultWiki] => http://myDokuwikiServer/wiki/doku.php?id=         //Base address used to snap DokuWiki page ID.
    [screenx] => 1280                                                  //Width of the virtual browser into which the snap is done.
    [screeny] => 1024                                                  //Height of the virtual browser into which the snap is done.
    [imFactor] => 1.33333333333                                        //width/height image proportion.
    [defLarg] => 200                                                   //Default width of the snaps.
    [defHaut] => 150                                                   //Default height of the snaps.
    [maxLarg] => 400                                                   //Max width allowed for the snaps.
    [maxHaut] => 300                                                   //Max height allowed for the snaps.
    [snapServer] => localhost                                          //Snap server address.
    [snapPorts] => 8888 8889 8890 8891 8892                            //Snap server port(s).
    [snapTimeout] => 5                                                 //Max duration for a snap (seconds).
    [tryTimeout] => 3                                                  //Max retries to connect snap server.
    [checkCache] => 1                                                  //Use snap cache (true/false).
    [width] => 200                                                     //Snap width.
    [height] => 150                                                    //Snap height.
    [outputPath] => /var/www/wiki/data/pages/../snap/                  //Directory to store the snaps.

    //Read only properties ------------------------------------------------------------------------------------------
    [imagePath] => /var/www/wiki/data/pages/../snap/start_200x150.jpg  //Path and name of the current snap.
    [titrePage] => My page title                                       //Page title (if a DokuWiki page ID was submitted).
    [snapTime] => 1224068749                                           //Snap time.
                                                                       //Can be different of the snap launch time if the snap was found into the cache.
    [snapTimeFormatted] => 15/10/2008 13:05                            //Formatted snap date (uses $conf['dformat']).
    [fromCache] =>                                                     //Snap found into the cache (true/false).
    [succeed] => 1                                                     //Snap successful (true/false).
    [target] =>                                                        //Target of the link (uses $conf['target']['extern'] and $conf['target']['wiki']).
    [selectedPort] => 8890                                             //Port used for this snap.
    [snapLog] => Width :1280                                           //Snap log (the password are hidden).
Height :1024
Time Out :5000
URL :http://myDokuwikiServer/wiki/doku.php?id=start&u=myLogin&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] =>                                                       //Timeout detected during the snap (true/false).
    [snapDuration] => 2                                                //Snap duration (seconds).
    [snapTotalDuration] => 2                                           //Total duration (seconds).
                                                                       //Can be greater than the snap duration itself if more than one retry was done to connect the snap server.
    [tries] => 1                                                       //Tries to connect the snap server.
    [url] => http://myDokuwikiServer/wiki/doku.php?id=start            //"Snapped" page address.

    //Inherited properties ------------------------------------------------------------------------------------------
    [allowedModesSetup] =>
    [localised] => 
    [lang] => Array
        (
        )
    [configloaded] => 
    [conf] => Array
        (
        )
    [Lexer] => 
    [allowedModes] => Array
        (
        )
)

Version history

  • 2008-10-17: first one!

Discussion

  • Tell me…
plugin/snap.txt · Last modified: by Aleksandr
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

Global DokuWiki Links