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: O5 Gallery Plugin¶
Created: | 2010-02-18T17:33:18 |
---|---|
Changed by: | Olivier |
Changed: | 2011-05-23T17:50:56.040000000 |
Classification: | Opus5 Gallery Plugin |
Description: | The keywords help with categorizing and tagging of the manuals. You can combine two or more keywords and add additional keywords yourself. Please use at least one keyword from both lists. If your manual is NOT in english, see next tab "language" ---- forEditors (use this for editors / german "Redakteure") forAdmins (use this for Administrators) forDevelopers (use this for Developers) forBeginners (manuals covering TYPO3 basics) forIntermediates (manuals going into more depth) forAdvanced (covering the most advanced TYPO3 topics) see more: http://wiki.typo3.org/doc_template#tags ---- |
Keywords: | forEditors, forDevelopers |
Author: | Opus5 (by Olivier PEYRUSSE) |
Email: | soporte@opus5.info |
Info 4: | |
Language: | en |
EXT: O5 Gallery Plugin - Opus5 Gallery Plugin
EXT: O5 Gallery Plugin¶
Extension Key: Opus5 Gallery Plugin
Language: en
Keywords: forEditors, forDevelopers
Copyright 2000-2011, Opus5 (by Olivier PEYRUSSE), <soporte@opus5.info>
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.org
Table of Contents¶
`Introduction 3 <#__RefHeading__4326_929642545>`_
`Installation 6 <#__RefHeading__3531_761925617>`_
`Users manual 7 <#__RefHeading__4334_929642545>`_
Configure the display of the extension 8
`Configuration 11 <#__RefHeading__710_1138821903>`_
`Frequently Asked Questions 14 <#__RefHeading__6716_1180458822>`_
No question has been posted yet. 14
`Known problems 15 <#__RefHeading__4362_929642545>`_
`To-Do list 16 <#__RefHeading__4364_929642545>`_
`Change Log 17 <#__RefHeading__4366_929642545>`_
`Appendix A – Improvements from Galleriffic 18 <#__RefHeading__3395_761925617>`_
Introduction¶
What does it do?¶
This extension is a FE plugin to create easily a gallery in a Typo3 web site. The main feature of this gallery is its flexibility. Every element of the gallery appears in its templates, very small pieces of code are generated in the source code. The gallery mainly uses code structure defined in templates.
This extension makes as a TYPO3 plugin the gallery named Gallerific, created by Trent Foley ( http://www.twospy.com/galleriffic/ ). Some corrections have been made to solve bugs, these are described in the section Improvements from Galleriffic.
Screenshots¶
An example of the use of the gallery: we select the two folders where the plugins will find the thumbnails and the images.
The gallery is rendered with this images.
Illustration 1: Screenshot form [http://www.twospy.com/galleriffic/example-5.htm]
Illustration 2: Screenshot from [http://www.twospy.com/galleriffic/example-2.html]
Questions?¶
If you have any questions about this extension, please, contact us at the following address: soporte@opus5.info.
Keeping the developer happy¶
If you like this extension, do not hesitate to rate it. Go the Extension Repository, search for this extension, click on its title to go to the details view, then click on the “Ratings” tab and vote (you need to be logged in). Every new vote keeps the developer ticking. So just do it!
You may also take a step back and reflect about the beauty of sharing. Think about how much you are benefiting and how much yourself is giving back to the community.
Installation¶
There is nothing special to do to install this extension. Dowload it from the Extension Repository and click on the button Install.
After installation, the static TypoScript template provided by the extension should be added to the site's template.
Configuration¶
There's a single configuration option available after installing the extension:
Include jQuery : check this box to include with the plugin jQuery. The plugin is using this library, but it is often the case in many websites. To avoid conflicts, this let you download by yourself a version of jQuery. Else, the plugin can provide you the version 1.5.2min. Versions of jQuery from 1.3.2 are functional.
Users manual¶
If you have never used a Display Controller before, please refer to the tutorial further down in this manual.
Create the gallery element¶
To create a gallery, go to the page and insert a General Plugin.
Then, go to the tab Plugin and choose Gallery.
Then, select a custom template and a custom CSS file for your gallery. If you want to use the default template and style, go directly to the tab Content of the plugin flexform.
Add content to the gallery¶
Add content using folders¶
The easiest way to create the gallery is to specify two folders, one for thumbnails and one for images. Then, the plugin will use all images inside to create the gallery.
To do so, click on the folder icon of the Images Folder field, select the folder containing the images. Do the same with the Thumbnails Folder field.
The corresponding image and thumbnail must have the same name in order the plugin to be able to work.
You can enable the checkbox to sort your gallery by the name of your files. Otherwise, the images will be displayed by the internal order of the thumbnails folder.
Add content using Typoscript¶
Instead of using folders ,you can manually define a matrix of images to be displayed. Then, the order of display will be the order of the matrix.
To do so, go to the section Add your own Typoscript .
As images matrices are defined by Typoscript, any script that will be included in the page holding the plugin can contain definitions of matrices. Using the checkbox “Use all gallery elements defined in Typoscript”, you can use all elements from these Typoscript files (checked) or only elements defined in the tab Typoscript (unchecked).
Configure the display of the extension¶
This panel lets you configure the behavior of the gallery.
As it says, the number of thumbnails to show will be the number of elements shown in each page of the pagination.
Enabling top or/and bottom pagers displays pagination items for navigation. These items consisting in a number for each page, the parameter “Maximum number of pages shown in the pager” specifies the count of numbers that will be shown.Default configuration is 5, minimum is 3. In the pager, 3 elements are always shown: a link to the first page, link to the last page, and an item for the current page.
When the user goes to another image, the shown image fades out and the new one fades in. This duration of the transition can be configured through the last input box. The duration is in milliseconds, default is 1000ms (1s).
Example :
In this example, we only show 2 thumbnails (green box) and we activate the two pagers (red boxes). Therefore, 4 links to pages should be shown. Because we configure only 3 pages to show (blue box), only 3 links are visible (1, 2, 4) and the resting pages are hidden by ellipsis (…).
Add your own Typoscript¶
In this tab, you can add a custom script to the plugin instance.
The main purpose of this element is to define a matrix of images for the galley. The syntax of this matrix is the following:
images {name_of_the_image {imageUrl = [define the URL where to find the image to show]thumbUrl = [define the URL where to find the thumbnail of the image]downloadUrl = [define the URL where to find an downloadable image]title = [enter a small text that will be used as a title for the image]description = [enter a description for the image]}}
You can also use this field to enter classical Typoscript, such as new language elements, or every configurable element of the plugin.
To see all configurable elements, go to Configuration .
Configuration¶
TypoScript¶
templateFile¶
Property
templateFile
Data type
string
Description
Configuration of the path to the template file to create the gallery view
Default
EXT:o5_gallery/res/pi1_template.html
cssFile¶
Property
cssFile
Data type
string
Description
Use this configuration to specify a CSS file to load with the element
Default
typo3conf/ext/o5_gallery/res/pi1.css
additionalScripts¶
Property
additionalScripts
Data type
list of strings separated with comma
Description
Scripts to be included with the gallery plugin. These scripts can for example create new animations for the gallery.
Default
thumbnailsFolder¶
Property
thumbnailsFolder
Data type
string
Description
Configure the path to the folder containing the images in full size
Default
imagesFolder¶
Property
imagesFolder
Data type
string
Description
Configure the path to the folder containing the thumbnails
Default
orderFilesByName¶
Property
orderFilesByName
Data type
boolean
Description
Use this configuration to sort the thumbnails by the name of the files (ascending order)
Default
0
thumbsByPage¶
Property
thumbsByPage
Data type
integer
Description
Configure the number of thumbnails to show in each page
Default
5
maxPages¶
Property
maxPages
Data type
integer
Description
Number of pages to show in the pager
Default
5
topPager¶
Property
topPager
Data type
boolean
Description
Use the configuration to show the pager, in top of the list of thumbnails
Default
0
bottomPager¶
Property
bottomPager
Data type
boolean
Description
Use the configuration to show the pager, in bottom of the list of thumbnails
Default
0
transitionDuration¶
Property
transitionDuration
Data type
integer
Description
Use this configuration to set the duration of the transition, while changing from one image to the next. This time is set in milliseconds.
Default
1000
images¶
Property
images
Data type
-> imagesMatrix
Description
Configure the images to show in the gallery
Default
[tsref:plugin.tx_o5_gallery_pi1]
-> imagesMatrix¶
The images matrix is made of names, for each image, each name being the key of a configuration array.
imageUrl¶
Property
imageUrl
Data type
string
Description
Configure the URL to the full size image
Default
thumbUrl¶
Property
thumbUrl
Data type
string
Description
Configure the URL to the thumbnail image
Default
downloadUrl¶
Property
downloadUrl
Data type
string
Description
Configure the URL to an image downloadable for the user. If not defined, the gallery will use the URL to the image.
Default
title¶
Property
title
Data type
string
Description
Configure a title for the image
Default
description¶
Property
description
Data type
string
Description
Configure a text describing the image
Default
[tsref:plugin.tx_o5_gallery_pi1.images]
Templates¶
There are few elements composing the template but some requirements for creating brand new templates.
Architecture and Requirements¶
The gallery is made of one <div> element containing every element. This <div> must have a specified Id, so that multiple gallery plugins can be included in a single page. This Id is one of the markers of the plugin (“gallery-###GALLERY_ID###") and will be described later. It is required by the Javascript to identify the gallery and work correctly.Additionally, the wrapping <div> can have a specific class, “gallery” in the default template, to style quickly all gallery plugin items, the id tag allowing a case-by-case style.
The gallery is basically compound of 5 elements:
A container for the image to show, this container must have the class “ slideshow ”;
A container for the control buttons (Play & Pause, Next | Previous, …), this container must have the class “ controls ”;
A container for the captions of images, this container must have the class “ caption-container ”;
A container for the loading image, this container must have the class “ loader ”;
A container for the thumbnail images (this is the most important component), this container must be a <div> element with class “ thumbs ”. We will detail this container deeper above.
Additional components can be:
A div with class “ photo-index ”, used to display the index of the image shown (e.g. 7/9).
Linking <a> elements with class “ prev ” and “ next ” for pagination navigation. These elements can be insert in the thumbnails container (<div class=”thumbs”>...</div>) to take advantages of the default scripts.
Thumbnail container
This container must be a <div> element, with class tag set to “ thumbs ”.
Inside this element, an unordered list <ul> helds <li> elements, one for each thumbnail. <li> elements must respect the following structure:
<li>
<a class="thumb">...</a>
<div class="caption">...</div>
</li>
The <a> tag with class “ thumb ” will be used to get the URL of the corresponding image.The <div> element with class “ caption ” will contain all information that will be returned directly as the caption of the image. This can hold every type of information, such as links, text, ...
Markers¶
Loops
There are only two loops in the gallery plugin template:
- ###GALLERY### , containing the whole gallery plugin code;
- ###THUMBNAIL_ITEM### , containing each thumb content.
Global markers
- ###GALLERY_ID### : the id of the gallery plugin element, this is the uid of the element in the table tt_content
- ###NO_JAVASCRIPT_TEXT### : a text to show if javascript is not activated
- ###PPREVIOUS_PAGE### : title for a link to the previous page in the thumbnail pagination
- ###NEXT_PAGE### : title for a link to the next page in the thumbnail pagination
Thumbnail markers
- ###IMAGE_URL### : Complete URL to the image for the gallery
- ###THUMB_URL### : Complete URL to the thumb image
- ###DOWNLOAD_URL### : complete URL to a downloadable image
- ###LABEL_DOWNLOAD_IMAGE### : text for the link to the downloadale image. In the images matrix , it is the content passed as downloadUrl . For a gallery generated from folders content, this is the URL of the image.
- ###IMAGE_TITLE### : title for the image. In the images matrix, it is the content passed as title . For a gallery generated from folders content, this is the name of the file.
- ###IMAGE_DESCRIPTION### : description for the image. In the images matrix, it is the content passed as description . For a gallery generated from folders content, this is the name of the file.
Summary¶
Schema of the template
<!-- ###GALLERY### [begin] -->
<div class="gallery" id="gallery-###GALLERY_ID###">
<div class="controls"></div>
<div class="slideshow"></div>
<div class="caption-container"></div>
<div class="photo-index"></div> (Optional)
<div class="thumbs">
<a class="prev"></a> (Optional)
<ul class="thumbs">
<!-- ###THUMBNAIL_ITEM### [begin] -->
<li>
<a class="thumb"></a>
<div class="caption"></div>
</li>
<!-- ###THUMBNAIL_ITEM### [end] -->
</ul>
<a class="next"></a> (Optional)
</div>
</div>
<!-- ###GALLERY### [end] →
Reserved keywords
The following keywords are used by the gallery plugin to its own working. Be careful if you decide to use it by yourself.
.slideshow, .controls, .caption-container, .loader, .thumbs, .thumb, .photo-index, .prev, .next, .left, .right, .caption, .ss-controls, .nav-controls, .current, .previous, .image-wrapper, .advanced-link, .image-caption, .top, .bottom, .pagination, .ellipsis, .play, .pause
Frequently Asked Questions¶
No question has been posted yet.
Known problems¶
To load the first image, the plugin uses JavaScript Image object and its method onload. Under Opera, according to forums, for versions between 9.x.x to 11.10 (excluded), this method is not implemented. Then, a message is shown to avoid a empty box. After the first click, images are loaded correctly.
Under Internet Explorer, the fades of transitions don't work correctly.
Please, feel free to report any problem to the following mail address: soporte@opus5.info
To-Do list¶
The elements of the to-do list are sorted from the most likeable to happen to the least, that are just ideas of improvements.
- Enable the opacity animations for Internet Explorer;
- Define a folder for downloable images for folders generated galleries;
- Implement new options choices in the flexform to enable every option of Galleriffic;
- Add new sorting methods and allow ascending and descending sorts;
- Change the gallery working to create a multimedia gallery, containing images, video, flash, … content
This is still a small project so no release dates have been planed.
If you have any suggestion about improvements, feel free to share them with us by sending a mail to: soporte@opus5.info
Appendix A – Improvements from Galleriffic¶
Corrections have been done to galleriffic-2.0. These corrections are described here to the knowledge of old users of galleriffic and developers wanting to update the plugin to a new version of galleriffic.
Multiple images while clicking on the main image¶
Clicking on the main image of the gallery, the same image was duplicated and placed below the container.
The code was using jQuery::append() to insert the new image content. This was replaced by jQuery::html(). To be consistent with this change for the image container, we also change it for the caption container.
Duplicate thumb while changing the page¶
Before, while clicking on an arrow to change the page, by going to the thumb aside with the arrow, this thumb was duplicated in the new paged shown. This was a result of the basic configuration, that changes the opacity not of the images but of the container of the image. So, by going with the pointer to the thumb aside, we activate the hover status, so the opacity change for this element was canceled.
To correct this, we add the class “selected” to the image selected, and we change the elements for Opacityrollover object to the images themselves and not their containers.
18