DEPRECATION WARNING
This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.
EXT: Gallery¶
Author: | Kasper Skårhøj |
---|---|
Created: | 2002-11-01T00:32:00 |
Changed: | 2004-08-10T13:28:07 |
Author: | Luite van Zelst |
Email: | luite@aegee.org |
Info 3: | |
Info 4: |
EXT: Gallery¶
Extension Key: lz_gallery
Copyright 2000-2002, Luite van Zelst, <luite@aegee.org>
This document is published under the Open Content License
available from http://www.opencontent.org/opl.shtml
The content of this document is related to TYPO3
- a GNU/GPL CMS/Framework available from www.typo3.com
Table of Contents¶
EXT: Gallery 1
Introduction 1
What does it do? 1
Screenshots 2
Users manual 3
Adminstration 3
Configuration 6
Reference 6
Known problems 8
To-Do list 8
Changelog 9
Introduction¶
What does it do?¶
Quick steps to use the gallery.This extension provides a plugin to display image galleries. The philosophy of the extension is simple: give you galleries fast ! Just add a record pointing to a directory on the server, and the pictures are parsed into the gallery. You want more? There is more: with this extension you can create entire listings of galleries, listings of listings...
You'll have some features available to change the images (effects, quality, size). And the layout is very customizable.
Screenshots¶
Users manual¶
Installation¶
Quick steps to use the gallery.
Install the extension using the extension manager.
Add the Gallery plugin to your page. Point it to the (sys)page where the gallery-records are stored (Start point Pid).
Create a Gallery record. Fill in the field as you see fit. Some points of attention:
The “Foto directory” field should point to an existing directory. Remember to use a trailing slash.
(Frontend) owner / usergroup fields have no functionality yet – don't give your backend-users rights to these fields.
Customize the extension using the Template Setup. Have a look at the configuration options (below). You can use the “Constants Editor” to set the options: there are two sections available: “plugin.Gallery” and “plugin.Gallery – Effects”. Normally, you should only adapt values in the the first section.
Customize the look & feel using CSS styles.
Typoscript logging¶
To find out what is going on – and how much time this is taking, you can inspect the extension's typoscript logging. To do so, turn on these options in your adminPanel:
If you do so, look for the extension key (tx_lzgallery) and you can find some (debugging) information about the extension.
And if there are any serious errors, you should be notified! Like this:
Or this:
Heavy Caching¶
As of version 0.5.0, lz_gallery has a heavy caching mechanism built in. It may have both possitive and negative effects. By default, it's partly enabled.
Positive:
- speeding up the reading of directory contents
- speeding up the generating of galleries
- speeding up the generation of the effects navigation
Negative:
lots of cach entries.
To disable / enable the heavy caching set the appropriate values in your template setup. See the reference for details. When the caching is enabled, database entries will be added to tx_lzgallery_cache_hash and tx_lzgallery_path_mtimes . The former holds the values representing the generated galleries and path- listings. The latter is merely a list of dates to verify path modify- times (mtimes).
Clearing / cleaning the cache:
When you change a directory, for instance add or delete a picture, the plugin will notice the directory has changed, delete the old cach- entries for that specific directory, read the new information and store it. So it's mostly a self-cleaning mechanism.
If you've made changes to the plugin-settings through your template constants, these changes will not always be recognised by the caching mechanism. If the result on the page are not as expected, try clearing the cache. Just click “clear the cache” in the backend, like you're used to doing, and the gallery caching tables will be automagically cleared at the same time !
Remember the logs! The extension will notify you of it's caching behaviour throught the typoscript logging-facilities.
Annotating (commenting) your images¶
The first thing you'll have to do is set up the gallery, as before. Let's suppose you have the following files in the galllery directory:
myfirstpic.jpg
yoursecond.png
lastone.gif
To comment on this files you'll have to place extra files in the same directory. They should have the same filenames, appended with an extension, by default “txt”. Like this:
kitchen.jpg.txt
yoursecond.png.txt
lastone.gif.txt
Now, let's say you want to add a title and a large comment. Ok, choose a character two separate the two parts, let's take the standard “|” character. So fill your files with the comments. For instance, here's how “kitchen.jpg.txt” could look like:
Homer & March Simpson in the kitchen | And who would like to comment on Homer eating? Not me!
Ok, that's done. Now, to have these comments used, do the following: in your template SETUP, add the following typoscript:
plugin.tx_lzgallery_pi1.gallery {
# all galleries (1x1, 2x2, 3x3 etc) default to this if they have no settings.
default {
# turn the first split, e.g. the title on
1 = 1
# and wrap it in a div so we can use stylesheets!
1.stdWrap.wrap = <div class=”plugin.tx-lzgallery-pi1-default-1”>|</div>
}
}
So now we have the title displayed. Wow, not so fast. First, you'll have have to change the main template, more specifically the subpart “<!--###GALLERY_DEFAULT###-->” Make sure it contains both “###IMAGE### and ###SPLIT_1### are in that subpart, and you're all set!
Ok, now let's try adding a filename and filesize to the pictures, this time only for single pictures. Let's see...
plugin.tx_lzgallery_pi1.gallery {
# all galleries (1x1, 2x2, 3x3 etc) default to this if they have no settings.
1x1 {
# turn the filename on
filename = 1
# and wrap it in a div so we can use stylesheets!
filename.stdWrap.wrap = <span class="tx-lzgallery-pi1-1x1-filename">|</span>
# turn the filesize on
filesize = 1
# make it human – readable (bytes, Kb's etc)
filesize.human =1
# and wrap it in a div-coat!
filesize.stdWrap.wrap = <span class="tx-lzgallery-pi1-1x1-filename"> - |</span><br>
}
}
Once more, remember to change the main template. That's all!
Subgalleries¶
As of version 0.5.0 you can use the gallery plugin to display galleries which has subgalleries. First, you'll have to grasp the concept of subgalleries used in the plugin.
You can think of the subgalleries as the opposite of a directory structure. In a directory structure every element (file, page) belongs to only one directory (folder, page) which is one step higher in the hierarchy. With the galleries, it's the other way around. A gallery can contain several subgalleries, which are all one step down in the hierarchy. This allows a tigh control over a very flexible hierarchy.
The field “subgalleries” can contain 2 kinds of records: other galleries or entire pages. If you select a page, the plugin will regard every gallery record on that page as a subgallery. This makes the gallery-management an easy job. You can organize your (sub)galleries in a hierachical page-structure, using sysmaps. You'd only have to point to the correct page. When you add / delete a gallery from that page, the change is recognized by the plugin.
Multiple references : yes, you can point to (sub)galleries from several places. This allows you to organize your galleries in categories, while some galleries may belong to several categories.
Self-reference : yes, you may create self-references and loops. I doubt wether this is usefull, but at least it doesn' t pose a problem to the plugin. It won't get in an endless loop when calculating image- counts.
Preview Image¶
As of version 0.5.0 you can customize the gallery listing. One of the aspects is to add “peview images” to the listing. They could be called “thumbnails”. By default the plugin tries to find an image to be displayed as thumbnail. To do so it randomly chooses an image from the gallery or the subgalleries. Althought that is pretty neat, if you have a lot of pictures and galleries, this behavior may be undesired, because then the chances are high some of the thumbnails were not generated and cached before - so the user will have to wait some seconds before the images are generated and the page is displayed. Furthermore: not all pictures are suitable as thumbnails in the first place.
So the solution is to edit your gallery record, and add images to the “Preview Images” box manually. Now if you add one image, that one will be used. If you add several, the plugin chooses randomly between them! Note that adding images here does not add these images to the gallery itself. It just for the thumbnails.
To chance the settings of the thumnail, change the plugin.tx_lzgallery_pi1.listing.preview
Simple Galleries¶
Sometimes you don't want a whole listing of multiple galleries on your page. Sometimes you just want to display the thumbnails for a single gallery on a page. When you decide to attach one gallery record per page, for example. The easiest way to automatically display a single gallery is to set default plugin-variables (get/post variables) with the “_DEFAULT_PI_VARS” concept. An example:
plugin.tx_lzgallery_pi1._DEFAULT_PI_VARS.showUid = 20
This will show the gallery with uid “20” as thumbnails. You could also display a gallery with subgalleries, like this:
plugin.tx_lzgallery_pi1._DEFAULT_PI_VARS.subg = 20
In theory, you could even display a single image with certain effects! To accomplish this you would set the appropriate pivars like shown above, and set the html-template in plugin.tx_lzgallery_pi1.layout to display only a picture (without navigation efc.).
(Mozilla) Site Navigation Bar
As of version 0.5.0. the plugin tries to insert links for the (mozilla) “site navigation bar”. In essence these are just html <link> elements. These are generated:
- Document --> Index = > Top level gallery or listing
- Document --> Chapers = > Galleries in the top level
- Document --> Sections => Current Gallery subgalleries
- Document --> Subsections = > Pages of images in the current display.
- More --> Bookmarks = > Custom bookmars.
- Navigation... next, previous... => The appropriate links for browsing the images.
Now, you want to get rid of all those extra options when displaying a single gallery. Ok, very nice those sizes and effects - but not what you want on your site? Included in the 0.5.0 version of the gallery is a set of presets which will demonstrate how to do this. Once again, edit your template (SETUP), and put this line in as *before* any other line regarding the template:
plugin.tx_lzgallery_pi1 < plugin.tx_lzgallery_pi1_simple
Save your settings, clear the cache and view the results! You can see the changes in the frontend, like this:
If you want to learn from this provided example, the best way to see the current values is with the “Typoscript Objectbrowser”, in your Template module. Furthermore, you can see what the example does with the Template Analyzer:
Gallery template¶
The gallery can be customized using a template. Set the template with “plugin.tx_lzgallery_pi1.layout”. This is a “cObj” which means you can set it to be any typoscript object (except “user_int” ) to render the template. So it can be read in from a file or set directly by using HTML (this is what the default template does).
The template contains four subparts:
<!--###LAYOUT###--> for rendering the whole gallery.
<!--###EFFNAV###--> for rendering the effects navigation
<!--###GALLERY_something###--> for rendering the images. (where something should be subsittuted by “default”, “1x1”, “1x2”, “3x4” etc.
<!--###LISTING###--> for rendering the gallery listings.
Here's a complete list of markers:
markers for ###LAYOUT###:
COLROWS_LABEL¶
Marker
COLROWS_LABEL
Description (substituted by...)
Label for the “Display” selector
COLROWS¶
Marker
COLROWS
Description (substituted by...)
The display selector.
MAXWIDTH_LABEL¶
Marker
MAXWIDTH_LABEL
Description (substituted by...)
Label for the “Screen width” selector.
MAXWIDTH¶
Marker
MAXWIDTH
Description (substituted by...)
The “Screen width” selector.
CLICKMODE_LABEL¶
Marker
CLICKMODE_LABEL
Description (substituted by...)
Label for the “Clickmode” selector.
PREVIOUS¶
Marker
PREVIOUS
Description (substituted by...)
Link to the previous page / picture.
NEXT¶
Marker
NEXT
Description (substituted by...)
Link to the next page / picture.
EFFECTS¶
Marker
EFFECTS
Description (substituted by...)
The entire effects-navigation.
TITLE¶
Marker
TITLE
Description (substituted by...)
The gallery's title.
DESCR_LONG¶
Marker
DESCR_LONG
Description (substituted by...)
The gallery's longer-description (richtext).
GALLERY¶
Marker
GALLERY
Description (substituted by...)
The pictures.
PATH¶
Marker
PATH
Description (substituted by...)
The original path from your gallery record.
DESCR_SHORT¶
Marker
DESCR_SHORT
Description (substituted by...)
The gallery's shorter description (plain text).
STARTDATE¶
Marker
STARTDATE
Description (substituted by...)
The gallery's date. (To set the formatting / timezone, see reference).
markers for ###GALLERY_DEFAULT###, ###GALLERY_1x1###, ###GALLERY_1x2, etc...
IMAGE¶
Marker
IMAGE
Description (substituted by...)
Inserrt the image. this is a must!
FILENAME¶
Marker
FILENAME
Description (substituted by...)
Insert the filename.
FILESIZE¶
Marker
FILESIZE
Description (substituted by...)
Insert the filesize.
SPLIT_1¶
Marker
SPLIT_1
SPLIT_2
SPLIT_3
...
Description (substituted by...)
Inserts the splitted parts of the annotations.
markers, subparts and wraps for ###LISTING###
SEARCHBOX¶
Tag
SEARCHBOX
Type
marker
Description (substituted by...)
Inserrts the searchbox.
SEARCHBOX_LABEL¶
Tag
SEARCHBOX_LABEL
Type
marker
Description (substituted by...)
Label for the searchbox
LISTITEM¶
Tag
LISTITEM
Type
subpart
Description (substituted by...)
Template for a single gallery item
NOTFOUND¶
Tag
NOTFOUND
Type
subpart
Description (substituted by...)
Template for the listing when no galleries are found. (Beause of the search of the user or because of an error).
PAGINATION¶
Tag
PAGINATION
Type
subpart
Description (substituted by...)
Template for the pagination.
markers, subparts and wraps for ###LISTITEM### and ###PARENTGALLERY###
SUBCOUNT¶
Tag
SUBCOUNT
Type
marker
Description (substituted by...)
Inserts the number of subgalleries. If you don't want to set this value if the value is 0 than set the option plugin.tx_lzgallery_pi1.listing.nosubcountIfzero . See reference.
COUNT¶
Tag
COUNT
Type
marker
Description (substituted by...)
Inserts the number of images. If a gallery has subgalleries, the number of images of all the subgalleries is inserted.
SUBCOUNT_LABEL¶
Tag
SUBCOUNT_LABEL
COUNT_LABEL
Type
markers
Description (substituted by...)
Inserts the appropriate labels.
HASSUBS¶
Tag
HASSUBS
Type
marker
Description (substituted by...)
Inserts the object plugin.tx_lzgallery_pi1.listing.hassubs if the gallery has subgalleries. Otherwise inserted empty.
NOSUBS¶
Tag
NOSUBS
Type
marker
Description (substituted by...)
Inserts the object plugin.tx_lzgallery_pi1.listing.hassubs if the gallery has subgalleries. Otherwise inserted empty.
PREVIEW¶
Tag
PREVIEW
Type
marker
Description (substituted by...)
Inserts a random image. If you have added images to you're gallery record, one of these will be choosen from randomly. If the list is empty, the extension will choose a random image from the specified path. If the gallery has subgallery, an image is choosen randomly from the subgalleries images.
TITLE¶
Tag
TITLE
DESCR_SHORT
DESCR_LONG
STARTDATE
ENDDATE
LOCATION
Type
markers
Description (substituted by...)
These database fields will be inserted.
TITLE_LABEL¶
Tag
TITLE_LABEL
DESCR_SHORT_LABEL DESCR_LONG_LABEL
STARTDATE_LABEL
ENDDATE_LABEL
LOCATION_LABEL
Type
markers
Description (substituted by...)
The database labels for the respective fields.
LINKGALLERY¶
Tag
LINKGALLERY
Type
wrap
Description (substituted by...)
Link to display the current gallery images. Wrap will be empty if there are no images.
LINKSUBGALLERY¶
Tag
LINKSUBGALLERY
Type
wrap
Description (substituted by...)
Link to display gallery listing with the subgalleries. Wrap will be empty if there are no subgalleries.
LINKGENERAL¶
Tag
LINKGENERAL
Type
wrap
Description (substituted by...)
Will wrap like LINKGALLERY, except if the gallery has subgalleries, in which case it will wrap like LINKSUBGALLERY
markers, subparts and wraps for ###PAGINATION###
PREVIOUS¶
Tag
PREVIOUS
Type
marker
Description (substituted by...)
Inserts the previous link.
NEXT¶
Tag
NEXT
Type
marker
Description (substituted by...)
Inserts the next link.
PAGE_ITEM¶
Tag
PAGE_ITEM
Type
subpart
Description (substituted by...)
Template for a single “page ...” link.
markers, subparts and wraps for ###PAGE_ITEM###
PAGE_LINK¶
Tag
PAGE_LINK
Type
wrap
Description (substituted by...)
Inserts the link to the specific page.
PAGE_LABEL¶
Tag
PAGE_LABEL
Type
marker
Description (substituted by...)
Inserts the page label (“page” by default).
PAGE_NUMBER¶
Tag
PAGE_NUMBER
Type
marker
Description (substituted by...)
Inserts the page number for the specific link.
markers, subparts and wraps for ###NOTFOUND###
MESSAGE¶
Tag
MESSAGE
Type
marker
Description (substituted by...)
Inserrts the searchbox.
BACKLINK¶
Tag
BACKLINK
Type
wrap
Description (substituted by...)
Insert a “back” link. This is a link to the very same page, but with different variables.
If the search variable (“tx_lzgallery_pi1[sword]”) is detected, it is unset.
Otherwise, an error is assumed and the link refers to the same page unsetting all variables.
BUTTON¶
Tag
BUTTON
Type
marker
Description (substituted by...)
Insert the “gallery_notfound_back” label (“go back” by default).
If the “notfound” object is set, it renders this object and inserts it instead. This can be used to insert an image instead, for example. See reference for the “notfound” object.
markers, subparts and wraps for ###SORTING###
PREVIOUS¶
Tag
PREVIOUS
Type
marker
Description (substituted by...)
Inserts the previous link.
NEXT¶
Tag
NEXT
Type
marker
Description (substituted by...)
Inserts the next link.
PAGE_ITEM¶
Tag
PAGE_ITEM
Type
subpart
Description (substituted by...)
Template for a single “page ...” link.
markers, subparts and wraps for ###SORT_ITEM###
SORT_FIELD¶
Tag
SORT_FIELD
Type
marker
Description (substituted by...)
Inserts the label for the sorting field.
SORT_LINK¶
Tag
SORT_LINK
Type
marker
Description (substituted by...)
Inserts the page label (“page” by default).
PAGE_NUMBER¶
Tag
PAGE_NUMBER
Type
marker
Description (substituted by...)
Inserts the page number for the specific link.
Configuration¶
Have a look at the html produced by the plugin: you'll see some default CSS for the gallery. You may overwrite the CSS with whatever styles you like! If you do, you could eventually unset the default css entirely. Use something like this in your template setup:
page = PAGE
...
page.stylesheet = your_style_sheet.css
#this unsets the default styles:
plugin.tx_lzgallery_pi1._CSS_DEFAULT_STYLE >
I recommend using “simulateStaticDocuments” in combination with variable hashing. This extension passes around a lot of variables, so if you don't use hashing, the url will get out of control (very long) easily! On the other hand, you should consider that if you use md5-hashing with a lot of variables (and combinations) the md5-hash tables in mysql might get millions of entries, which would eventually slow down your entire site. So it's a choise between two evils ;-)
config.simulateStaticDocuments = 1
config.simulateStaticDocuments_pEnc = md5
config.simulateStaticDocuments_noTypeIfNoTitle = 1
The plugin needs the “content (default)“ template in order to display the “long description”.
To change the (language) labels, you can do the following:
plugin.tx_lzgallery_pi1._LOCAL_LANG.language {
label1 = ...
label2 = ...
}
where “language” can be either “default” or a 2-character shorthand for the country. To view a full list of labels defined/available, see the file “ext/lz_gallery/pi1/locallang.php”.
Reference¶
Options in the template SETUP (!!):
plugin.tx_lzgallery_pi1 :
basepath¶
Property
basepath
Data type
string
Description
Points to the base-directory where all the galleries should reside. The basepath itself is relative to the webroot. Should end with a forward slash.
Exmpl.: “fileadmin/fotos/”.
Default
fileadmin/
temppath_fotos¶
Property
temppath_fotos
Data type
string
Description
Points to the temp-path where the cached / generated images should reside. The path is relative to the webroot.
Exampl.: “typo3temp/mygallery/”
Note: this will only work if you allow this specific temp-path in your install tool or localconf.php (“allowedTempPaths” option). And the directory exists and have read/write access. Otherwise you won't see a single image!
Using different temp-paths allows you to delete the bulk of cached images from the plugin without affecting your site.
Default
typo3temp/
temppath_effects¶
Property
temppath_effects
Data type
string
Description
Same as above, for the image with effects applied.
Default
typo3temp/
filetypes¶
Property
filetypes
Data type
list
Description
Comma seperated list of image-filetypes allowed.
Default
jpg,png,gif,bmp
timezone¶
Property
timezone
Data type
string
Description
Use this to set the correct timezone. The timezone should be recognized by your OS, while it is issued with a “putenv('TZ=....') command. This is to correctly display the dates.
Default
dateFormat¶
Property
dateFormat
Data type
strftime-conf
Description
Set this to change the startdate-formatting.
Default
listing.titleWrap¶
Property
listing.titleWrap
Data type
wrap
Description
OBSOLETE SETTING
Default
OBSOLETE SETTING
listing.resultAtATime¶
Property
listing.resultAtATime
Data type
int
Description
Number of galleries per page in the listing.
Default
20
listing.nosubcountifzero¶
Property
listing.nosubcountifzero
Data type
boolean
Description
If set, the value “0” for the number of subgalleries is displayed as an empty string in stead.
Default
1
listing.preview¶
Property
listing.preview
Data type
IMAGE
Description
Change the settings of this image to manipulate the resulting “preview image” in the gallery listings. The file location (listing.preview.file) is set by the plugin.
Default
listing.maxPages¶
Property
listing.maxPages
Data type
int
Description
This limits the number of pages in the gallery listings. For example:
plugin.tx_lzgallery_pi1.listing {
resultsAtATime = 7
maxPages = 10
}
this will display only 70 (sub)galleries in any listing.
Default
100
listing.maxlevel¶
Property
listing.maxlevel
Data type
int
Description
Limits the depth of the search for subgalleries. Every subgallery found is searched for subgalleries of it's own using database queries. This setting avoid long/endless loops and problems with the database. Do not change this unless you know what you are doing.
Default
10
gallery.default¶
Property
gallery.default
gallery.1x1
gallery.1x2
gallery.2x2
gallery.1x3
...
etc
Data type
GALLERY_OBJECT (see below)
Description
Holds objects which define the behavior of annotations.
default view (if no other defined)
view for 1 columns x 1 rows
view for 1 columns x 2 rows
view for 2 columns x 2 rows
view for 1 columns x 3 rows
... etc
Default
commentSplits¶
Property
commentSplits
Data type
int+
Description
Sets the limit for the number of splits for the annotation files.
Default
commentFiletype¶
Property
commentFiletype
Data type
string
Description
Set the filetype for the annotation files.
Default
txt
commentBytes¶
Property
commentBytes
Data type
int+
Description
Set the limit for the number of bytes read from annotation files. This is to prevent the extension from using loads of memory when encountering large annotation files.
Default
4096
layout¶
Property
layout
Data type
cObj
Description
This cObj (that is: you can choose what object you use: HTML, TEMPLATE, etc) should return the main template. This template is needed to parse the gallery. Look at the standard extension setup with your template-analyzer to see what the default value is.
Default
imageLinkWrap¶
Property
imageLinkWrap
Data type
imageLinkWrap
Description
Use this to set custom values for the popups generated byt the “newwindow” clickmode. E.g.
plugin.tx_lzgallery_pi1.imgeLinkWrap {
title = I love Typo3
}
Default
overrideImageLinkWrap¶
Property
overrideImageLinkWrap
Data type
boolean
Description
By default, some of the values are set by the plugin. This is being generated:
plugin.tx_lzgallery_pi1.imgeLinkWrap {
JSwindow = 1
enable = 1
width = ... (calculated)
height = ... (calculated)
alternativeTempPath = ... (set through options)
}
If you want your settings to prevail, you can override these standard options by settings this option to true.
Default
false
optimizeFactor¶
Property
optimizeFactor
Data type
int
Description
You probably know how to set the max. width for a gallery. The max.width of a picture is calculated as a result of this value, as is the max. height of the picture.
If most pictures are taken in “landscape”, most pictures' width is larger than the pictures' height. A single picture in “portrait” could disrupt the nice grid of pictures adding a lot of whitespace. To avoid this, by default the extension tries to optimize the width / height.
Regular photographs have 3:4 dimensions, so multiplying (reducing) the height by a factor of 0.75 corrects the whitespace problem.
If you don't want the plugin to do any optimizing, set this value to 1, or unset the below setting “optimize”.
Default
0.75
optimize¶
Property
optimize
Data type
“width”, “height”
Description
If most pictures are in “portrait” direction, the above behavior might be undesirable. In stead you might want to correct the picture width's of “landscape” picture. Set this value to “width” to do so.
If you don't want the plugin to do any optimizing, unset this value1, or set the above setting “optimizeFactor” to 1.
Default
height
forceOptimize¶
Property
forceOptimize
Data type
boolean
Description
By default, the above optimization is a “suggestion” to the system. This means all heights/widths are just a maximum value. To enforce all picture dimensions, set this value to true. Smaller pictures will be enlarged, pictures in other dimensions will be changed.
Default
false
caching¶
Property
caching
Data type
boolean
Description
Enable/disable any caching done by the lz_gallery heavycaching mechanism.
Default
false
caching.paths¶
Property
caching.paths
Data type
boolean
Description
Enable/disable path-information caching. Only if “caching” is set to true.
Default
true
caching.galleries¶
Property
caching.galleries
Data type
boolean
Description
Enable/disable gallery-output caching. Only if “caching” is set to true.
Default
true
previous¶
Property
previous
Data type
cObj
Description
Set this cObj (e.g. IMAGE, TEXT, HTML ...) to override the “previous” link. By default, the link is displayed as a label from the language files.
Example:
plugin.tx_lzgallery_pi1.previous = IMAGE
plugin.tx_lzgallery_pi1.previous {
file = fileadmin/prev_button.png
file.width = 80m
file.height = 100m
}
The result of this cObj will be forcibly wrapped with the link generated by the plugin. It's probably not a good idea to define you own link with the cObj.
Default
next¶
Property
next
Data type
cObj
Description
Same as above, but for the “next” link.
Default
previous_nolink¶
Property
previous_nolink
Data type
cObj
Description
Same as above, but only used when there is no previous page to display (if there is no link). For example, to hide the lable/button if no link is available:
plugin.tx_lzgallery_pi1.previous_nolink = TEXT
Or if you want to display the same image as above (on one line!):
plugin.tx_lzgallery_pi1.previous_nolink < plugin.tx_lzgallery_pi1.previous
Default
next_nolink¶
Property
next_nolink
Data type
cObj
Description
Same as above, but for the “next” link.
Default
hidedescription¶
Property
hidedescription
Data type
boolean
Description
Enable/disable hiding of the description. If enabled, the descr_long field will only be shown once in
the single gallery display.
Default
true
qtt¶
Property
qtt
Data type
filepath
Description
If you want to change the properties of the table generated by the template, you can use a Qiktable Template. This allows you to customize virtually anything in the table. The template is called as the very last thing before the output is generated, so you can also unset anyhing set by default by the extension. (like align=”center”).
Read more about using a Qiktable template in the Qiktable `reference < http://typo3.org/doc.0.html?&tx_extrepmgm_pi1[extUid]=225&tx_extrepmgm _pi1[tocEl]=931&cHash=8f23b81713#oodoc_part_933>`_ and examples .
Default
CMD¶
Property
CMD
Data type
“singleView”
Description
If you set this to “singleView” the extension will attempt to show a single gallery. If no “showUid” variable is set in the url (or through _PIVAR_PRESETS) it will fetch the first record associated with the plugin.
Default
_DEFAULT_PI_VARS¶
Property
_DEFAULT_PI_VARS
Data type
Description
Use this as explained in the secion “Simple Gallery”. Can be used to set default url parameters (to show a certain gallery or set effects etc).
Default
_LOCAL_LANG.country.langkey¶
Property
_LOCAL_LANG.country.langkey
Data type
Description
Substitue “country” for the two-letter country code (like “de” or “nl”) or “default” (for english/default) and substitue “langkey” for the language-key used by the extension. This will override any language label in pi/locallang.php.
To see what labels are available, open that file.
Default
Otions in the template SETUP (!!):
plugin.tx_lzgallery_pi1.gallery.GALLERY_OBJECT
1,2,3,4...¶
Property
1,2,3,4...
Data type
boolean /
.stdWrap
.richtext (boolean)
Description
Annotations-files are split with the value of “separator”. Each part corresponds to a number. Displat properties of the first part are set with “1” , the second part with “2” etc.
If you set the “richtext” suboption, this part of the annotation will be regarded as richtext, and parsed accordingly. This is done with “plugin.tx_lzgallery_pi1.text” (which is a copy of “tt_ content.text.20 ”.
Default
stdWrap¶
Property
stdWrap
Data type
stdWrap
Description
stdWrap around the image in this gallery.
Default
emptyCell¶
Property
emptyCell
Data type
cObj
Description
If this value is set, this is put in the place of any empty cells (e.g. if you display 8 images with 2x5 display two cells will be empty.
Default
filename¶
Property
filename
Data type
boolean / .stdWrap
Description
Configuration for adding the filename to the image.
Default
filesize¶
Property
filesize
Data type
boolean /.stdWrap
.human (boolean)
Description
Configuration for adding the filesize to the image. The suboption “human” renders the filesize in human readable form (bytes, Kb, Mb, Gb).
Default
You can customize the effects to some extend: for each effect the setup has two fields: a list of options (plugin.tx_lzgallery_pi1.piVarOptions.something) and a default value (plugin.tx_lzgallery_pi1.piVarPresets.something). The latter should be a value available in the list, else the first value in the list will be default.
The list of options is reflected in the dropdown-lists in the navigation / effects.
plugin.tx_lzgallery_pi1.piVarPresets -- plugin.tx_lzgallery_pi1.piVarOptions:
maxwidth¶
Property
maxwidth
Data type
list / int +
Description
Defines the maximum width used in the extension. This value is used in the following way: it is the tótal maxwidth; the image-sizes are calculated accordingly, by dividing the maxwidth by the number of columns.
Presets
540
colrows¶
Property
colrows
Data type
list / string
Description
Display type number of colums 'x' Number of columns. Be sure to include “1x1” as an option (or you won't be able to display a single images!).
Presets
5x5
rotation¶
Property
rotation
Data type
list / int +
Description
Image rotation.
Presets
0
colors¶
Property
colors
Data type
list / int *
Description
Number of colors. (Color reduction). Use integer numbers. “normal” is a special value meaning “no color reduction”.
Presets
normal
effect¶
Property
effect
Data type
list/ *
Description
Use the default options only! The value is straight passed to imagemagick, so typing-mistakes are not encouraged!
Presets
normal
gamma¶
Property
gamma
Data type
list / float +
Description
Gamma. (Good to clear up / brighten images).
Presets
0
clickmode¶
Property
clickmode
Data type
Description
Use only these options (hardcoded):
- samewindow_noeffect : single image is opened (using 1column x 1row). No effects available.
- samewindow : same, but with effects
- newwindow : standard Typo3 popup-window using javaScript.
- samewindow_max: single image is opnened (using 1column x 1row). No effects available. Image is not size-restricted (will be displayed in original size). Note that this will reveal the original foto-path (not the temp path).
Presets
samewindow_noeffect
swirl¶
Property
swirl
Data type
list / int
Description
Swirlpool effect. Integer is number of degrees.
Presets
0
contrast¶
Property
contrast
Data type
list / int
Description
Increase / decrease image contrast.
Presets
0
implode¶
Property
implode
Data type
list / int
Description
Implode / explode the image from the image center.
Presets
0
charcoal¶
Property
charcoal
Data type
list / int
Description
Charcoal effect.
Presets
0
mirror¶
Property
mirror
Data type
list / *
Description
Use only these options.
Presets
normal
channel¶
Property
channel
Data type
list / *
Description
Extract an color-channel from the image. Use only these options.
Presets
all
brightness¶
Property
brightness
Data type
list / int +
Description
Increase the image brightness.
Presets
0
saturation¶
Property
saturation
Data type
list / int +
Description
Increase the image saturation.
Presets
0
hue¶
Property
hue
Data type
list / int +
Description
Increase the image hue.
Presets
0
amplitude¶
Property
amplitude
Data type
list / int +
Description
Produce wave-effects, in combination with the wavelength.
Presets
0
wavelength¶
Property
wavelength
Data type
list / int +
Description
Produce wave-effects, in combination with the amplitude.
Presets
0
spread¶
Property
spread
Data type
list / int +
Description
Random pixel displacement by factor.
Presets
0
solarize¶
Property
solarize
Data type
list / int +
Description
Solarization (over-lighting) effect.
Presets
0
((generated))¶
Example¶
For instance, you could decide to change the number of colums. Also, you want to limit the possibility of color-reduction to 16 and 256 colors. Add this to your template constants section.
plugin.tx_lzgallery{
piVarPresets {
# set the default to 3 columns
numcols = 3
}
piVarOptions {
# be sure to include the default (set to '3') in this list also
numcols = 1,3,5,10
# and it's a nice idea to include 'normal' also ;-)
colors = normal,16,256
}
}
FAQ¶
Why use “heavy caching” ? Because it can save a lot of processing time !
Why don't he gallery listings get cached?
Because this is logically not possible. One of the features of the Gallery Listings is to display “preview” images. These are picked at random, and because of that they can't be cached.
I don't want all the extra options, like effects, clickmodes etc. How do I get rid of them?
The easy approach is to use the “Simple” presets shipped with the extensions. Read the section “Simple Gallery” in this manual. Or do it yourself !First unset the appropriate settings in plugin.tx_lzgallery.piVarPresets and plugin.tx_lzgallery.piVarOptions. Then cut out unwanted parts from the template in plugin.tx_lzgallery_pi1.layout (SETUP).
What are *piVarPresets* and *piVarOptions* ?
“piVars” is the technical name used to refer to the http-get and http- post variables. If you refer to a page like this:
http://www.mysite.org/index.php?id=10&tx_lzgallery_pi1[showUid]=10]&tx_lzgallery_pi1[maxwidth]=1000
variables “showUid” and “maxwidth” will be passed on to the gallery extension. For security reasons, the frontend user is not allowed to set just any value he / she likes. For example, you may want to restrict the allowed “maxwidth” values, to optimize the resulting page width. To accomplish this set the appropriate values of piVarPresets and piVarOptions. Here piVarOptions.maxwidth is the list of allowed values for the maxwidth variable, and piVarPresets.maxwidth is the default value is none is set. If you change these settings, be sure to include the default value in piVarPresets in the allowed list set in piVarOptions !
See section “Reference” for more detailled information.
What's the difference between “ *plugin.tx_lzgallery”* and “ *plugin.tx_lzgallery_pi1”* ? Which do I have to use?
You have two different ways to set values used by the gallery. First, by setting values through the SETUP part of your template. Secondly, through the CONSTANTS part. That's the difference: use plugin.tx_lzgallery_pi1 in your SETUP and plugin.tx_lzgallery in your CONSTANTS. Ok, but which to use. The reference section of this manual tells you which to use. But if you are in doubt or something is not working (maybe there's an mistake in the manual ;-) ) the save bet is to use SETUP. I have choosen to use the same names in both SETUP and CONSTANTS to avoid confusion.
Let 's look at some explanation with the template analyzer:
What you see in this screenshot is a small part of the standard SETUP that comes with the extension. This is automatically loaded when you install the extension. You see that the values like “plugin.tx_lzgallery_pi1.basepath” are copied from the CONSTANTS like plugin.tx_lzgallery.basepath”. This shows that in this case you can either change the value of the constant (then the changed value will be copied) or the value of the setup (in which case nothing is being copied anymore - since the new value is set by you). However, in order for the solution with the CONSTANTS to work - the standard template has to show the correct line which copies the value into the setup. If you have doubts about that, have a look at the Template Analyzer yourself.
Once again - to view the resulting values - use the Object Browser in your Template module.
Can I add titles and comments to my pictures?
Yes you can! This extension does not allow a per-picture database record, but you can use txt-files to comment your pictures. This is not an ideal solution, but it is a fair compromise between speed and customizability. See the subsection “Annotating (commenting) your images” in this manual.
Can I have (multiple levels of) subgalleries?
Yes, as of version 0.5.0 you can! You can add infinite levels of subgalleries. You can use this to categorize your galleries.
Why do you use a directory based approach, and not database records?
This gallery has today's technology in mind: the digital photocamera. The “philosophy” is too be able to shoot pictures (during an event), upload them all at once, add one gallery-record, and you're all set! If you have hundreds or even thousands of photo's you want to display on your website, adding one record for every picture is bound to be a costly and tedious business.
Why did you write this extension ?
I needed a quick 'n dirty gallery solution, and thought this would be a nice challenge! Since then it has steadily grown in functionality: a lot of it (like commenting the pictures using files) was added because of requests in the Typo3 community.
Known problems¶
- Security issue: the only check used for all the variables that are passed around in this extension, is a list-membership test; the options are checked against the list in piVarOptions. This allows no room for shell escapes or other security problems. But! If you're template-setup is flawed and you allow problematic values in the piVarOptions.... well, just don't !
To-Do list¶
- Stalled: Frontend uploading of images / creation of galleries !
- Stalled: Integrate watermarks.
- Todo: Add “seperators” to the galleries.
Changelog¶
0.6.0
- Fix: if no pictures can be displayed, html makers are no longer displayed
- Fix: images are sorted alphabetically.
- Fix: documentation updated about listing.maxlevel and listing.maxPages.
- Fix: rand() errors on MS windows.
- Fix: (hopefully!) caching issues with galleries displayed on several pages or in several languages.
- Fix: caching issues with wrong directory content being displayed
0.5.0
- Added: Subgalleries (!!).
- Added: Customizing the gallery listing.
- Added: Preview Images.
- Added: Heavy Caching mechanism.
- Added: “Top” and “Up” links for easy navigation.
- Added: Set of “simple” presets added at public request. (hiding effects, maxwidths, clickmoe and display options).
- Added: Using alt-text for the images (filename).
- Fixed: “_DEFAULT_PI_VARS” functionality.
- Added: Customizing the next/previous links.
- Added: Customizing the width/height optimization factor.
- Added: Customizing the “newwindow” popup settings.
- Fixed: Hardcoded <div> for “descr_long”
- Fixed: Logic bug which forced effect-navigation to appear.
0.4.0
- The effects-navigation is now cached, which saves about 60ms per hit.
- Added nice icons. Big thanx to Netcreators.nl !
0.3.0
- Added Typoscript logging.
- Added layout customization through html-templates. Cleaned up the code.
- Added possibilities to annotate your images with a file-based approach.
- Fixed problems with alternativeTempPath
- Fixed problems with path slashes. Extended possibilities for any kind of mixed slash-using. E.g. even “\filadmin./pathto/your/fotos” is a valid path now.
0.2.0
Added “Constant Editor” Support. All custom settings in your template should now use “plugin.tx_lzgallery” in the constants section, not “plugin.tx_lzgallery_pi1” in the setup section anymore.
0.1.2
- Fixed flawed temp-paths in ext_typoscript_setup.txt.
- Fileextensions are now regarded case-insensitive
0.1.0
First edition !