• View
• Edit
• History
• Attach
• Print
• Backlinks

Highslide

Questions answered by this recipe

• How can I easily expand image links inside my wiki pages?
• Is there any alternative to Lightbox?

Description

Highslide JS is a JavaScript image viewer developed by Torstein Hønsi that expands the images inside the current page. This recipe provides a new markup that allows you to enable the Highslide functionality in any wiki page you like.

Examples

Here are some links to sites where Highslide is used in live systems.

• The Highslide website itself has nothing to do with PmWiki but contains several examples of how Highslide JS can look like.
• The TECH-BUFFET website has a photo gallery that is powered by PmWiki, ThumbList² and Highslide.

Installation

1. Download the current version (the zip file) of Highslide JS from the highslide download page. Also consult the notes section below.
2. Unzip the highslide directory from the zip file to the farm pub directory of your wiki.
3. Download the current version of this recipe (see above) and unzip the contents to your farm root directory (where your cookbook and pub folders reside). This will create some files in the beforementioned folders.
4. Add the following line to your config to your local configuration script: include_once("$FarmD/cookbook/highslide.php");

Installing in a non-standard location

If you have to chose a non-default installation path for the highslide files (i.e. not $FarmD/pub/highslide) configure the recipe to use your changed path:

    $Highslide['Directory'] = "/your/custom/path";
    $Highslide['DirectoryUrl'] = "/your/custom/path";

Be careful however, that 'Directory' SHOULD contain an absolute path and 'DirectoryUrl' MUST point to the same folder as 'Directory', but in URL space.

Usage

As you have successfully installed the Highslide recipe you may want to know how to use it to showcase your images.

Firstly on any page where you want to use Highslide add the following markup: (:highslide:) or (:highslide additional-options:), where additional-options stands for some of the customisation options below. This will instruct Highslide to introduce some JavaScript into the page that loads the main Highslide JS and configures it appropriately.

If you want to use Highslide on every page in your wiki by default simply add the following line to your configuration script: $GroupHeaderFmt = '(:highslide:)' . $GroupHeaderFmt;. Then you can customise Highslide by modifying the $Highslide array as outlined under Customisation below.

Now Highslide will by default expand all links whose anchor element as its rel attribute set to "highslide", like in <a href="photo.jpg" rel="highslide" etc...>. This behaviour is desirable if you are generating your image links using some image gallery recipe like for example ThumbList². There you can just write (:thumblist rel=highslide other_options:) to achieve the desired effect.

If you are not using a gallery you might want to use the promiscuous preset which tells Highslide to process all links that link to an image file, like <a href="photo.jpg" rel="highslide" etc...>. In this case "image file" means "any file ending in .jpg, .jpeg, .gif or .png". To do this you can write (:highslide presets=promiscuous:) in the markup or $Highslide['Presets'][] = 'promiscuous'; in your local configuration file. See below for more details.

In that case you can just place any link like [[Attach:somefile.jpg|Some image]] in your markup to create a highslide link.

Also you might find the recipe Mini useful to create thumbnail previews that link to the original files. When used in conjunction with the promiscuous preset this lets you easily create pretty image links in your pages.

Notes

Highslide JS is not included in this package but at the time of writing it can be obtained on: http://highslide.com/

There are multiple ways to tell highslide which links it should process. Currently this recipe only supports the 'unobtrusive' way of doing so. Thus you need to use a configuration of the main highslide JavaScript file that contains the +unobtrusive option. (also see the Configurations section below)

One out of the box configuration that supports this is highslide-full.js (or highslide-full.packed.js respectively), so this may be fine for you.

