Notice!
Please also use
this page's discussion to get last minute information or fixes, as well as participate with your own experience, thanks.
Release 1.5.5.0
This new release removes a CPU overrun error as well as implementing the -oneliner- feature, where the album thumbs are presented in one line wider than the page, but scrolling when mouse hoovers the album.
ScrewTurn 3 - Photo Library Plugin
QRCode to this page
I have been missing an easier method to publish series of photos and have therefore created this plugin for displaying photos on the ScrewTurn wiki.
The plugin currently only supports files with JPG format and extension. Non JPG files with .JPG extension will probably prevent normal functionality of the plugin.
This plugin is nicely integrated with ScrewTurn's many features but is still very customizable and altogether the plugin feels like a built in feature.
You can look at the
Plugin Sample page on this site to see how the plugin works with the browser. Also try to browse th page from a smartphone like an Android or an iPhone, that should work too.
The photolibrary is integrated tightly into the page attachment system, so these administrative functions can be used to administrate each pages photos, and behind the scene the plugin finishes preprocessing the photos when the page is saved.
The basic idea is that you simply upload your original digital photos or possibly other sources of high resolution images, just as you usually do, by using the pages attachment manager. Then you add the wiki mark
{photos} to the page, click
save - and magic, you now see evently sized thumbnails displayed on the page, and when clicking a thumbnail you see the larger copy in a lightbox. All the original photos are at the same time completely hidden from the browser. Observe on the sample page, that you can use the attachments button to download only the large images with printed copyright, not the true originals of the photos that was first uploaded to the page. The originals are hidden from the common user. The copyright message is a watermark being set with options, and the download option is also configurable.
The images can be sorted ascending or descending, by any value in the photos Exif data, as well as the image filename and filesize. You can for instance sort by the photos Shutter time if that would be interesting on some instructional photo page.
Since the uploaded photos is resized and the page refer to the resized images, the page loads faster to the users browser. The browser loads all images on the page, and the page is therefore quick to show the large images when thumbnails are clicked.
On pages with huge amounts of images, the images should be smaller to reduce memory usage in the browser client.Installation and usage¶
Download the attachment
BITFIX_PhotoLibrary.zip, rename it to have the extension
.dll, and then install the plugin like any other plugin. For information, this plugin has been downloaded 14 times.
Create a page, and write
{photos} into it, upload a few photos to the pages attachment and save the page. Thats it.
After verifying that the plugin is working, you can play with the
{photos} wiki command to include parameters from the list below.
Example:
{photos|thumbSize=125|largesize=600|watermarktext=Copyright 2010|watermarkcolor=red|watermarkposx=-10|watermarkposy=-10}When the plugin is properly installed, then autoupdate is possible through ScrewTurns provider administration page.
The technique with attachments
Photos are uploaded as normal page attachments. When the page is saved and the photo plugin is activated, all uploaded jpg attachments are processed. Each photo is copied to a thumbnail for page display, and a larger format for lightbox display. Each original photo is also moved out of the normal attachment store. The large photos can at the same time as copying, be watermarked with custom messages.
Depending on the pages plugin configuration, the attachment list on the page is then populated through a custom storage provider also included in this project. The published list of attachments is by default the thumbnails, but the user can define to publish the large images or even the originals.
When the page is edited, the user can delete or rename photos on will. It is also possible to resize thumbnail or large image if that is wanted. Just specify which size you want in the photo plugin's wiki command, and then the images are resized by the plugin when you save the page. In fact any change in any of the plugin's parameters causes the images to be rebuilt on next load. This also accounts for the global plugin configuraton.
The Lightbox Technique
Photos are listed on the page as thumbnails. When a thumbnail is clicked, the lightbox for that image is shown, displaying the large format of the image - not the original.
The album on the page as well as the lightbox to show one photo can be completely customized, since the html is created by using a snippet - more on that below.
With version 1.2 of this plugin, support for jQuery was implemented, so if JQuery is detected, or if ScrewTurn is version 3.0.3.555 or later, JQuery support is simply enabled, and the photoplugin snippets are equipped with advanced JQuery facilities. The JQuery API ensures the best possible cross browser support. The JQuery versions of the snippets are quite advanced.
Snippets
The very first time the plugin is activated on a page, the plugin will install two snippets on the system. One is the photo library html created for the whole photo library. And the other is for the html for each individual image to display in the photo library. The names are by default
PhotoAlbum and
PhotoBox, but these names can be changed in the configuration. Actually each page can use its own snippets so by different snippets you can produce different looking albums. The example given code below is from the earliest released plugin. The code for the snippets is continuously improved with new versions.
Both snippets can be edited after creation to suit your own needs. The plugin does not alter already existing snippets at any time, not even when upgrading. Observe that the replacement parameters in the snippets are replaced by the plugin and not by data on the page. Any snippet parameter can be excluded if for instance you do not want to display exif data, then remove the sections of the snippets that has to do with exif data.
Parameters are specific names surrounded with quationmarks, ex.
?name?. The snippet is in this way compatible with any other normal snippets and they can therefore be tested like any snippet on a separate page with you own specific contents.
The plugin will not create snippets that already exists (by name), so no one will lose their snippets by accident. But you need to rename your valuable snippets in order to use this plugin, if there is a naming conflict.
If any of the album or photo snippet is somehow screwed up by accident, it can simply be deleted, which causes the plugin to recreate the original one.
All known exif data is also extracted and written to the page for every image. The exif data is visible only by activating the lightbox for an image and then hovbering or clicking the title for the image in the lightbox. This behaviour is controlled by the snippet contents.
From version 1.3 the photobox snippet requires the user to click the title in the lightbox to show and hide exif data. This was implemented to support touch mobiles that have no concept of mouseover events.
I wrote the exif extraction tool with inspiration from this
CodeProject article.
The lightbox HTML code in the snippet is my invention and I would like to receive ideas for better lightbox HTML code to be included as standard with the plugin. I have a resonable understanding of IE HTML, but I do need help to make a full blown cross browser lightbox with zooming and forward buttons as well as dynamical loading of images. etc.
From version 1.3 i have implemented JQuery support in the plugin code so that the snippets created are considering JQuery API when created. This makes the work with a dynamic lightbox so much easier. The problem with cross browser javascript has now been eliminated. In my opinion the JQuery framework is a major innovation in web technology. It must not stop being developed.
An early photoAlbum snippet
<div style='text-align:center;width:100%;'>
<div>
?photos?
</div>
</div>
{clear}
An early photobox snippet
<div class='imageleft' style='text-align:center' style='cursor:hand;'>
<div id='?id?exif' style='display:none; position:fixed; top:10px; left:20px; font-size:0.7em; color:#aaa; background-color:#333; z-index:2000'><h2 style='color:#aaa;'>Exif Data</h2>?exif?</div>
<div id='?id?' style='display:none; position:fixed; height:100%; width:100%; top:0px; left:0px; background-color:#111; z-index:1000;' title='Click to return. Klik for at returnere.' onclick="javascript:this.style.display='none';">
<div style='position:absolute; width:?fullwidth?px; height:?fullheight?px; left:50%; top:50%; margin-left:-?halfwidth?px; margin-top:-?halfheight?px; text-align:center; border:1px solid #555;' >
<p style='height:?lineheight?px; font-size:1.5em; color:#aaa;' onmouseover="javascript:getElementById('?id?exif').style.display='block'" onmouseout="javascript:getElementById('?id?exif').style.display='none'">?text?</p>
<img class='image' style='border:none;' src='?image?' alt='?text?' />
</div>
</div>
<img class='image' src='?thumb?' alt='?text?' onclick="javascript:getElementById('?id?').style.display='block';" title='Click for large image. Klik for stort billede.' />
<p class='imagedescription'>?text?</p>
</div>
Plugin Configuration
The plugin's configuration has been predefined to resonable default values, which are used when no custom configuration is made. Individual configuration parameters can then be overridden for the whole site in the global plugin configuration in the provider admin page, which in turn can be overridden in the plugin code on each page where the plugin is being used. Every configuration parameter can be specified on the page.
Each wiki page can have only one photo plugin active. Since all attached photos will be displayed in the first photo plugin on a page, there is no reason to make more photo libraries per page.
This is the list of configurable parameters. These are also given in the help text on the providers administration page. When the plugin is selected, press help on the plugins settings block. The default value for each parameter is also given below.
Photobox snippet parameters
These are replaceable parameters in the photobox snippet. Some come from values from the image being rendered and some come from configuration parameter values of the same name.
?framemargin? is replaced with the framemargin specified in the configuration.
?largewidth? is replaced with the individual image's width in pixels.
?largeheight? is replaced with the individual image's height in pixels.
?framewidth? is replaced with the frames calculated width in pixels. This can be used for non dynamic html.
?framehalfwidth? is replaced with the frames calculated half width in pixels. This can be used for non dynamic html.
?frameheight? is replaced with the frames calculated height in pixels. This can be used for non dynamic html.
?framehalfheight? is replaced with the frames calculated halft height in pixels. This can be used for non dynamic html.
?lineheight? is replaced with the lineheight specified in the configuration.
?id? is replaced with a unique DOM ID specificly created for this image.
?text? is replaced with the text to show for the image. The text comes from the exif description, alternatively from the image filename.
?exif? is replaced with the generated html for the exif data for the image.
?large? is replaced with a URL pointing to the large image.
?thumb? is replaced with a URL pointing to the thumnail image.
?photo? is replaced with a URL pointing to the photo image. This replaceable parameter should not be used if original photo download is not to be allowed.
Photoalbum snippet parameters
These are replaceable parameters in the photoalbum snippet. They are all replaced with configuration parameter values of the same name.
?lineheight? is replaced with the pixelheight of the textline in the lightbox. This is to be used to calculate the correct height of the image frame.
?framemargin? is replaced with the image frame's margin from the configuration.
?largesize? is replaced with the vertical size of the lightbox images.
?photos? is replaced with the complete list of html for all images build from the photobox snippet.
Configuration parameters
The configration parameters are named values that can be given in the administration page where the plugin is configured, or they can be given on the page as name=value, each separated with vertical bars.
The page specified configuration overrides the plugin configuration with in turn overrides the default configuration.
- usingjquery = false
- This instructs the plugin to support JQuery if it is set to true. This parameter is used only while creating the snippets. If the value is changed, the snippets needs to be recreated in order to let the change have the desired effect.
- photosnippet = photobox
- The name of the photosnippet. If this is changed and the new name does not exist, the snippet is created with this name. There may exist as many snippets as you like and you can change between them by using this configuration parameter.
- albumsnippet = photoalbum
- The name of the albumsnippet. If this is changed and the new name does not exist, the snippet is created with this name. There may exist as many snippets as you like and you can change between them by using this configuration parameter.
- framemargin = 5
- The width of the padding for the div surrounding the image in the lightbox, if such a frame is wanted. This can be ignored if no surrounding div is used to frame the ligrbox image.
- lineheight = 30
- This is the height of the images title in the lightbox given in pixels.
- thumbSize = 125
- This is the fixed height of the thumbnails given in pixels. The width is then calculated from the original.
- largeSize = 800
- This is the height of the images in the lightbox, also called lage images. The Originals should be must larger, ex. 10Mpixels.
- downloadable = thumb
- this valus can be 'thumb', 'large' or 'photo'. It defines which version of the photo the end user can download.
- watermarktext =
- This is the text to write on the large images as a watermark. For instance such text '(C) my name 2010'.
- watermarkposx = 10
- This is the X position of the watermark. A positive valus is a measure from left and a negative is a measure from right.
- watermarkposy = 10
- This is the Y position of the watermark. A positive valus is a measure from top and a negative is a measure from bottom.
- watermarkfontfamily = segoe condensed
- This is the font to use for the watermark. The server should know the font given, not the browser client.
- watermarkfontsize = 14
- This is the size in pixels for the watermark text.
- watermarkcolor = silver
- This is the color for the watermark
- watermarktransparency = 50
- This is the transparency for the watermark, where 0 is invisible and 255 is opaque.
- oneliner = false
- The album may be presented as a traditionel album, with all thumbs filling the page, across and down, or the album may be presented as one horisontal line of thumbs, maybe wider than the view, but in a way that the line of thumbs is scrolling left or right on the page, when the mouse hoovers the album thumbs. Set this option to true to get the oneliner album. The album snippet needs to be updated to get this feature, which is new in version 1.5.x
Replacable snippet parameters
The snippets can be equipped with codes in the same form as usual snippets, like
?name? where name is the name of a plugin built-in value.
The photolibrary plugin makes replacements by using some data from a simgle image (with and height and text) or the photo library plugin configuration (margin and textheight and such).
There are different replaceable parameters for the two snippets, photoalbum and photobox.
The list of replacable parameters is growing with new plugin versions and I have not had the time to document the latest list. For now you can look in the snippets code to see which parameters exists, as all of them are used in plugin version 1.3. The parameters should be resonable selfexplanatory. I will make an efford to create a full description soon.
Suggestions, Errors and Updates¶
You should sign up here and write on this pages discussion (link named
deltag) to make errors and suggestions visible to me.
I would like to open the page up for public discussions, but it seems that a spamgroup have broken ScrewTurns quite simple captcha.
Could we have a new one please.
Updates are also becoming available here, downloadable as attachments.
Limitations
There is support for only one album per page.
If the {photos} element is placed more than once on the page, the page will show more equally looking albums and the presentation logic is run multiple times for the page.