Configuration - Imageflow

Wednesday, 25 June 2008 07:11

Imageflow Module Configuration

Imageflow has several module configuration parameters that control where Imageflow gets the images to be included in the gallery, various options defining how the thumbnails are generated as well as several behavioral attributes of the gallery. They are listed below in the order that they appear on the Module edit screen. Click on the item of interest to get detailed information regarding that parameter.

Module Class Suffix

This is a standard Joomla parameter that allows you to define a unique class for the module. Imageflow defines an 'imageflow' class on the outer HTML DIV that it generates. You can append any suffix that you desire to this by specifying a value here. Normally, this parameter should be left blank. The module id (described below) is usually enough to allow CSS styling of the gallery but there could be special circumstances where you might want to specify a suffix.

Module id

Specify a unique HTML id. This id is used for several purposes:

it is the name assigned to the unique instance of Imageflow on the page. If you have multiple copies of Imageflow on a single page, this is the value that allows the instances to work independant of each other.
it is specified as the id attribute on an HTML DIV that surrounds all of the loaded images. This id can be used for CSS styling if desired.
for Highslide, it is specified as the 'slideshowGroup' parameter. If you intend to use the loaded images with a highslide gallery, this value should also be specified as the 'Slideshow group' in the gallery settings.
for shadowbox, lightbox, greybox, etc. this value is used in a similar fashion to group the images for slideshow viewing.

Any valid HTML id can be used as long as it is unique to all other ids on the page. Defaults to 'imf'. Note: Due to the fact that this value is also used to create a javascript variable on the page, it must begin with either a letter or underscore.

Load images from

This parameter tells Imageflow how it should acquire the images that it is to place in the gallery.

'Image list file' indicates that images that you have specified in the text configuration file defined by the 'Image list file' parameter are to be loaded.
'Directory' tells Imageflow to load the image files contained in the directory that you have specified in the 'Directory path' parameter. All JPG, PNG and GIF images will be loaded.
'Both' results in images being loaded from both places.

Directory path

Specify the directory that images are to be loaded from when using the 'Directory' or 'Both' options for the 'Load images from' parameter. TIP

Directory depth

When displaying images from a directory, Imageflow can include images from any subdirectories that may be inside the main directory. This parameter controls how deep into the directory path Imageflow should go when including images. The default value of zero indicates that no subdirectory images will be loaded.

Image list file

Defines the location of a configuration text file that you have created to tell Imageflow what images to include in the gallery. A functional sample configuration file is supplied with the module at modules/mod_imageflow/samplelist.txt. A description of the contents of the image list configuration file is provided later in this document. TIP

NOTE: This must be a plain text file. For MAC users using text edit, be sure to select 'Make Plain Text' in the Format menu before saving the file. Another MAC alternative is a free text editor called 'TextWrangler' at http://www.versiontracker.com

NOTE*: If your captions/titles contain accented characters you must save the image list file using UTF-8 encoding. For windows notepad, this can be selected in the Encoding area of the save/save as dialog box.

Cascading stylesheet file

If you create your own cascading stylesheet, you can specify a url that points to that file. It will be included in the page at load time instead of the CSS file supplied with the module. This parameter defaults to the CSS file provided with Imageflow.

Imageflow detects when it has been loaded with Internet Explorer 6 and will attempt to load an additional cascading stylesheet that contains special css rules for IE6. That CSS file must have the same name as the Cascading stylesheet file specification with '-ie6' appended to it. In the example above, Imageflow will look for a CSS file named 'modules/mod_imageflow/css/imageflow-ie6.css'.

Slider

The slider that is displayed below the image gallery can optionally be hidden. Default is 'Show'.

Captions

Provides the option of hiding the caption that is displayed below the image gallery. The caption consists of either the title attribute of the anchor or thumbnail image or if no title was specified, the filename of the image. Default is 'Show'.

Previous/next buttons

Previous and next buttons can optionally be displayed on the slider line to allow the viewer to single step forward or backward through the gallery thumbnails by clicking on the appropriate button. Default is 'Hide'

Strip extension from filename

This parameter controls whether or not the file extension will be removed from the filename when it is displayed as a caption. The default is 'Yes'.

Image stack size

Specifies the number of images (1-9) that will be displayed on either side of the center image. Default is 4.

