Symphony.

A new ensemble, “SimpleViewer” is now available for download. Comments and feedback can be left here but if you discover any issues, please post it on the issue tracker.

Tutorial: Integrate SimpleViewer with Symphony

In this tutorial I will explain how the free version of Simpleviewer by Airtight Inc. can be integrated with Symphony CMS. This enables you administrate all your photo galleries using the administrative back-end of Symphony. I will not go much into detail into all XSLT but I will try and answer your questions about this.

• Download the ensemble at http://github.com/carsten/sym-simpleviewer-integrated
• See a demo at http://www.carsten.in/tutorials/simpleviewer/gallery/

Before you start

• Download Simpleviewer at http://www.simpleviewer.net
• Download the latest version of Symphony at http://www.getsymphony.com with the default extensions.
• Download the Color Chooser Field extension at http://getsymphony.com/downloads/redirect/21927/grab/
• Download the Unique Upload Field extension at http://getsymphony.com/downloads/redirect/20653/grab/

Step 1. Creating necessary files and directories

Install Symphony with its default extensions (make sure you have the Select Box Link field, it is necessary for this tutorial). Use your FTP client to open Symphony’s /workspace directory and create a new directory called “simpleviewer”. Open the Simpleviewer.zip file you downloaded and upload viewer.swf and swfobject.js to your newly created directory. Now, go to your /workspace/images directory and create a new directory called “gallery”.

Extract the Color Chooser Field extension to your extensions directory and make sure that you rename the directory to “color_chooser_field” or it will not show up in your extensions overview. Extract the Unique File Upload Field extension to your extensions directory and make sure that you rename the directory to “uniqueuploadfield” for the same reason. Go to your extensions overview and enable both extensions.

Step 2. Creating Sections

SimpleViewer can be customized by setting several options. We want to make sure that they are configurable through the Symphony Interface for each Gallery. The documentation of all the options of the free version are found at http://www.simpleviewer.net/simpleviewer/options.html.

Create a section called “Simpleviewer Gallery” and create the following fields:

• Text Input field “Title”, make it a required field
• Text Input field “maxImageWidth”, use number validation rule
• Text Input field “maxImageHeight”, use number validation rule
• Text Input field “frameWidth”, use number validation rule
• Text Input field “stagePadding”, use number validation rule
• Text Input field “navPadding”, use number validation rule
• Text Input field “thumbnailColumns”, use number validation rule
• Text Input field “thumbnailRows”, use number validation rule
• Text Input field “firstImageIndex”, use number validation rule
• Text Input field “Flash Object Width”
• Text Input field “Flash Object Height”

For all these fields, choose Sidebar placement

• Color Chooser field “textColor”
• Color Chooser field “frameColor”
• Color Chooser field “preloaderColor”
• Color Chooser field “Background Color”
• Unique Upload field “backgroundImagePath”, select /workspace/images/gallery, use validation rule /.(?:gif|jpe?g|png|swf)$/i
• Select Box field “navPosition”, static options “left, right, top, bottom”
• Select Box field “vAlign”, static options “center, top, bottom”
• Select Box field “hAlign”, static options “center, left, right”
• Select Box field “enableRightClickOpen”, static options “true, false”
• Text Input field “langOpenImage”
• Text Input field “langAbout”
• Checkbox field “Publish”

Note that you can use pixels, em and percentages for Flash Object Width and Flash Object Height, therefore you should not use the number validation rule. Also, if you want your Flash Object to have a transparent background you can choose to make “Background Color” a Text Input field instead of a Color Chooser field (“transparent” is also a valid value).

Create a section called “Simpleviewer Images and create the following fields:

• Text Input field “Title”
• Unique Upload field “Image File”, select /workspace/images/gallery, use validation rule /.(?:gif|jpe?g|png|swf)$/i
• Select Box Link field “Gallery”, select option “title” from “Simpleviewer Gallery”, limit to the 99999 most entries

Step 3. Creating Data Sources

I don’t like to retrieve data that I am not going to use, therefore I make three data sources.

Create a Data Source called Simpleviewer Galleries with the following details:

• Source: Simpleviewer Gallery
• Filter Simpleviewer Gallery by Publish, value “yes”
• Show a maximum of 99999 results
• Use field “System ID” for Parameter Output
• Included Elements: title, publish

Create a Data Source called Simpleviewer Gallery Details with the following details:

• Source: Simpleviewer Gallery
• Filter Simpleviewer Gallery by System ID, value {$simpleviewer-gallery-id}
• Show a maximum of 1 results
• Include all elements except pagination (publish is also not necessary but you might want to see unpublished galleries anyway)

Create a Data Source called Simpleviewer Images with the following details:

• Source: Simpleviewer Images
• Filter Simpleviewer Images by Gallery, value {$simpleviewer-gallery-id}
• Show a maximum of 99999 results
• Included Elements: title, image-file

Step 4. Creating Pages

You need to create at least one page to display your Simpleviewer galleries and one page to generate the Simpleviewer XML file.

Create a Page called Gallery with the following details:

• URL handle: gallery
• URL parameters: simpleviewer-gallery-id
• Include Event “Login Info”
• Include Data Sources: Navigation, Simpleviewer Galleries, Simpleviewer Gallery Details

Create a Page called Gallery XML with the following details:

• URL handle: xml
• Parent page: /gallery
• URL parameters: simpleviewer-gallery-id
• Page type: hidden, XML
• Include Data Sources: Simpleviewer Gallery Details, Simpleviewer Images

Step 5. Write XSLT

We’ll need to write XSLT to display the Simpleviewer galleries and to generate the Simpleviewer XML file. In the setup of this tutorial I assume that more galleries are required. However, if only one gallery is published this gallery will be shown by default.

Open master.xsl and put the following line just below the closing head tag: <script type="text/javascript" src="{$workspace}/simpleviewer/swfobject.js"></script>

We want to create an XML file that outputs all allowed configuration options of Simpleviewer and includes the appropriate images. Use the code provided at http://gist.github.com/223768 to replace the existing code of gallery_xml.xsl

Now, open gallery.xsl and use the code provided at http://gist.github.com/223768 to replace the existing code. This code will generate a list of all your galleries and if one is chosen will display the Simpleviewer gallery using the values you provided in your Simpleviewer Gallery and Simpleviewer Image content entries.

Step 6. Create your first gallery

Go to Simpleviewer Gallery and create a new entry. Only Title is required, but to display the gallery be sure to check the Publish checkbox. In the ensemble (see demo at ) I use the following values for the following fields with the horizontal gallery and (vertical gallery):

• maxImageWidth: 800 (400)
• maxImageHeight: 480 (700)
• frameWidth: 10 (10)
• stagePadding: 10 (5)
• navPadding: 5 (50)
• thumbnailColumns: 6 (2)
• thumbnailRows: 1 (2)
• firstImageIndex: 0 (2)
• Flash Object Height: 100% (90%)
• Flash Object Width: 100%
• textColor: #000000 (#2e2e2e)
• frameColor: #000000 (#8a8a8a)
• preloaderColor: #000000 (#8a8a8a)
• Background Color: #FFFFFF (#FFFFFF)
• navPosition: top (left)
• vAlign: top
• hAlign: center

Final Note

There are some default values defined in the code for gallery.xsl that you can find at lines 46, 52, 58, and 64. These are only used when the values are left empty in the respective Simpleviewer Gallery content entry. Change them if you want. You can find the default values for all config options at http://www.simpleviewer.net/simpleviewer/options.html.

If you have any questions about the code or suggestions for improvement, please let me know. Also, if you use this code it would be nice to see some examples of your Simpleviewer galleries and their configuration values, so feel free to post them!

Awesome work Carsten! Thanks for this.

Beautiful work Carsten! This is a wonderful tutorial!

You used the Color Chooser Field! :-))

I was going to use the field for a photographers’ portfolio site and use SimpleViewer, but haven’t gotten to it yet. A nice way to implement it. You just saved me some work. Thanks!

Hello Carsten, is possible integrate Gallery in article.xsl? Thanks

demo doesn’t work here - http://www.carsten.in/tutorials/simpleviewer/gallery/

error - Line 15 – No suitable XSLT processor was found.

transparent background doesn't work, Background becomes green when i type 'transparent' in Background Color text input field