.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ============ 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: EXT: Gallery ============ Extension Key: **lz\_gallery** Copyright 2000-2002, Luite van Zelst, 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: 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: Introduction ------------ .. _What-does-it-do: 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: Screenshots ^^^^^^^^^^^ |img-1| |img-2| |img-3| .. _Users-manual: Users manual ------------ .. _Installation: 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: 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: |img-4| If you do so, look for the extension key (tx\_lzgallery) and you can find some (debugging) information about the extension. |img-5| And if there are any serious errors, you should be notified! Like this: |img-6| Or this: |img-7| .. _Heavy-Caching: 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: 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 =
|
} } 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 “” 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 = | # 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 = -   |
} } Once more, remember to change the main template. That's all! .. _Subgalleries: 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. |img-8| 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: 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. |img-9| 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. |img-10| To chance the settings of the thumnail, change the plugin.tx\_lzgallery\_pi1.listing.preview .. _Simple-Galleries: 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 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: |img-11| 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: |img-12| .. _Gallery-template: 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: for rendering the whole gallery. for rendering the effects navigation for rendering the images. (where something should be subsittuted by “default”, “1x1”, “1x2”, “3x4” etc. for rendering the gallery listings. Here's a complete list of markers: *markers for ###LAYOUT###:* .. ### BEGIN~OF~TABLE ### .. _COLROWS-LABEL: COLROWS\_LABEL """""""""""""" .. container:: table-row Marker COLROWS\_LABEL Description (substituted by...) Label for the “Display” selector .. _COLROWS: COLROWS """"""" .. container:: table-row Marker COLROWS Description (substituted by...) The display selector. .. _MAXWIDTH-LABEL: MAXWIDTH\_LABEL """"""""""""""" .. container:: table-row Marker MAXWIDTH\_LABEL Description (substituted by...) Label for the “Screen width” selector. .. _MAXWIDTH: MAXWIDTH """""""" .. container:: table-row Marker MAXWIDTH Description (substituted by...) The “Screen width” selector. .. _CLICKMODE-LABEL: CLICKMODE\_LABEL """""""""""""""" .. container:: table-row Marker CLICKMODE\_LABEL Description (substituted by...) Label for the “Clickmode” selector. .. _PREVIOUS: PREVIOUS """""""" .. container:: table-row Marker PREVIOUS Description (substituted by...) Link to the previous page / picture. .. _NEXT: NEXT """" .. container:: table-row Marker NEXT Description (substituted by...) Link to the next page / picture. .. _EFFECTS: EFFECTS """"""" .. container:: table-row Marker EFFECTS Description (substituted by...) The entire effects-navigation. .. _TITLE: TITLE """"" .. container:: table-row Marker TITLE Description (substituted by...) The gallery's title. .. _DESCR-LONG: DESCR\_LONG """"""""""" .. container:: table-row Marker DESCR\_LONG Description (substituted by...) The gallery's longer-description (richtext). .. _GALLERY: GALLERY """"""" .. container:: table-row Marker GALLERY Description (substituted by...) The pictures. .. _PATH: PATH """" .. container:: table-row Marker PATH Description (substituted by...) The original path from your gallery record. .. _DESCR-SHORT: DESCR\_SHORT """""""""""" .. container:: table-row Marker DESCR\_SHORT Description (substituted by...) The gallery's shorter description (plain text). .. _STARTDATE: STARTDATE """"""""" .. container:: table-row Marker STARTDATE Description (substituted by...) The gallery's date. (To set the formatting / timezone, see reference). .. ###### END~OF~TABLE ###### *markers for ###GALLERY\_DEFAULT###, ###GALLERY\_1x1###, ###GALLERY\_1x2, etc...* .. ### BEGIN~OF~TABLE ### .. _IMAGE: IMAGE """"" .. container:: table-row Marker IMAGE Description (substituted by...) Inserrt the image. this is a must! .. _FILENAME: FILENAME """""""" .. container:: table-row Marker FILENAME Description (substituted by...) Insert the filename. .. _FILESIZE: FILESIZE """""""" .. container:: table-row Marker FILESIZE Description (substituted by...) Insert the filesize. .. _SPLIT-1: SPLIT\_1 """""""" .. container:: table-row Marker SPLIT\_1 SPLIT\_2 SPLIT\_3 ... Description (substituted by...) Inserts the splitted parts of the annotations. .. ###### END~OF~TABLE ###### *markers, subparts and wraps for ###LISTING###* .. ### BEGIN~OF~TABLE ### .. _SEARCHBOX: SEARCHBOX """"""""" .. container:: table-row Tag SEARCHBOX Type marker Description (substituted by...) Inserrts the searchbox. .. _SEARCHBOX-LABEL: SEARCHBOX\_LABEL """""""""""""""" .. container:: table-row Tag SEARCHBOX\_LABEL Type marker Description (substituted by...) Label for the searchbox .. _LISTITEM: LISTITEM """""""" .. container:: table-row Tag LISTITEM Type subpart Description (substituted by...) Template for a single gallery item .. _NOTFOUND: NOTFOUND """""""" .. container:: table-row 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: PAGINATION """""""""" .. container:: table-row Tag PAGINATION Type subpart Description (substituted by...) Template for the pagination. .. ###### END~OF~TABLE ###### *markers, subparts and wraps for ###LISTITEM### and ###PARENTGALLERY###* .. ### BEGIN~OF~TABLE ### .. _SUBCOUNT: SUBCOUNT """""""" .. container:: table-row 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: COUNT """"" .. container:: table-row 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: SUBCOUNT\_LABEL """"""""""""""" .. container:: table-row Tag SUBCOUNT\_LABEL COUNT\_LABEL Type markers Description (substituted by...) Inserts the appropriate labels. .. _HASSUBS: HASSUBS """"""" .. container:: table-row 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: NOSUBS """""" .. container:: table-row 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: PREVIEW """"""" .. container:: table-row 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: TITLE """"" .. container:: table-row Tag TITLE DESCR\_SHORT DESCR\_LONG STARTDATE ENDDATE LOCATION Type markers Description (substituted by...) These database fields will be inserted. .. _TITLE-LABEL: TITLE\_LABEL """""""""""" .. container:: table-row 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: LINKGALLERY """"""""""" .. container:: table-row Tag LINKGALLERY Type wrap Description (substituted by...) Link to display the current gallery images. Wrap will be empty if there are no images. .. _LINKSUBGALLERY: LINKSUBGALLERY """""""""""""" .. container:: table-row 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: LINKGENERAL """"""""""" .. container:: table-row 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 .. ###### END~OF~TABLE ###### *markers, subparts and wraps for ###PAGINATION###* .. ### BEGIN~OF~TABLE ### .. _PREVIOUS: PREVIOUS """""""" .. container:: table-row Tag PREVIOUS Type marker Description (substituted by...) Inserts the previous link. .. _NEXT: NEXT """" .. container:: table-row Tag NEXT Type marker Description (substituted by...) Inserts the next link. .. _PAGE-ITEM: PAGE\_ITEM """""""""" .. container:: table-row Tag PAGE\_ITEM Type subpart Description (substituted by...) Template for a single “page ...” link. .. ###### END~OF~TABLE ###### *markers, subparts and wraps for ###PAGE\_ITEM###* .. ### BEGIN~OF~TABLE ### .. _PAGE-LINK: PAGE\_LINK """""""""" .. container:: table-row Tag PAGE\_LINK Type wrap Description (substituted by...) Inserts the link to the specific page. .. _PAGE-LABEL: PAGE\_LABEL """"""""""" .. container:: table-row Tag PAGE\_LABEL Type marker Description (substituted by...) Inserts the page label (“page” by default). .. _PAGE-NUMBER: PAGE\_NUMBER """""""""""" .. container:: table-row Tag PAGE\_NUMBER Type marker Description (substituted by...) Inserts the page number for the specific link. .. ###### END~OF~TABLE ###### *markers, subparts and wraps for ###NOTFOUND###* .. ### BEGIN~OF~TABLE ### .. _MESSAGE: MESSAGE """"""" .. container:: table-row Tag MESSAGE Type marker Description (substituted by...) Inserrts the searchbox. .. _BACKLINK: BACKLINK """""""" .. container:: table-row 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: BUTTON """""" .. container:: table-row 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. .. ###### END~OF~TABLE ###### *markers, subparts and wraps for ###SORTING###* .. ### BEGIN~OF~TABLE ### .. _PREVIOUS: PREVIOUS """""""" .. container:: table-row Tag PREVIOUS Type marker Description (substituted by...) Inserts the previous link. .. _NEXT: NEXT """" .. container:: table-row Tag NEXT Type marker Description (substituted by...) Inserts the next link. .. _PAGE-ITEM: PAGE\_ITEM """""""""" .. container:: table-row Tag PAGE\_ITEM Type subpart Description (substituted by...) Template for a single “page ...” link. .. ###### END~OF~TABLE ###### *markers, subparts and wraps for ###SORT\_ITEM###* .. ### BEGIN~OF~TABLE ### .. _SORT-FIELD: SORT\_FIELD """"""""""" .. container:: table-row Tag SORT\_FIELD Type marker Description (substituted by...) Inserts the label for the sorting field. .. _SORT-LINK: SORT\_LINK """""""""" .. container:: table-row Tag SORT\_LINK Type marker Description (substituted by...) Inserts the page label (“page” by default). .. _PAGE-NUMBER: PAGE\_NUMBER """""""""""" .. container:: table-row Tag PAGE\_NUMBER Type marker Description (substituted by...) Inserts the page number for the specific link. .. ###### END~OF~TABLE ###### .. _Configuration: 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: Reference ^^^^^^^^^ Options in the template SETUP (!!): *plugin.tx\_lzgallery\_pi1* : .. ### BEGIN~OF~TABLE ### .. _basepath: basepath """""""" .. container:: table-row 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: temppath\_fotos """"""""""""""" .. container:: table-row 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: temppath\_effects """"""""""""""""" .. container:: table-row Property temppath\_effects Data type string Description Same as above, for the image with effects applied. Default typo3temp/ .. _filetypes: filetypes """"""""" .. container:: table-row Property filetypes Data type list Description Comma seperated list of image-filetypes allowed. Default jpg,png,gif,bmp .. _timezone: timezone """""""" .. container:: table-row 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: dateFormat """""""""" .. container:: table-row Property dateFormat Data type strftime-conf Description Set this to change the startdate-formatting. Default .. _listing-titleWrap: listing.titleWrap """"""""""""""""" .. container:: table-row Property listing.titleWrap Data type wrap Description OBSOLETE SETTING Default OBSOLETE SETTING .. _listing-resultAtATime: listing.resultAtATime """"""""""""""""""""" .. container:: table-row Property listing.resultAtATime Data type int Description Number of galleries per page in the listing. Default 20 .. _listing-nosubcountifzero: listing.nosubcountifzero """""""""""""""""""""""" .. container:: table-row 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: listing.preview """"""""""""""" .. container:: table-row 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: listing.maxPages """""""""""""""" .. container:: table-row 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: listing.maxlevel """""""""""""""" .. container:: table-row 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: gallery.default """"""""""""""" .. container:: table-row 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: commentSplits """"""""""""" .. container:: table-row Property commentSplits Data type int+ Description Sets the limit for the number of splits for the annotation files. Default .. _commentFiletype: commentFiletype """"""""""""""" .. container:: table-row Property commentFiletype Data type string Description Set the filetype for the annotation files. Default txt .. _commentBytes: commentBytes """""""""""" .. container:: table-row 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: layout """""" .. container:: table-row 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: imageLinkWrap """"""""""""" .. container:: table-row 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: overrideImageLinkWrap """"""""""""""""""""" .. container:: table-row 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: optimizeFactor """""""""""""" .. container:: table-row 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: optimize """""""" .. container:: table-row 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: forceOptimize """"""""""""" .. container:: table-row 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: caching """"""" .. container:: table-row Property caching Data type boolean Description Enable/disable any caching done by the lz\_gallery heavycaching mechanism. Default false .. _caching-paths: caching.paths """"""""""""" .. container:: table-row Property caching.paths Data type boolean Description Enable/disable path-information caching. Only if “caching” is set to true. Default true .. _caching-galleries: caching.galleries """"""""""""""""" .. container:: table-row Property caching.galleries Data type boolean Description Enable/disable gallery-output caching. Only if “caching” is set to true. Default true .. _previous: previous """""""" .. container:: table-row 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: next """" .. container:: table-row Property next Data type cObj Description Same as above, but for the “next” link. Default .. _previous-nolink: previous\_nolink """""""""""""""" .. container:: table-row 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: next\_nolink """""""""""" .. container:: table-row Property next\_nolink Data type cObj Description Same as above, but for the “next” link. Default .. _hidedescription: hidedescription """"""""""""""" .. container:: table-row 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: qtt """ .. container:: table-row 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: CMD """ .. container:: table-row 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: \_DEFAULT\_PI\_VARS """"""""""""""""""" .. container:: table-row 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: \_LOCAL\_LANG.country.langkey """"""""""""""""""""""""""""" .. container:: table-row 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 .. ###### END~OF~TABLE ###### Otions in the template SETUP (!!): *plugin.tx\_lzgallery\_pi1.gallery.GALLERY\_OBJECT* .. ### BEGIN~OF~TABLE ### .. _1-2-3-4: 1,2,3,4... """""""""" .. container:: table-row 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: stdWrap """"""" .. container:: table-row Property stdWrap Data type stdWrap Description stdWrap around the image in this gallery. Default .. _emptyCell: emptyCell """"""""" .. container:: table-row 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: filename """""""" .. container:: table-row Property filename Data type boolean / .stdWrap Description Configuration for adding the filename to the image. Default .. _filesize: filesize """""""" .. container:: table-row 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 .. ###### END~OF~TABLE ###### 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:* .. ### BEGIN~OF~TABLE ### .. _maxwidth: maxwidth """""""" .. container:: table-row 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. Options 540,640,1024 Presets 540 .. _colrows: colrows """"""" .. container:: table-row 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!). Options 1x1,3x3,5x5 Presets 5x5 .. _rotation: rotation """""""" .. container:: table-row Property rotation Data type list / int + Description Image rotation. Options 0,45,90,135,180,225,270,315 Presets 0 .. _colors: colors """""" .. container:: table-row Property colors Data type list / int \* Description Number of colors. (Color reduction). Use integer numbers. “normal” is a special value meaning “no color reduction”. Options normal,2,4,8,16,32,64,128,256 Presets normal .. _effect: effect """""" .. container:: table-row Property effect Data type list/ \* Description Use the default options only! The value is straight passed to imagemagick, so typing-mistakes are not encouraged! Options normal,negate,enhance,dither Presets normal .. _gamma: gamma """"" .. container:: table-row Property gamma Data type list / float + Description Gamma. (Good to clear up / brighten images). Options 0.2,0.4,0.6,0.8,1,1.2,1.4,1.6,1.8,2,3,4,5,10 Presets 0 .. _clickmode: clickmode """"""""" .. container:: table-row 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). Options samewindow\_noeffect,samewindow,newwindow,samewindow\_max Presets samewindow\_noeffect .. _swirl: swirl """"" .. container:: table-row Property swirl Data type list / int Description Swirlpool effect. Integer is number of degrees. Options -620,-360,-180,-90,-45,0,45,90,180,360,620 Presets 0 .. _contrast: contrast """""""" .. container:: table-row Property contrast Data type list / int Description Increase / decrease image contrast. Options -10,-9,-8,-7,-6,-5,-4,-3,-2,-1,0,1,2,3,4,5,6,7,8,9,10 Presets 0 .. _implode: implode """"""" .. container:: table-row Property implode Data type list / int Description Implode / explode the image from the image center. Options -1000,-750,-500,-400,-300,-200,-100,-90,-80,-70,-60,-50,-40,-30,-20,-1 0,0,10, 20,30,40,50,60,70,80,90,100 Presets 0 .. _charcoal: charcoal """""""" .. container:: table-row Property charcoal Data type list / int Description Charcoal effect. Options -1,0,1,2,3,4,5,6,7,8,9,10,20,30,40,50 Presets 0 .. _mirror: mirror """""" .. container:: table-row Property mirror Data type list / \* Description Use only these options. Options normal,flip,flop,both Presets normal .. _channel: channel """"""" .. container:: table-row Property channel Data type list / \* Description Extract an color-channel from the image. Use only these options. Options all,red,green,blue,cyan,magenta,yellow Presets all .. _brightness: brightness """""""""" .. container:: table-row Property brightness Data type list / int + Description Increase the image brightness. Options 0,10,20,30,40,50,60,70,80,90,100,110,120,140,160,180,200 Presets 0 .. _saturation: saturation """""""""" .. container:: table-row Property saturation Data type list / int + Description Increase the image saturation. Options 0,10,20,30,40,50,60,70,80,90,100,110,120,140,160,180,200 Presets 0 .. _hue: hue """ .. container:: table-row Property hue Data type list / int + Description Increase the image hue. Options 0,10,20,30,40,50,60,70,80,90,100,110,120,140,160,180,200 Presets 0 .. _amplitude: amplitude """"""""" .. container:: table-row Property amplitude Data type list / int + Description Produce wave-effects, in combination with the wavelength. Options 0,1,2,3,4,6,8,10,15,25,40,60,100 Presets 0 .. _wavelength: wavelength """""""""" .. container:: table-row Property wavelength Data type list / int + Description Produce wave-effects, in combination with the amplitude. Options 0,4,8,10,20,30,40,50,60,70,80,90,100 Presets 0 .. _spread: spread """""" .. container:: table-row Property spread Data type list / int + Description Random pixel displacement by factor. Options 0,1,2,4,6,8,10,20,40,60,80,100 Presets 0 .. _solarize: solarize """""""" .. container:: table-row Property solarize Data type list / int + Description Solarization (over-lighting) effect. Options 0,10,20,30,40,50,60,70,80,90,100 Presets 0 .. ###### END~OF~TABLE ###### .. _generated: ((generated)) """"""""""""" .. _Example: 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: 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: |img-13| 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: 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: To-Do list ---------- - Stalled: Frontend uploading of images / creation of galleries ! - Stalled: Integrate watermarks. - Todo: Add “seperators” to the galleries. .. _Changelog: 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
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./\path\to/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 ! .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. :border: 0 .. :height: 593 .. :id: Afbeelding4 .. :name: Afbeelding4 .. :width: 469 .. |img-2| image:: img-2.png .. :align: left .. :border: 0 .. :height: 715 .. :id: Graphic3 .. :name: Graphic3 .. :width: 669 .. |img-3| image:: img-3.png .. :align: left .. :border: 0 .. :height: 253 .. :id: Graphic6 .. :name: Graphic6 .. :width: 607 .. |img-4| image:: img-4.png .. :align: left .. :border: 0 .. :height: 141 .. :id: Graphic4 .. :name: Graphic4 .. :width: 621 .. |img-5| image:: img-5.png .. :align: left .. :border: 0 .. :height: 240 .. :id: Graphic5 .. :name: Graphic5 .. :width: 669 .. |img-6| image:: img-6.png .. :align: left .. :border: 0 .. :height: 107 .. :id: Graphic7 .. :name: Graphic7 .. :width: 557 .. |img-7| image:: img-7.png .. :align: left .. :border: 0 .. :height: 84 .. :id: Graphic8 .. :name: Graphic8 .. :width: 627 .. |img-8| image:: img-8.png .. :align: left .. :border: 0 .. :height: 173 .. :id: Afbeelding1 .. :name: Afbeelding1 .. :width: 410 .. |img-9| image:: img-9.png .. :align: left .. :border: 0 .. :height: 113 .. :id: Afbeelding3 .. :name: Afbeelding3 .. :width: 679 .. |img-10| image:: img-10.png .. :align: left .. :border: 0 .. :height: 120 .. :id: Afbeelding2 .. :name: Afbeelding2 .. :width: 406 .. |img-11| image:: img-11.png .. :align: left .. :border: 0 .. :height: 49 .. :id: Afbeelding5 .. :name: Afbeelding5 .. :width: 483 .. |img-12| image:: img-12.png .. :align: left .. :border: 0 .. :height: 223 .. :id: Afbeelding6 .. :name: Afbeelding6 .. :width: 350 .. |img-13| image:: img-13.png .. :align: left .. :border: 0 .. :height: 108 .. :id: Afbeelding7 .. :name: Afbeelding7 .. :width: 394