Meta data template

Provides the path/filename of a template that defines to Imageflow the meta data information that is to be extracted from jpg images that are loaded via the directory load option. The template also defines the format of the caption that is to be displayed. This parameter defaults to a predefined template that is supplied with Imageflow. You can create your own template or modify the one supplied with the module. TIP

Output template

This parameter defines the default output template file that is to be used. An output template is a text file that contains a skeleton HTML format. The skeleton HTML has variable information that is filled in by Imageflow at page load time. For each image being loaded in the gallery, Imageflow replaces the variables with information about the image such as image file name, captions, etc. and then outputs the finished HTML onto the page. This enables Imageflow to be adapted to any number of image display scripts, such as Shadowbox, Highslide JS, Lightbox, etc. Several output templates are provided with Imageflow in the modules/mod_imageflow/templates directory. If this parameter is omitted or points to a nonexistent file, an internal representation of the Highslide JS template is used.. TIP

Image limit

When loading images from a directory, you can specify a maximum number of images to load. If omitted, all qualifying images in the directory will be loaded.

Glide to image

Defines the image that should be focused in the center of the gallery upon page load. This can be a specific image number, starting with 1 for the first thumbnail, or a percentage. For example, 50% in a 25 image gallery will cause imageflow to glide to image 13. The default is 1. Invalid or out of range values are ignored.

Auto-step seconds

Specify a numeric value greater than zero to activate the auto-step function. When activated, Imageflow automatically rotates the thumbnails to the center at the specifed interval of seconds. A play/pause button is displayed on the slider line to allow starting/stopping the auto-step function. Clicking on a thumbnail also stops auto-stepping.

Active link on focused

This parameter dictates the behavior of the gallery when you mouseover or click on the gallery thumbnails. One of the following settings may be chosen:

No. Clicking on any thumbnail will trigger the click event (popup image, link activation, etc.) for that thumbnail.
Advance on click. Clicking on a non-focused (not the center) thumbnail will cause that thumbnail to be brought into focus (brought to the center). Clicking on the focused (center) thumbnail will trigger the click event (popup image, link activation, etc.) for that thumbnail.
Advance on mouseover. Hovering the mouse pointer over on a non-focused (not the center) thumbnail will cause that thumbnail to be moved toward the center. Clicking on the focused (center) thumbnail will trigger the (popup image, link activation, etc.) for that thumbnail.

The default is No.

Highslide controlbar

Yes will cause a navagation control bar to appear on Highslide popup images when you mouseover the popup. Clicking on the next/previous arrows in the controlbar will advance to the next/previous popup image in the gallery as well as advancing the gallery thumbnails. Note: This parameter should only be set to yes if you are using Highslide to generate the popup images. Setting this parameter to yes without highslide present will cause errors to be generated on your page. The default is No.

Size percent

Defines the size of the generated thumbnail image as a percentage of the original source image size. This value controls the size of the thumbnail image that is created and stored on the server. It has nothing to do with the size of the thumbnail that is displayed in the gallery. If your original source image is rather large a smaller value can yield a satisfactory thumbnail whereas for small images a small value will result in a somewhat pixelated thumbnail being displayed. The default is 35.

Sharpen

Specify the amount of sharpening effect (0-9) to apply to the focused (center) thumbnail image to make it stand out from the non-focused (non-centered) thumbnails. The default is 0, no sharpening. Generated thumbnails can exhibit a certain amount of detail loss. Sharpening, in most cases, can restore some of the detail to the thumbnail image. PHP 5 or greater is required to produce this effect.

Blur

Specify the amount of blur effect (0-9) to apply to the non-focused (non-centered) thumbnail images to make the focused (centered) thumbnail standout. The default is 0, no blurring. PHP 5 or greater is required to produce this effect.

Darken

Specify the amount of darkening effect (0-9) to apply to the non-focused (non-centered) thumbnail images to make the focused (centered) thumbnail standout. The default is 0, no darkening. PHP 5 or greater is required to produce this effect.

Grayscale

Yes will display all of the non-focused (non-centered) thumbnail images in grayscale to make the focused (centered) thumbnail standout. The default is No. PHP 5 or greater is required to produce this effect.

Border width(s)

