Integrating a Template into MODX part 3

What is Gallery?

Gallery is a dynamic Gallery Extra for MODx Revolution. It allows you to quickly and easily put up galleries of images, sort them, tag them, and display them in a myriad of ways in the front-end of your site.

Gallery comes packaged with 3 snippets - one called "Gallery", which displays a gallery from either an Album, a Tag, or both; a snippet called "GalleryAlbums", which displays a list of Albums; and a snippet called "GalleryItem", which displays a single Gallery Item.

For more info about Gallery and it s Snippets please refer to the Official Gallery Documentation.

Creating an Album with the Gallery extra.

Hover over Components in the Main Navigation and click on Gallery this will take you to the Gallery Create Page.

Once in the Gallery Create Page click on Create Album, in the Create Album Pop-Up window insert a Name for your gallery, a Description and make sure you check mark Active (otherwise this Album won t be accessible) then click Save.

You will see our Album has been created now let s get some images in it, Right Click on your Album and Click on Update Album

Gallery provides you with 4 different ways to upload images into Albums, there s Upload Item which allows you to upload images one by one and insert a Name, Description, Tag and URL for each image if needed. There s also Multi-Upload which uploads multiples files at once and allows you to Tag them. Batch Upload which allows you to upload images from a directory on your computer and Tag them and Zip upload which allows you to upload a zip file with all your images, Gallery then extracts them and inserts them into the Album and also provides the option to tag them.

Since we only have 3 images we are going to use the Multi-Upload option, Click on Multi-Upload then Click on Upload Files, browse to the directory where our template images are stored and select the 3 images for the Homepage Slider and Click Done. Once the images are uploaded into our Album you can see a preview of them in the Album Browser

The next section will cover how to create a Gallery Call in our template to retrieve the images in our album and create a Gallery Template (tpl) for our Image Slider.

Creating the Gallery Call

Gallery works similar to Wayfinder you have a Snippet call, pass some parameters and use a template Chunk (tpl) to style what each item should look like.

Go to the Elements Tab and expand the Templates and Click on the Home Template, now find the div with the ID slider. Let s analyze our slider HTML, we can see we have the div with the ID slider which holds a div with the class slides_container which holds all the slider images, each image in the slide is wrapped with a div with the class slide this div is what we will use to create our Chunk Tpl so Gallery can iterate every image in the Album and apply this template to each image, if you look closely you will notice the second image in our gallery has a div with a caption class to display any image captions, let s copy the code we will use for our Chunk Tpl:

<div class="slide">
<a href="#"><img src="images/fern.jpg" alt="" /></a>
<div class="caption">Insert your caption here</div>
</div>

Right Click the Elements Tab and select New Chunk.

<a href="images/tutorials/soho-part3/template-tutorial (38).jpg" rel="prettyPhoto[pp_gal]" class="prettyGalleryThumb"> <img src="images/title-background.png" alt="Create New Chunk" class="lazy" data-original="images/tutorials/soho-part3/template-tutorial%20%2838%29.jpg"/></a> <p>In the Create Chunk page insert a Name, Description and paste the code we copied in the previous step into the Chunk Code text area.</p> <a href="images/tutorials/soho-part3/template-tutorial (39).jpg" rel="prettyPhoto[pp_gal]” class="prettyGalleryThumb">

Now we need to modify our Tpl so we can make it use the fields for each of the images in our Album. After modifying our Chunk Tpl our code will look like this:

<div class="slide”>
[[+url:!empty=&lt;a href="[[+url]]"&gt;]]<img src=”[[+image_absolute]]” alt=”[[+name]]” />[[+url:!empty=&lt;/a&gt;]]
[[+description:!empty=&lt;div class="caption"&gt;[[+description]]&lt;/div&gt;]]
</div>

Let s go over what is happening here, the first line of code opens a div with the class slide which acts as a wrapper for each of the Album images, the second line we can see some MODX Syntax:

[[+url:!empty=<a href="[[+url]]">]]

This is a MODX Placeholder with an Output Modifier, a normal placeholder would be this would tell MODX to use the URL field for our image as the text for this placeholder which will act as the URL for this image. We are using an Output Modifier because not all of our images will have links, so this code:

[[+url:!empty=<a href="[[+url]]">]]

Tells MODX if the URL field is not empty render an

<a href=”[[+url]]"> 

tag and use the URL field of our image as the href value.

The next line of code is for our image tag:

<img src=”[[+image_absolute]]” alt=”[[+name]]” />

