Gallery How To

This component allows you to create an image gallery in two ways:

  • from an html list
  • programatically, for use in other javascript components

When created with the first mode, the list degrades gracefully when javascript is not available.

Demo

 http://js.sapo.pt/SAPO/Component/Gallery/sample/



Initial configuration

To use this component you need the following files:

<link href="http://js.sapo.pt/Assets/Images/Gallery/style.css" type="text/css" media="screen" rel="Stylesheet" />
<script type="text/javascript" src="http://js.sapo.pt/SAPO/0.1/"></script>
<script type="text/javascript" src="http://js.sapo.pt/SAPO/Dom/Event/0.1/"></script>
<script type="text/javascript" src="http://js.sapo.pt/SAPO/Dom/Css/0.1/"></script>
<script type="text/javascript" src="http://js.sapo.pt/SAPO/Utility/Dimensions/0.1/"></script>
<script type="text/javascript" src="http://js.sapo.pt/SAPO/Component/Gallery/0.1/"></script>

The stylesheet can be omitted but in that case you need to specify similar css styles to those you can find on that file, so that the behavior can work perfectly.





First mode: html list


Necessary HTML code

<div id="gallery" class="SAPOGallery">
    <a href="#" class="first">First</a>
    <a href="#" class="previous">Previous</a>
    <a href="#" class="next">Next</a>
    <a href="#" class="last">Last</a>
    <ul class="thumbs">
        <li>
            <a href="http://image.url/file_original.jpg" title="image title">
                <img src="http://image.url/file_thumbnail.jpg" alt="image title" />
            </a>
            <div class="caption">Image caption</div>
        </li>
	</ul>
</div>
  • The container div id can be specified by the user
  • The links are optional and the available links are previous/next or first/last.
  • The caption div is also optional
  • The present css classes are necessary for the component to work and can also be used for styling the component
  • The previous/next links have a disabled class when you are on the first/last image, respectively.
  • In the generated code there will be a container with a SAPOGalleryStage class for the image which is currently being shown.
  • In the generated code, there will be 2 links previous/next which show up when you hover the image, with classes prev/next and disabled when in the first/last image. These links are inside the div with the SAPOGalleryStage gallery.



Necessary JS code

new SAPO.Component.Gallery({
    container: "gallery"
});

Don't forget to put this code inside a dom ready or just at the end of the page.

Beside the container parameter, which indicates the element which contains the HTML structure necessary for the gallery, there are other additional parameters:

  • hoverControls (default: true): Activates prev/next buttons which show up when you hover the image.
  • hoverThumbs (default: false): Uses thumbnails instead of text on the hover links
  • navThumbs (default: false): Uses thumbnails on the external prev/next links.
  • pageThumbs (default: false): Defines a number of thumbs by page, for paging the visible thumbnails.
  • prevLabel (default: Anterior): Previous hover link label
  • nextLabel (default: Próxima): Next hover link label
  • prevPageLabel (default: <<): Text for the previous thumbnails page
  • nextPageLabel (default: >>): Text for the next thumbnails page
  • showList (default: true): Show the thumbnail list
  • onChange (default: false): Callback executed on each image change





Second mode: create the gallery programatically


Necessary JS code

In this mode it's necessary to specify an array list with objects for each image to be loaded.

var gal = new SAPO.Component.Gallery({
    list: [
		{
			href: "http://image.url/file_original.jpg",
			thumb: "http://image.url/file_thumbnail.jpg",
			title: "image title",
			caption: "image caption"
		}
    ]
});

After initialization, you have to use the getGallery method to access the generated markup for the gallery, and inject it into the DOM. Example:

document.body.appendChild(gal.getGallery());

All the options from the first mode are valid. There are also some extra options for this mode:

  • navLinks (default: false): Adds external navigation links Next/Previous
  • endsLinks (default: false): Adds external navigation links First/Last
  • prevLabel (default: Anterior): Label for Previous hover link or external link
  • nextLabel (default: Próxima): Label for Next hover link or external link
  • firstLabel (default: Primeira): Label for the First external link
  • lastLabel (default: Última): Label for the Last external link
  • showCaption (default: true): Show the caption





Additional methods

  • gotoPrev - Goes to the previous image
  • gotoNext - Goes to the next image