Adobe Business Catalyst Developer

  Please click our Google +1 Button if you find this helpful.

Use JavaScript Galleria Slideshow to Display an Adobe Business Catalyst Photo Gallery using jQuery

Jonathan Beacher - Thursday, October 20, 2011
View The Demo Gallery Slide Show

The demo shows one way to use our free BC-PhotoGallery plugin that connects Business Catalyst to Galleria, a wonderful and free image gallery created by Aino. Another example is on the home page of this BC site for Galen Medical Billing.

There are several ways to install Galleria in Business Catalyst:

  1. Feed images setup in the BC Photo Gallery.
  2. Insert images defined in a BC Content Holder.
  3. Create a Web App to setup the images the gallery uses.

This tutorial will first discuss how to use Galleria with a BC Photo Gallery, because some of my clients are on the BC Business Plan and do not have Web Apps available. At the end of the article we'll show how Content Holders or Web Apps can be used instead.

Using the BC Photo Gallery with Galleria

With Galleria you can turn a BC Photo Gallery into an animated slide show complete with titles over or above photos, photo descriptions, and links so clicking photos takes you to another web page. This lets you create a home page slider to promote featured content -- clicking a photo will take your visitor to an article. Galleria is also a nice way to display new products or sales points.

By linking Galleria to the Business Catalyst Photo Gallery, your client can easily change the photos and messages/links using the BC Admin -- no need to tinker with HTML code.

Our tutorial provides you with jQuery code that can read the  XML file that the BC Photo Gallery creates to define the images, headlines, photo descriptions and links that the Galleria Gallery will display.

You can change the size, position, and style of the captions and thumbnails, and display or hide the thumbnails or titles or descriptions, if you modify the included CSS file in the BC-PhotoGallery Galleria Theme we provide. Some tips are given below.

Let's get started...

Step 1: Create a Business Catalyst Photo Gallery

  1. Download Our Zip File of Galleria for BC
  2. From within the Zip file extract the Galleria folder and copy it to the root folder of your BC server using an FTP program or Dreamweaver.
  3. In Business Catalyst Admin use the File Manager or FTP or Dreamweaver to create a folder that will store your gallery images. Then upload the images into that folder. Every image in this folder will appear in the slide show, so don't put extras here.
  4. In BC Admin click Modules --> Photo Galleries --> Create New Photo Gallery
  5. In Name enter your gallery name. This doesn't appear online, only in BC Admin.
  6. In Images Folder choose the folder name you created above to hold your images.
  7. Click Next
  8. One by one highlight each photo in the left box. In the description field for each photo, you can optionally enter a title headline, a description sentence, and/or a link. Since BC provides only one description box, we have to put all these in that one box, so we separate them by use a ^ delimiter like this:
    • Your Title^A description sentence.^/link-to-page.htm
  9. Our jQuery code will split apart these items at the ^ mark. You can leave out the title, or description, or link but you must still include the ^ in place so the code knows where to delimit the info. Here are examples:
    • Your Title^^/link-to-page.htm
    • Your Title^Description sentence.
    • ^^/link-to-page.htm
  10. You can leave the Photo Gallery Description empty if you only want images and no titles, sentences or links. No ^ marks are needed.
  11. When done in right column click Generate XML File.
  12. If you add a new photo or delete a photo in the gallery folder, you must return to Generate XML File. The current XML file version tells Galleria which photos and descriptions to use.

Step 2: Install Galleria Gallery on a Web Page

To display a Galleria Gallery on the web page all you do is add one line of HTML to create a DIV to hold the slide show plus load two scripts.

How It Works: The script looks in a BC Photo Gallery folder on the server for an XML file that describes the photos and their titles/captions. It then adds new HTML for those images into your page inside a DIV where you want the slide show to appear, the loads Galleria which turns that new HTML into the gallery.

