Home » Articles » Using the Gallery Snippet - Part 2

Using the Gallery Snippet - Part 2

In this part, I'll look at the other parameters used by this snippets and then take a look at the default template.

It's worth mentioning (even though you probably know) that if you don't spell the name of the parameter correctly, snippets will just ignore them. So, if you don't get the results you expect, double-check your spelling!

Starting with GalleryAlbums, here are the next set of parameters, what they do and the default(if any) value:

As you can see, most of the default settings are probably what you would expect to see - sorted by createdon date, in descending order, showing all images, etc., and they should be fairly self explanatory.

The one that tripped me up for ages was the 'prominentOnly'.
By default, GalleryAlbums will look for albums with this flag set (in the Components -> Galley manager). This can flag can be used for marking albums private (i.e. unset the prominent flag) but still have them active. Just remember that if none of your albums are marked as prominent, you won't get a whole lot back from this!

The Gallery Manager can be used to create parent albums, by right clicking on an existing album and selecting Add Album from the context menu. This gives the ability to group related albums for use in different areas of the site, for example. You might have a container of "Car" albums and another of "Buildings", and then have albums within them. Using the parent parameter allows you to select which container album to use.

The outputSeparator is a useful parameter that allows you to specify some html to use to separate the albums listed. For example, you could have <div class="clear"></div> or simply <br />. This is another one that is not listed on the official documentation page, but examination of the snippet shows it being there.

The final one for now - rowTpl - relates to the next section on the templates, but this should be familiar to you (unless you really are brand new to ModX!)

The rowTpl

The default template looks like:
<li[[+cls:notempty=``]]><a href="[[~[[*id]]? &[[+albumRequestVar]]=`[[+id]]`]]">[[+showName:notempty=`[[+name]]`]]</a></li>

As you can see, it's a list item and uses the various placeholders available to the snippet - the placeholders are listed below.

The sharp-eyed amongst you will notice that the very first placeholder [[+cls]] does not appear in the parameter list above! This is an example of where the official documentation has not kept up with the development of the snippet, I think. I am not going to complain or berate anyone for this - I can fully appreciate how busy these guys are, and this is partly why I started this series of articles!

So, to set a class for the li tag, simply use &rowCls=`your-class-name` and then style in your CSS file as normal

Moving along the rest of the tag, we have the anchor. Notice the format of the href. This use of
[[~[[ is very common and you'll see more if it in these articles and in other snippets in ModX. The *id should be familiar as the id of the current resource - i.e. the link will be to the current page.

Next is +albumRequestVar. This is a parameter that the snippets use to pass the id of the gallery between themselves. I'll come back to this in a later article when I look at passing parameters to different resources.

The next bit is a little clever use of a parameter in this case +showName. It basically says that if &showName is not empty then display the name of the album. Setting the &showName parameter to `0` will cause all album names to be displayed as 0 (not sure if this is by design, but happens according to my testing). If the parameter is blank, or any other value other than 0, then the album name is displayed.

To override the default display, it is simply a matter of creating your own chunk, and then setting the &rowTpl parameter to the name of that chunk.

If you have created the sample from the Part 1 article, you should have a working page, so go ahead and create a new chunk called "my-album-row-tpl" and enter the following:

<li[[+cls:notempty=``]]>
<a href="[[~[[*id]]? &[[+albumRequestVar]]=`[[+id]]`]]">
<img src="[[+image]]" alt=[[+description]]></a> </li>
<h4>[[+name]]</h4>

And then add
&rowTpl=`my-album-row-tpl`
to the GalleryAlbums call:
[[!GalleryAlbums? &toPlaceholder=`AlbumList` &rowTpl=`my-album-row-tpl`]]

You should now see your galleries listed, with a thumbnail image and the name of the gallery underneath. OK, it's not probably not pretty because there is no CSS styling in there, but hopefully you can see how this works.

Thumbnail and Album Covers

This last bit covers the parameters and properties for overriding the default handling of how the thumbnails are displayed, and the album cover as well.

The parameters are:

The first two tell the snippet what to do in order to get a cover for the album - i.e. which field to use and how to sort that field. Might be nice in future releases to specify an id number to use as a cover.... ;-)

The thumbWidth and thumbHeight, again should be self-explanatory. They control the size of the thumbnail image. No, really they do!

The thumbZoomCrop is either 0 or 1, 0 being off and 1 being on. This will auto crop the largest dimension to allow the image to fit the smallest dimension i.e. it will make the image fit the available space

The thumbQuality is a percentage setting for the quality of the cover image (JPG's)

thumbFar and thumbProperties are phpthumb parameters and as yet, I have not investigated these and their functionality. When I do, I will write up an article for them as well!

So, we can create a snippet call with a number of parameters set as follows:

[[!GalleryAlbums? &toPlaceholder=`AlbumList` &rowTpl=`my-album-row-tpl` &albumCoverSort=`createdon` &albumCoverSortDir=`DESC` &thumbWidth=`50` &thumbHeight=`50` &thumbQuality=`100` &outputSeparator=`<br />`]]

As an uncached call, get all albums, put the results in a placeholder 'AlbumList', use the template 'my-album-row-tpl' to display the results, use the 'createdon' field and sort DESCENDING to find the cover image to use, display the thumbnails as 50x50 images at 100% quality, and put a break after each gallery

Placeholders

The other placeholders available are:

What usually stumps people (i.e. me!) is HOW and WHERE to use these placeholders. The short answer is within the template e.g. in the my-album-row-tpl you created earlier.

Why there? Well, that template is called for every album that is pulled from the gallery, one after the other. The snippet builds the html for the resource as it loops through the albums in the gallery. Once the loop is finished, the placeholders are no longer available, so you can't try and use them in the resource content, for example, they just don't exist.

You can see this working by changing the my-album-row-template, and try adding a placeholder to the test resource in the previous article.

So, that's it for GalleryAlbums. Hopefully, you can see how this works. Remember that GalleryAlbums on its own will just pull back the album details - there will be no actual images as yet (just the album thumbnails) - that needs the Gallery snippet, which will be the subject of Part 3!