As you can see it s a regular html image tag that is using an placeholder as the source of our image and it s using the placeholder as our images alt text. With this code we are telling MODX render an image and use the images absolute path as the source and use the image name field as our images alt text.

The next code is the closing tag of our a href tag using another Output Modifier:

[[+url:!empty=</a>]]

This tells MODX render a closing a tag if the url field of our image is not empty. So now MODX will know when to render an a href and when not to, if no text is inputted into the URL field of any given image MODX will render a regular image tag, if the URL field has any text then MODX will wrap our image tag with an a href tag.

The next line of code uses another MODX Placeholder with an Output Modifier:

[[+description:!empty=<div class="caption">[[+description]]</div>]]

Now we are telling MODX if the Description field of our image is not empty render a div with the class caption and use the contents of the Description field as its content.

The next line of code closes our div tag to complete our tpl code:

 

</div>

Your home-gallery-tpl code should look like this now

<a href="images/tutorials/soho-part3/template-tutorial (40).jpg" rel="prettyPhoto[pp_gal]" class="prettyGalleryThumb"> <img src="images/title-background.png" alt="Edited home-gallery-tpl" class="lazy" data-original="images/tutorials/soho-part3/template-tutorial%20%2840%29.jpg"/></a> <p>Now we need to create our Gallery call so we can see our slider in action, let s go back to the Home Template.</p> <p>We need to find where the code for our gallery is in our template so we can replace it with our gallery call</p> <a href="images/tutorials/soho-part3/template-tutorial (41).jpg" rel="prettyPhoto[pp_gal]” class="prettyGalleryThumb">

Locate the div with the class: slides_container you will see it has 3 child divs with a slide class, delete the divs with the slide class along with their contents and let s replace them with our gallery call which looks like this:

[[Gallery? &album=1 &thumbTpl=home-gallery-tpl]]

Let s go over what we are doing here, first we are using the Gallery

[[Gallery?]]

snippet and we are passing the album parameter (the ? let’s us pass the parameters to the gallery snippet)

&album=1 

to tell the Gallery which album it should use then we pass the thumbnail template

&thumbTpl=home-gallery-tpl

this tells Gallery to iterate our home-gallery-tpl chunk to each image in the gallery.

Our final Gallery call should look like this

<a href="images/tutorials/soho-part3/template-tutorial (42).jpg" rel="prettyPhoto[pp_gal]" class="prettyGalleryThumb"> <img src="images/title-background.png" alt="Gallery Call" class="lazy" data-original="images/tutorials/soho-part3/template-tutorial%20%2842%29.jpg"/></a> <p>Save your template and click on view now your image gallery is working with MODX Gallery Extra.</p> <div class="tip"> <img src="images/tip.png" alt="Tip" class="tip-icon"> <p> Tip: You can use the albums name in the album parameter or the album ID, you can find the album ID by going to Components > Gallery the album ID is the number between the parenthesis next to the album name. </p> <p>Another option is to create a template variable and use it as the value in the album parameter, for example I make a TV called gallerySelector with an input value of galleryalbumlist then the album parameter would look like this:</p> <pre class="brush:jscript">&album=[[*gallerySelector]]</pre> <p>this will allow you to select a gallery from the MODX backend, very handy for non-technical users.</p> </div> <p>When previewing our Gallery I noticed none of the images had a caption this is because our Output Modifier is at work and since none of the images have any text in the description field it won t render the caption tag. Go to Components > Gallery then Right Click on the album and select Update Album</p> <a href="images/tutorials/soho-part3/template-tutorial (43).jpg" rel="prettyPhoto[pp_gal]” class="prettyGalleryThumb">

In the Album page Right Click on one of the images and select Update Item, this will open a pop-up window with the selected image properties, here we can change the Name, Description, URL and Tags for the image insert any text in the description field so our image can have a caption and click Save.

<a href="images/tutorials/soho-part3/template-tutorial (44).jpg" rel="prettyPhoto[pp_gal]" class="prettyGalleryThumb"> <img src="images/title-background.png" alt="Update Item" class="lazy" data-original="images/tutorials/soho-part3/template-tutorial%20%2844%29.jpg"/></a> <p>Now refresh your homepage again and the image you updated should have an image caption now</p> <a href="images/tutorials/soho-part3/template-tutorial (45).jpg" rel="prettyPhoto[pp_gal]” class="prettyGalleryThumb">

Thanks to our Output Modifiers MODX knows when to render the caption div and the a tag if any link is inserted into the URL field for the image.

This concludes our Gallery integration for the Homepage, our next tutorial will cover creating the Template Variables for the remaining text fields on the page.