Here's how to install it on your web site...

  1. Create a blank page in Business Catalyst. In the BC editor switch to HTML View and paste in the following code. HINT: Hover the code box below and in upper right click COPY to put this code on your clipboard, then paste into BC. (This code is also included in a file within the Download Zip File above.)  Save and publish your BC page.
    
    <div id="bc-photogallery-1" style="position: relative;"></div>
    <script src="/galleria/galleria-1.2.5.js"></script>
    <script type="text/javascript">
    jQuery(document).ready(function(){
    	jQuery(function(){
    		jQuery.ajax({
    			type: "GET",
    			url: "/galleria/bc-galleria-images-1/PhotoGallery.xml", // set to path to BC photo gallery
    			dataType: "xml",
    			success: function(xml) {
    				var location = '/galleria/bc-galleria-images-1/'; // set to path to BC photo gallery
    				jQuery(xml).find('img').each(function() {
    					// step through xml file and add image info into the web page
    					var myurl = jQuery(this).attr('src');
    					var mystuff = jQuery(this).attr('alt').split("^");
    					var myinfo = "";
    					if ( mystuff.hasOwnProperty("0") ) { myinfo = myinfo + ' title="' + mystuff[0] + '"'; }
    					if ( mystuff.hasOwnProperty("1") ) { myinfo = myinfo + ' alt="' + mystuff[1] + '"'; }
    					if ( mystuff.hasOwnProperty("2") ) { myinfo = myinfo + ' longdesc="' + mystuff[2] + '"'; }
    					var myimg = '<img class="bc-gallery-image" src="'+location+''+myurl+'" '+myinfo+ '" />';
    					jQuery('#bc-photogallery-1').append(myimg); // set to your div containing galleria
    					});
    					// load Galleria slideshow theme and start the show
    					Galleria.loadTheme('/galleria/themes/bc-photogallery/galleria.bc-photogallery.js'); // set to your theme
    					jQuery('#bc-photogallery-1').galleria({ // set to your div containing galleria
    						height: 560, // set to height of slide + height of thumbnails (default 50px)
    						image_crop: true,
    						carousel: true,
    						carousel_speed: 2000,
    						autoplay: true,
    						thumbnails: true,
    						showInfo: true,
    						transition: 'fade',
    						transition_speed: 600
    						});
    			}
    		});
    	});
    }); 
    </script>
    
  2. In addition to this code, you must also have jQuery installed on your web site. You can read my article on Loading jQuery.
  3. Line 2 is the single line of HTML needed on a page to create a Galleria Gallery. Our code is looking for a DIV on the page with ID #bc-photogallery-1 and will insert the new gallery HTML into that DIV.  (Note: You can have more than one gallery on page by creating a second DIV with a different ID and providing a second script that loads different images into the second DIV.
  4. In line 27 change the height of the #bc-photogallery-1 container to the pixel height of the tallest photo in your gallery, plus add 50px. 50px is the default thumbnail height defined in /galleria/themes/bc-photogallery/galleria.bc-photogallery.css unless you change thumbnail size there. In our demo we set the height at 560 because we had images that are 510 px tall plus the 50px thumbnails.  (Note: if the height isn't defined or too small the gallery may not appear.)
  5. In line 9 change the file URL to your domain and the folder where you installed your images. Leave PhotoGallery.xml as the file name because BC always creates that file when you click Generate XML File in the BC Photo Gallery admin.
  6. You can adjust carousel_speed in line 30. Numbers are milliseconds so 4000 means display a slide for 4 seconds.
  7. If you make thumbnails: false in line 32 then they will not display, and you can remove the extra 50px from the gallery height. You can also hide thumbnails by adding a display:none in the CSS file.
  8. There are other optional parameters you can add as described in documentation on the Galleria site.

Style and Position the Gallery Titles, Slide Sizes, Etc.

The appearance of the Galleria Gallery is controlled by editing a CSS file: /galleria/themes/bc-photogallery/galleria.bc-photogallery.css