However if you know what you need and care about file size (and possibly execution speed in your visitors' browsers) you can create your own configuration using the configurator on the highslide website.

To see if a given highslide JavaScript file is suitable for use with this recipe, open the file in a text editor and look at the first few lines. If you see +unobtrusive in the line beginning with Config: the file should be alright. It should look somewhat similar to this:

/******************************************************************************
 Name:    Highslide JS
 Version: 4.0.8 (Oct 30 2008)
 Config:  default -multiple -hideelements +unobtrusive +slideshow +transitions +packed
 Author:  Torstein Hønsi
 Support: http://highslide.com/support
 ...

Customisation

The Highslide JS application as well as this script are very customisable. In this section we shall explain the different options of this recipe.

Configurations

A 'configuration' is a version of the main Highslide JavaScript file that includes (or doesn't include) some features. Configurations for this recipe do by default reside in the highslide folder and are called highslide-config.js where config is the name of the configuration. For example the default configuration that includes all features of Highslide is called highslide-full.js. On how to create your own configuratin consult the Notes above.

Configurations may also be packed (compacted with a JavaScript 'compressor') and are then called highslide-config.packed.js. Those packed files are executable just as their non-packed equivalents but are not human-readable.

To tell this recipe which configuration to use, set the $Highslide['Configuration'] to the desired configuration name. For example to use highslide-full.js write in your config.php: $Highslide['Configuration'] = 'full'; The recipe will then try to find a file called highslide-full.packed.js. If this does not exist it will look for a file called highslide-full.js. If neither of those two exists, it defaults to highslide.js.

You can also override the default setting in the markup using the config parameter. For example (:highslide config=with-gallery ... :) would by default try to load the file highslide-with-gallery.packed.js that is included in the Highslide JS zip package.

The format for configuration file names is defined in $Highslide['Files']['ScriptFile']. Like all file names this is relative to the highslide directory.

Presets

Presets in the context of this recipe are small JavaScript files that contain some code that serves one single clearly defined purpose.

Presets by default reside in the highslide folder are named preset-name.js where name is the name of the preset. Some presets that are included with this recipe are:

• preset-slideshow.js: Creates a slideshow from all the images in the current page. Controls for starting and stopping the slideshow are shown in the image and the transition between images is set to crossfade. This requires a configuration with +slidesow.
• preset-easing-all.js: Contains all easing equations written by Robert Penner. When you use this preset you still have to set hs.easing and hs.easingClose to use the desired type of easing. See the Highslide reference on hs.easing for deatails on how to use this. Also see Inline configuration below.
• preset-easing-quad.js: Like above, but this file is smaller as it only contains the quadratic easing equations and thus is much smaller.
• preset-promiscuous.js: This file configures Highslide JS to recognise all links that link to image files as unobtrusive links. In effect this causes all links to Images in your page to be expanded by Highslide, in addition to the default behaviour of expanding all links that have the attribute rel="highslide".

There are two ways to load presets: either by listing them in the markup as in (:highslide presets=slideshow,ease-quad ... :) or by adding them to your local configuration script: $Highslide['Presets'] = array('slideshow', 'promiscuous', 'easing-quad'); Note that unlike the markup syntax this has to be an array and not a comma seperated list.

To disable a specific preset you can prefix its name with a minus sign. This will keep the preset file from being loaded even if it is listed in one of the other sources of presets. So if for example you want to show show your pictures as a gallery by default with the exception of one page you could write $Highslide['Presets'] = array('slideshow'); in your local config file and then use the markup (:highslide presets=-slideshow ... :) in this specific page. Note that there is no way to load a preset that is listed with a minus in the local configuration file.

The format for configuration file names is defined in $Highslide['Files']['PresetFile']. Like all file names this is relative to the highslide directory.

Translation

Starting with version 4 you can easily translate Highslide JS by changing the values in the hs.lang object (see the reference and this thread in the support forums).

This recipe can automatically load files of the format lang-XY.js where XY is the language code. For example to use the file lang-de.js that is shipped with this recipe you could write (:highslide lang=de ... :) in the markup or add this line to your configuration file: $Highslide['Language'] = 'de';

The file lang-de.js is encoded with ISO-8859-15 while the file lang-de-utf8.js is encoded with the Unicode UTF-8 character set. To use the latter you would write de-utf8 instead of de in the above example.

To create your own translation either look at the Highslide JS support forums ( http://highslide.com/forum/viewtopic.php?t=2119 ), get the appropriate translation and save it as some file called lang-XY.js with XY being your language code. Then just proceed as outlined above.

The format for configuration file names is defined in $Highslide['Files']['LanguageFile']. Like all file names this is relative to the highslide directory.

Inline configuration

You can also easily add custom JavaScript commands for example to set some properties of the hs JavaScript object (see the Highslide Reference). Just add or modify an element of the array Highslide['InlineConfig'] in your local configuration file. For example to change the appereance of the Highslide expander you could add the following lines:

    SDVA($Highslide['InlineConfig'], array(
        'outlineType' => "hs.outlineType = 'drop-shadow';",
        'wrapperClassName' => "hs.wrapperClassName = 'wide-border';",
    ));

Or to add easing to the expander movement (see the Presets section above) write

    $Highslide['Presets'] = array('easing-quad');
    SDVA($Highslide['InlineConfig'], array(
        'easing' => "hs.easing = 'easeOutQuad';",
        'easingClose' => "hs.easingClose = 'easeInQuad';",
    ));

For more information on which options are available please consult the Highslide reference. You are welcome to leave your own configurations that you think may be helpful to other people here.

CSS files

By default this recipe will look for two css files in your highslide directory and include them in the wiki page if present. The highslide.css is contained in the highslide zip package and should not be used for customisations, in case it is overwritten by an update later.

For CSS customisations you should rather use the file called highslide-custom.css which is not contained in any packages. So you can safely put all your custom CSS code there and be reasonably certain that it will not be overwritten automatically.

The names of both of these files can be customised by changing $Highslide['Files']['DefaultCss'] or $Highslide['Files']['CustomCss'] respectively. Like all file names these are relative to the highslide directory.

Release Notes

2008-11-27

• Initial release.

See Also

• ThumbList² is a great recipe that you can use in conjunction with Highslide to form a powerful image gallery.
• Mini might also be useful if you just want to link some images and not a whole gallery.

Contributors

• This recipe was initially written by and is currently maintained by Fritz Webering.
• The Highslide JS application is written and maintained by Torstein Hønsi.

Comments

See discussion at Highslide-Talk?