This parameter can be used to generate a border on the thumbnail images. Numeric pixel width(s) may be specified, with or without commas, to define a border on each edge (top, right, bottom or left) of the thumbnail. Like the CSS border-width property, from one to four values may be specified.

Examples:

1 2 0 1
- top border is 1 pixel
- right border is 2 pixels
- bottom border is 0 pixels
- left border is 1 pixel
2, 1, 1
- top border is 2 pixels
- right and left borders are 1 pixel
- bottom border is 1 pixel
2, 1
- top and bottom borders are 2 pixels
- right and left borders are 1 pixel
2
- all four borders are 2 pixels

Default is no borders.

Border color(s)

This parameter can be used to specify the color of the border(s) on the thumbnail images. Hexidecimal color values(s) may be specified, with or without commas, to define the color of each edge (top, right, bottom or left) of the thumbnail. The hexidecimal value is in the form #RRGGBB where RR is the amount of red, GG is the amount of green with BB representing the amount of blue. This color chart at W3 Schools is a great reference. Like the CSS border-color property, from one to four values may be specified.

Examples:

#FF0000, #00FF00, #0000FF, #808080
- top border is red
- right border is green
- bottom border is blue
- left border is gray
#FF0000 #00FF00 #0000FF
- top border is red
- right and left borders are green
- bottom border is blue
#FF0000, #00FF00
- top and bottom borders are red
- right and left borders are green
#FF0000
- all four borders are red

Note: You can use a shorthand hex value of 3 digits if you wish. For example, #323 is the same as #332233. Default is #000000 (black).

Transparent

Defines whether to generate transparent or non-transparent thumbnail reflections.

Transparent reflections are created as image type PNG files. They are the most flexible in that you can use them on any page and they will blend into the background of the gallery regardless of it's color. The drawback is that not all browsers are equal in that some older browsers do not display PNG files correctly. This results in a minor compatiblity problem.
Non-transparent reflections are the most compatible because they can be displayed by any browser. The drawback here is that they must be generated with the background color of the gallery that they will be displayed on in mind. Gradient and image backgrounds can also be a problem because they cannot be matched very well with this type of reflection.

For both methods, the generated thumbnail is written to the same directory as the source image. The thumbnail file name begins with 'refl_' followed by the name of the original image along with an alphanumeric key that is generated from the module options used to create the thumbnail. Subsequent thumbnail refection requests for a given source image will automatically be directed toward this file rather than generating a new thumbnail reflection. Once the thumbnails are generated, the imageflow display is considerably faster and results in less load on the web server

Default is non-transparent reflections.

Fade to color

This parameter is only meaningful when using non-transparent reflections. It defines the color to 'fade the reflection into'. A single hexidecimal color value may be specified. The hexidecimal value is in the form #RRGGBB where RR is the amount of red, GG is the amount of green with BB representing the amount of blue. This color chart at W3 Schools is a great reference. Specify a color value that matches the background of your Imageflow gallery.

Default is #000000 (black).

Alpha fade start

The starting intensity of the reflection is controlled by this parameter. Values in the range of 0 (completely faded) to 127 (no fade) are allowed. You can also specify the values as a percentage where 0% is completly faded to 100% (no fade).

You can effectively eliminate the reflection portion of the thumbnail image by specifying an alpha fade start and alpha fade end of 0.

Default is 80 (50%).

Alpha fade end

The ending intensity of the reflection is controlled by this parameter. Values in the range of 0 (completely faded) to 127 (no fade) are allowed. You can also specify the values as a percentage where 0% is completely faded to 100% (no fade).

In most cases it is desirable for the reflection to fade all the way into the background.

Default is 0.

Tint color

This parameter is only meaningful when using transparent reflections. It can be used to add a tint of color to the reflection. For example, you can increase the blue channel for a more 'watery' effect. A single hexidecimal color value may be specified. The hexidecimal value is in the form #RRGGBB where RR is the amount of red, GG is the amount of green with BB representing the amount of blue. This color chart at W3 Schools is a great reference.

Default is no tint.

Memory limit

When using very large images you may encounter a case where just a blank page is displayed instead of the gallery that you expected. This is usually caused by the PHP memory_limit parameter being too small to support thumbnail generation of the images that you are using..