Some ideas about the items you can change to suit your design...

  • .galleria-container: change background color surrounding the image (on my demo it is set to none so transparent.).
  • .galleria-stage: this is the slide area within the .galleria-container. You can adjust margins to make the stage the same size as the container, so there is no border areas around the slides.
  • .galleria-info: this contains the title and description. The info normally displays in the top left corner so setting in CSS top:200px moves it down over the slide. You can adjust left: from 0 to move the title right, or delete left: and make it right:0 to align to right of slide. The width default is 50% of the width of the slide, adjust as needed including up to 100% if the info is displayed above or below the images.
  • .galleria-info-text: the container around the title and description - change the text background color or use a semi-transparent .PNG
  • .galleria-info-title: change the title's color or font size or font family.
  • .galleria-info-description: change the description's color or font size/family.
  • .galleria-thumbnails-container: adjust the position of the thumbnails.
  • .galleria-thumbnails .galleria-image: adjust thumbnail size. Thumbnails are automatically created by JavaScript from the full-size images.

Animating Titles/Captions

A developer is asking if the caption can be animated to slide out or down. It can by adding a little more jQuery to the script. I'll work on showing how to do that in a later revision to this article.

Using A Business Catalyst Content Holder with Galleria

In some projects we use a Business Catalyst Content Holder to define the images we want Galleria to use. This is a simpler approach to install, but requires the client to be extra careful when adding info in the content holder. The problem is BC has a friendly UI that lets you easily add a longer description and link to an image, but to add a Title your client will need to switch to HTML view in the content holder and type in some text.

For Galleria to work it needs HTML markup on the page that looks like this:


<div id="bc-photo-gallery-1">
    <img src="/images/pic1.jpg" alt="My longer description sentence." title="My title" longdesc="http://www.some-website-to-view-when-image-is-clicked.com">
    <img src="/images/pic2.jpg" alt="Another description" title="Another title" longdesc="/some-bc-page-seen-when-image-clicked.htm">
</div>

We put the <img tags inside our content holder, and on the page where we wish the Galleria Gallery to appear we'll put a BC Module tag to insert the content holder within a DIV. Here's step by step...

  1. In BC Admin in the upper right toolbar click on Admin --> Manage Content Holders.
    Create a new content holder and name it.
  2. In the Content Holder Content box use the Image button on the editor toolbar to insert an image. Continue inserting more images in the order you wish them to appear, without adding a blank space or line break after each image.
  3. To add the Title and Description, you can right click on a photo to select it and choose Properties from the popup.
  4. In the Alt Text box you enter the longer description sentence for the image.
  5. In the Long Description box you enter an optional URL link, so when the image in the slide show is clicked your user will go to another page on your site like /some-page.htm or an external website like http://www.AtlantaWebDesignGA.com
  6. To add a Title unfortunately the BC UI has no method, so close the properties box, then at bottom of Content Holder click on HTML view. Inside the IMG tag for each photo, add: Title = "My title." You could of course manually enter the Description this way as an ALT attribute, and the URL link as a LONGDESC attribute, so your end result looks like the HTML markup above.
  7. Save the content holder.
  8. On the page where you Galleria Gallery will appear, you'll add a DIV and in it use the BC Add Modules button to add module tag that will insert the HTML in the content holder into this page. When you are done your markup will look like this, with the number being your own Content Holder's ID.
    
    <div id="bc-photo-gallery-1">
    { module_contentholder,1234}
    </div>
    
  9. The next step is adding the code to make Galleria work. Download the Zip File using the button atop this article and copy the Galleria folder in the zip file to the root of your BC Server. Then on the bottom of your Gallery page before the </body you need to add a script like this:
    
    <script src="/galleria/galleria-1.2.5.js"></script>
    <script>
    jQuery(document).ready(function(){
      // load Galleria slideshow theme and start the show
    	Galleria.loadTheme('/galleria/themes/bc-photogallery/galleria.bc-photogallery.js'); // set to your theme
    	jQuery('#bc-photogallery-1').galleria({ // set to your div containing galleria
    		height: 560, // set to height of slide + height of thumbnails (default 50px)
    		image_crop: true,
    		carousel: true,
    		carousel_speed: 2000,
    		autoplay: true,
    		thumbnails: true,
    		showInfo: true,
    		transition: 'fade',
    		transition_speed: 600
    		});
    }); 
    </script>
    Galleria needs to know the width of the gallery in pixels or it will not start. It usually can determine the height automatically, although you can specify one if you wish. You can add additional parameters as described on the Galleria site on the Galleria Options Page.
  10. Remember you also need to load jQuery on your website if it is not already installed. See Loading jQuery.

