Galleria Plugin
The Galleria Plugin file contains functions which assist in generating JavaScript code for Galleria, a JavaScript image gallery framework made by Aino http://galleria.aino.se/. The plugin comes in two flavors. In it's first form the plugin generates the required JSON array (based on a static meta data text file) and Galleria initialization code, writes the data to disk and returns either a reference to the JavaScript file or the data itself to be inserted in a view file. In it's second form the plugin generates the JSON array based on dynamically created meta data, adds initialization code and returns the JavaScript code enclosed in "script" tags.
The Galleria version currently supported is 1.2.5.
Requirements
- JQuery JavaScript file or a reference to the Google Apis CDN (recommended).
- The Galleria Javascript file.
- Galleria theme files (JavaScript and CSS).
- A folder containing at least your gallery images and (in case you use static image meta data files) a text file (the meta data file) containing an image file name, optional captions (title and description), an optional image link, optional layer data and an optional refernce to the original IMG element for each image you provide. Note: This folder must be writable. See Using Image Data http://galleria.aino.se/docs/1.2/references/data/ for further information regarding image data properties.
- Optionally you can include in your images folder a folder for thumbnails called "thumb" and a folder for fullscreen mode images called "big".
Images Folder Structure
/myImagesFolder
myGalleriaCaptions.txt
myImage1.png
myImage2.png
myImage3.png
/big
myImage1.png
myImage2.png
myImage3.png
/thumb
myImage1.png
myImage2.png
myImage3.png
The file name for your image data properties ("myGalleriaCaptions.txt" in this case) is arbitrary but the "txt" suffix is mandatory. This file is only needed if you don't provide the data programmatically. If you want to provide separate images for thumbnails and fullscreen mode (recommended) include them in a folder called "thumb" and "big" respectively.
Note: This folder must be writable. Use identical file names for standard, thumbnail and fullscreen versions of your images.
Galleria Framework Modification
There are minor modifications necessary in order for the plugin to work properly.
- Remove the suffix of the css property in the JavaScript file of your theme, for example replace css:"galleria.classic.css" with css:"galleria.classic".
- Adjust all URLs in the CSS file of your Galleria theme according to where you store theme related images. Remember: Paths in a CSS file are always relative to the CSS file itself. Alternatively you may use full URLs.
The Image Data File
The image data file you have to provide if you use the plugin in it's first form is a simple text file containing a list of tab delimited Galleria image properties and has the following form for each line:
image file name<tab>image title<tab>image description<tab>image link URL<tab>image HTML layer<tab>IMG element reference
Keep in mind that the only mandatory property is the image file name. See Using Image Data http://galleria.aino.se/docs/1.2/references/data/ for further information regarding image data properties.
Note: Using static meta data gallery images are sorted alphabetically.
Dynamically Generated Image Data
In case you don't want use static image meta data saved on disk you may create the meta data programmatically for example from data stored in a database. Dynamically generated meta data has the same form as the static image data described above with one exception: The first item in each line of the list is the image file name prepended with a root relative path.
Note: Using dynamically created meta data gallery images are sorted according to the order determined in your meta data.
Loading this Plugin
This plugin is loaded using the following code:
rigLoadPlugin "galleria"
The functions:
rigGalleriaData(tGalleryPath, tOptions, tContainerID, tDataVariableName, tCacheBuster, tReplaceDataFile, tReturnReference)
- The first parameter is a root relative path to the folder containing the gallery images and the meta data file.
- The second parameter is optional and is an array of pairs of Galleria option names and Galleria option values. See List of Options http://galleria.aino.se/docs/1.2/options/. The default key value pair is "height" and 420.
- The optional third parameter is the ID of the <div> tag containing the gallery. The default ID is "galleria".
- The optional fourth parameter is the name of the JSON array data variable needed by Galleria. The default name is "galleriaData".
- The optional fifth parameter is a boolean which determines whether your gallery should be excluded from cache busting in case use_cacheBusters in system/application/config/config.lc is set to TRUE. The default value is TRUE.
- The optional sixth parameter is a boolean which determines whether the generated JavaScript file should be replaced every time the function is called. The default value is FALSE.
- The optional seventh parameter is a boolean which determines whether the plugin should return a file reference or the Galleria data itself. The default value is TRUE for returning a file reference. Setting this parameter to FALSE comes in handy for example if you are dealing with Ajax requests to dynamically change gallery content by sending just the Galleria data to the browser.
This function generates the required JSON array based on a meta data text file, adds Galleria initialization code, writes the data to disk and returns either a file reference or the data itself.
rigDynamicGalleriaData(tMetaData, tOptions, tContainerID, tDataVariableName, tCacheBuster)
- The first parameter is the dynamically generated meta data.
- The second parameter is optional and is an array of pairs of Galleria option names and Galleria option values. See List of Options http://galleria.aino.se/docs/1.2/options/. The default key value pair is "height" and 420.
- The optional third parameter is the ID of the <div> tag containing the gallery. The default ID is "galleria".
- The optional fourth parameter is the name of the JSON array data variable needed by Galleria. The default name is "galleriaData".
- The optional fifth parameter is a boolean which determines whether your gallery should be excluded from cache busting in case use_cacheBusters in system/application/config/config.lc is set to TRUE. The default value is TRUE.
This function generates the required JSON array based on dynamically created meta data, adds initialization code and returns the JavaScript code enclosed in "script" tags.
Note: If you place more than one gallery on a page you need to include the third and fourth parameter as you need different IDs and variable names for each gallery. This applies to both functions.
Note: Enclose literal Galleria option values with single quotes and double quotes like: put "'galleriaIn'" into tOptions["easing"]. This applies to both functions.
Gallery Example (Using Static Meta Data)
For this example put your gallery images and your image properties file in assets/img/galleriaPics, this path is arbitrary for your own projects though. Download the Galleria framework. Put the file galleria-1.2.5.min.js in assets/js. Assuming you use the Galleria classic theme put a modified version (see above) of galleria.classic.min.js in assets/js. Put a modified version (see above) of galleria.classic.css in assets/css. Create the following view file and let's call it galleriaView.lc:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>[[gData["pageTitle"] ]]</title>
<? return rigCssAsset("galleria.classic.css") ?>
</head>
<body>
<div class="content">
<div id="galleria"></div>
</div>
<? return rigJsAsset("jsGoogleapis-jquery-1.7.1") ?>
<? return rigJsAsset("galleria-1.2.5.min.js") ?>
<? return rigJsAsset("galleria.classic.min.js") ?>
<? return rigGalleriaData("assets/img/galleriaPics") ?>
</body>
</html>
Note: rigGalleriaData("assets/img/galleriaPics") returns a reference to a Galleria JSON array including Galleria initialization code, or false on failure.
Now create a controller called galleria.lc:
<?rev
global gControllerHandlers, gData
put "galleria,index" into gControllerHandlers
command galleria
rigLoadHelper "asset"
rigLoadPlugin "galleria"
end galleria
command index
# SET PAGE TITLE
put "Galleria Plugin Example" into gData["pageTitle"]
# LOAD THE VIEW FILE
get rigLoadView("galleriaView")
end index
--| END OF galleria.lc
--| Location: ./system/application/controllers/galleria.lc
----------------------------------------------------------------------
Try it!
To view your gallery, visit your site using a URL similar to this one:
example.com/index.lc/galleria/