Imageflow estimates the amount of memory required for thumbnail generation and if it determines that the PHP memory_limit being used is insufficient, tries to override that setting for the duration of the thumbnail creation process. If successful, you will never need to use this parameter. However, it is not always possible to perform the override because the PHP functionality needed may not available depending upon how your version of PHP was created.

This advanced parameter can be used to try to temporarily override the PHP memory_limit parameter. The value you specify here is the same as what you would use for the memory_limit parameter in the php.ini file. For example, 32M would indicate a memory limit of 32 megabytes.

Max execution time

If you receive an error message indicating that the maximum execution time has elapsed when displaying a page with Imageflow, you can temporarily increase the amount of time that Imageflow has to generate thumbnail images with this parameter. Specify a number of seconds. For example, the PHP default value is 30. Increase it to 45 or 60.

End FAQ

The Image List File

In its simplest form, the image list file is a text file containing a list of img= specifications, one for every image to be loaded in the gallery. Consider the Imageflow gallery and the subsequent image list file shown below.

Loading images

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25 // // Simple Imageflow images list // // // image definitions // img = "modules/mod_imageflow/images/thumbstrip20.jpg" & imgalt="My title 1" & caption="My caption for image 1" & hreftitle="My href title 1" & imgtitle="My img title 1" img = "modules/mod_imageflow/images/thumbstrip23.jpg" & imgalt="My title 2" & caption="My caption for image 2" & hreftitle="My href title 2" & imgtitle="My img title 2" img = "modules/mod_imageflow/images/thumbstrip24.jpg" & imgalt="My title 3" & caption="My caption for image 3" & hreftitle="My href title 3" & imgtitle="My img title 3"

If you hover over and/or click on the thumbnail images you can see that the titles and captions specified in the image list file were included in the resulting gallery.

Comments

Any line that begins with 2 slashes is considered a comment by Imageloader and is completely ignored. Comment lines allow you to document areas of the image list file and to temporarily remove image definitions without actually deleting them.

Image definitions

An image definition consists of a number of keyword/value pairs and takes the general form of:

keyword1 = "value1" keyword2 = "value2"....

The image definition can be specified on a single line or, for readability, can be broken into several lines by specifying an ampersand at the end of each line that is to be continued onto the next.
Keywords are case insensitive, i.e. IMG is the same as img.
The only required keyword is the 'img' specification. It defines the image that Imageflow will load on the page and must be present or the entire specification will be ignored.

Additional keywords, beyond the img keyword, are defined by the output template that is being used by Imageflow to generate the required HTML output for the image. To illustrate this, the default output template used for the demo, highslidetemplate.txt, is shown below:

1
2
3
4
5
6
7

8
9
10

11
12
13

14 // // output template suitable for Highslide JS // The following parameters will be inserted into the resulting output: // {img} = URL of the image // {hreftitle} = title specification from imagelistfile // {rflct} = URL of thumbnail/reflection image // {imgalt} = image alt specification from imagelistfile or filename if loading from a directory // {imgtitle} = image title specification from imagelistfile. // {caption} = caption info derived from image metadata. // {_group} = used to restrict next/prev navigation to images in a particular gallery instance. Module id is automatically used if not specified otherwise. // {_id} = unique id. // <a class="highslide" href="{img}" onclick="return hs.expand(this,{slideshowGroup: '{_group}', captionText: '{caption}'})" title= "{hreftitle}"> <img id="{_id}" src="{rflct}" alt="{imgalt}" title="{imgtitle}"/></a>

Notice that keywords specified in the image definition (img=, hreftitle=, etc.) match variable values in the output template ({img}, {hreftitle}, etc). Imageflow simply substitutes the value that you specify for each keyword into the output template. After all variables are substituted the final HTML markup is output to the page. For example, the resulting HTML for the first image definition above is as follows:

1 <a class="highslide" href="/modules/mod_imageflow/images/thumbstrip20.jpg" onclick="return hs.expand(this,{slideshowGroup: 'imfex1', captionText: 'My caption for image 1'})" title="My href title 1"><img onload="return imfex1.imgloaded(this);" width="210" height="210" id="imfex1_imageflow_image_0 " src="/modules/mod_imageflow/images/refl_thumbstrip20_jpg_9804a52846192125b21 f68c1e86decde.jpg" alt="My title 1" title="My img title 1"/></a>