Using a Business Catalyst Web App with a Galleria Gallery

If you have the Business Catalyst Pro Plan then you can use a Web App to control which slides display in your Galleria Gallery.

Your client will be entering images as new Web App Items in Modules --> Web Apps --> Add a new Web App Item. On your Galleria Gallery page, you'll insert a BC Module to list the web app items (images) within your HTML markup.

Here's how to set this up...

  1. In BC Admin click Modules --> Web Apps then click Build a New Web App
  2. Give the Web App a Name. Your users don't see this, it's just for Admin.
  3. At bottom click Next.
  4. Now on the Custom Fields screen we'll create some custom fields. We'll explain these later when we create our first web app item.
  5. On the Custom Fields screen in Field Name enter Select Image, in Field Type select Image, check the mandatory box, and click Save Field.
  6. Click New Field and for Field Name enter Copy Image URL, in Field Type select Text (String), check the mandatory box, and click Save Field.
  7. Click New Field and for Field Name enter Image Title, in Field Type select Text (String), and click Save Field.
  8. Click New Field and for Field Name enter Image Description, in Field Type select Text (String) or Text (Multi-line) if you need very long descriptions, and click Save Field.
  9. Click New Field and for Field Name enter Image Link, in Field Type select Text (String) and click Save Field. (Don't choose type Hyperlink, we need our link to be text.)
  10. In right column click Customize Web App Layout. We need to modify the List Template to output the kind of HTML that Galleria needs. Switch to HTML view and paste in this code:
    
    <img longdesc="{tag_image link}" alt="{tag_image description}" title="{tag_image title}" src="{tag_copy image url}" class="bc-gallery-image" />
    

Now we are ready to add web app items (images) to our Galleria Gallery.

  1. In BC Admin click Modules --> Web Apps and click the name of your gallery web app.
  2. Click Create a New Web App Item.
  3. In Item Name enter the image name. This will not display online, it's just for BC Admin. The reason we don't use this field for the Image Title in Galleria is you may not want a title on all images.
  4. In Template leave on Don’t' use a template.
  5. In Select Image, click on the blue Select Image link at right and navigate to your image already in a BC server folder, or upload a new image to a server folder. When done, the image URL will appear in this box. However, we cannot use this field to send an image to Galleria because when BC outputs a web app field of type image to a web page it automatically creates an IMG link that wouldn't have any parameters for an image title, image description, or image link that we wish our Galleria gallery to use. So, this is a dummy field we added simply so we'd have a Select Image link to help us navigate to find an image URL or upload a new photo. The next field is the one we'll really be using.
  6. In the next field, Copy Image URL, we want to copy the URL in the Select Image field into this field. This one is a type text, and allows us to provide the proper image link to Galleria in our web app List Layout along with the image title, description, and link info.
  7. In Image Title, enter a title to appear for this image in the slide show display. You can leave it blank if you don't want a title.
  8. In Image Description, enter an optional description to display in Galleria.
  9. In Image Link, enter an optional link that the user will go to when the slide show image is clicked. This can be to a BC web page ( /some-page.htm ), an external web site (http://www.AtlantaWebDesignGA.com) , or link to a larger blow up of the image in the gallery.
  10. At bottom left Save the web app item.

When you are done creating images as web app items, you are ready to prepare the page where you want the Galleria Gallery to appear.

In the page you'll want to create markup that looks like this where 12345 will be the ID for your web app:


<div id="bc-photo-gallery-1">
{ module_webapps,12345,a,}
 </div>

Finally, install the Galleria script as described in step 9 in the previous section, Using A Business Catalyst Content Holder with Galleria.

Comments
Post has no comments.
Post a Comment



Captcha Image

Trackback Link
http://www.atlantawebdesignga.com/BlogRetrieve.aspx?BlogID=11204&PostID=327493&A=Trackback
Trackbacks
Post has no trackbacks.