Summary: A recipe that enables you to use the Highslide JS application in your wiki.
Prerequisites: PmWiki 2.1 or newer (latest stable or beta recommended)
Status: Initial release
Questions answered by this recipe
- How can I easily expand image links inside my wiki pages?
- Is there any alternative to Lightbox?
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.
- Download the current version (the zip file) of Highslide JS from the highslide download page. Also consult the notes section below.
- Unzip the
highslide directory from the zip file to the farm
pub directory of your wiki.
- Download the current version of this recipe (see above) and unzip the contents to your farm root directory (where your
pub folders reside). This will create some files in the beforementioned folders.
- Add the following line to your config to your local configuration script:
Installing in a non-standard location
If you have to chose a non-default installation path for the highslide files (i.e. not
) 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.
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 additional-options:), where
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.
Highslide JS is not included in this package but at the time of writing it can be obtained on: http://highslide.com/
+unobtrusive option. (also see the Configurations section below)
One out of the box configuration that supports this is
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.
+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
The Highslide JS application as well as this script are very customisable. In this section we shall explain the different options of this recipe.
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.
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
$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
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 by default reside in the highslide folder are named
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
preset-easing-all.js: Contains all easing equations written by Robert Penner. When you use this preset you still have to set
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
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.
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';
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.
Highslide['InlineConfig'] in your local configuration file. For example to change the appereance of the Highslide expander you could add the following lines:
'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');
'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.
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']['CustomCss'] respectively. Like all file names these are relative to the highslide directory.
- 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.
- 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.
This space is for User-contributed commentary and notes. Feel free to leave yout comments and opinions. Please sign your comment with
~~ (four tildes), which is replaced by your name and the time of writing when you save the page. Fritz Webering November 27, 2008, at 01:01 PM
User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.