The output template contains several variables that are automatically filled in by Imageflow depending upon the Imageflow module parameters that you specify. These are internally generated variables that are prepended with an underscore so as to not clash with any variables that you may define. They are:

{_group} is the module id that you assigned to the module.
{_id} is a unique id assigned to the thumbnail image by Imageloader.
{_filename} is the name of the image file.

These variables can be ignored for the purposes of creating an image list file, however, if you are creating your own output template you may need to include these in your template wherever feasible.

More Image List File

The three images shown below were loaded using the samplelist.txt image list file that is installed with Imageflow, also shown.

Loading images

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

17
18

19

20

21

22

23
24
25

26

27
28
29
30
31
32
33
34
35
36
37
38

39
40
41
42
43
44
45

46
47
48
49
50 // // Imageflow images list // // // file path variable definitions // $baseurl0 = "modules/mod_imageflow/images/" // // caption and comment variable definitions // @metaauthor = "$author, IPTC.2#080, IFD0.Artist, IFD0.Author" @metacomments = "$comments, IPTC.2#120, IFD0.Comments" @metatitle = "$title, IPTC.2#005, IFD0.Title, $_filename" @metadate = "$datetime, IFD0.DateTime, EXIF.DateTimeOriginal, IPTC.2#055" $title = '<div class="imageflow_title">{metatitle}</div>' $author = '<div class="imageflow_caption_author">Author: {metaauthor}</div>' $comments = '<div class="imageflow_comment">: {metacomments}</div> ' $captioncomments = '<div class="imageflow_caption_comments"> {title}{comments}</div>' $datetime = '<div class="imageflow_caption_datetime">Date: {metadate}</div>' $caption = '<div class="imageflow_caption"> {captioncomments}{author}{datetime}</div>' $divtitle = '<div class="imageflow_title">{mytitle}</div>' $divcomments = '<div class="imageflow_comment">: {mycomments}</div>' $mycaptioncomments = '<div class="imageflow_caption_comments"> {divtitle}{divcomments}</div>' $mycaption = '<div class="imageflow_caption"> {mycaptioncomments}{author}{datetime}</div>' // // image definitions // // // using my title and comments // combined with meta author and date // $mytitle = "My title 1" $mycomments = "My comments for image 1" img = "{baseurl0}thumbstrip20.jpg" imgalt="{mytitle}" caption="{mycaption}" hreftitle="{mytitle}" imgtitle="{mytitle}" // // example using my title and comments only // $mytitle = "My title 2" $mycomments = "My comments for image 2" img = "{baseurl0}thumbstrip23.jpg" imgalt="{mytitle}" caption=" {mycaptioncomments}" hreftitle="{mytitle}" imgtitle="{mytitle}" // // example using metadata exclusively // img = "{baseurl0}thumbstrip24.jpg" imgalt="{metatitle}" caption="{caption}" hreftitle="{metatitle}" imgtitle="{metatitle}"

Variables

A variable definition is denoted by a dollar sign preceding the alphanumeric variable name and takes the general form of:

$variablename = "definition data"

Multiple definitions can be included on a single line. The variable name is case insensitive, i.e. {BASEURL0} is the same as {baseurl0}.

Variables provide a shorthand way of specifying information that can potentially change. File paths and URLs are especially suited for this. If at a later time the information changes, all you need do is change the variable and any line using that variable automatically changes. In the example above, the first variable defined is named $baseurl0 (line 8). It is assigned the value "modules/mod_imageflow/images/". Once defined, the variable can be used in any line by specifying the variable name surrounded by brackets, i.e. {baseurl0}. The first IMG definition (line 38) uses this variable as follows:

img = "{baseurl0}thumbstrip20.jpg"

This is equivalent to the following:

img = "modules/mod_imageflow/images/thumbstrip20.jpg"

EXIF data

If your server supports the PHP EXIF library, you can choose to include exif data in combination with or instead of your own captions. In the samplelist.txt file above, lines (13-26) define variables for exif data elements and variables containing HTML DIV information. The sample illustrates 3 different ways that captions and exif information can be combined to produce the caption.

Last Updated on Monday, 30 April 2012 07:59