How-to: Use MODX getResources & getPage for a gallery...or anything you want!

My latest assignment was a MODX site featuring a thumbnail gallery with the following requirements:

• List up to 8 thumbnails in a static-sized div.
• Thumbs pulled from end-user-created-and-editable MODX resources.
• If in photography section, clicking thumbs opens Lightbox.
• If in design section, clicking thumbs opens another page with more info.
• If more than 8 resources, pagination starts up.
• Lots of targeted styling.

So of course the first snippet that comes to mind is the venerable all-in-one toolbox called getResources and the sister-snippet getPage for the pagination feature. Let’s walk through the install:

1. Official Documentation

• getResources: http://rtfm.modx.com/display/ADDON/getResources
• getPage: http://rtfm.modx.com/display/ADDON/getPage
• Property Set: http://rtfm.modx.com/display/revolution20/Properties+and+Property+Sets (you’ll see later why I added this)

2. I’m assuming pretty good knowledge of MODX and getResources, although I think this tutorial could come in handy for Beginners all the way to Advanced Users.
3. Template Setup
I’m using one template for all possible portfolio-related pages. You could do this with several templates, but I like to push the boundaries of MODX TVs because you can give the end-user control over them or not, depending on the situation. Flexibility is part of what makes MODX great, right?
The template has a radio option TV so the user can select: Photo thumbnail gallery, Design thumbnail gallery, Lightbox image item, or Design item info page. The latter two are just page layouts - it’s the first two we’ll talk about here because they’re essentially getPage snippet calls.
4. getPage Snippet Call
I started with the photography section, cuz I love photography


Break it down:
!getPage@Gallery? » Uncached call with a custom Property Set attached! getPage is NOT a regular snippet where you can reference template chunk names in the snippet call. You MUST use a custom Property Set to define these values. If you’re unfamiliar with them, check out the MODX Documentation (link above). I’ll go over some of the template features later...
&element=`getResources` » this tells getPage to use getResources to...well, get the resources. Haha. Note from here on in, properties in this snippet call are all relating to getResources!
&parents=`[[*id]]` » Uses the current page as parent, so child resources of current page will be listed.
&limit=`` » Sets the maximum number of resources to output.
&tpl=`` » Chunk name for photo item template.
&tpl_3=`` » Chunk name for template for every 3rd output photo item. This was necessary because the third item in each row had to be styled differently. Yes, I also used CSS Nth child, but not all browsers support (*sigh*).
&tpl_6=`` » same as above
&includeContent/&includeTVs » Both these properties tell getResources to output the content and template variables. They are off by default to save on requests ( or save on something, I’m not sure LOL )
&processTVs=`1` » Not only do you have to include template variables, if you want to process them and get their results you have to set this property.
&sortby/&sortdir » Pretty standard MODX snippet properties for sort order.

5. Now we look at one of the templates `photoTpl`


Break it down:
I’m outputting to an unordered list, which suits my purposes here. You can output to anything though. This template represents What Will Be "Gotten" From Each Resource, And Which Fields It Will Get Stuff From.
Note the `[[+` syntax: when writing a template for a snippet to use, you use `[[+` instead of `[[*` - don’t ask me why.
Also note the `tv.` prefix. That is for TVs, if it wasn’t obvious.

Extra detail (skip this if you’re bored) about the TVs:
tv.photo... » These all provide info about the image. The user can upload & specify images from the Resource’s Manager page. Having alt text and titles for everything is just a good idea (and to validate) - not required.
tv.lightbox » Just a way to specify `<link rel=` so that an image can be included or excluded from the Lightbox functionality by the user in the Resource’s Manager page.

We pretty much have all of our requirements:
1. Lists 8 thumbnails - Yes, &limit=`8`. Although you can’t see it here, the snippet call is inside a div so I can style the items as a group.
2. Thumbs pulled from Resources - Yes. We’re using getResources so this output is end-user-editable via Resources, with potential permissions & form customization, yada yada yada.
3. Thumbs open Lightbox - Yes. There’s extra JS & stuff but that’s separate. Our &photoTpl provides the means to target the images for Lightbox functionality ( rel="lightbox" ) AND allows the end-user to turn this on/off via the TV.
4. Pagination - Yes. We’re using getPage which automatically outputs pagination, with a customized (@Gallery) Property Set.
5. Targeted styling - Yes, &photoTpl allows us to set classes and IDs. Need SNIPER targeting?

**PRO TIP: Are You Ready? »
Just add: id=[[+id]]
to any html tag in the template and you will have an absolutely unique CSS selector for every instance of that tag :END PRO TIP**

The customized Property Set for getPage allows you to setup templates for the pagination items, so even THAT can have custom selectors if you want. I wanted, and MODX delivered - as usual

Example:

This is almost the default &tpl for getPage, which you’ll find in the snippet’s properties page. I just added a custom #id and <span> to the link text. That’s all, folks!

Ok, ok, I missed "If design section, thumbs do something else..." Sheesh, you’re demanding, aren’t you? It’s like this: the radio option TV I talked about above just selects different getPage snippet calls, depending on which gallery style the user wants for the page. From there, each version of the snippet call can use different &tpl for infinite possibilities. Why not just use different page templates, you ask? Because this way, the user can choose gallery style WITHOUT having access to change page templates. What if they chose the wrong template? A potentially broken, or at least unsightly page that will be unnerving for the user. "Aaargh! I broke the site!!" Rather, if they only have the power to choose the wrong Gallery style, it’s no big deal.

There. Hopefully worth the hours it took for me to write this and you to read it LOL.

Quote from: TomMLS at Jun 15, 2011, 07:39 AM

Does this implementation care about image dimensions??
Usually galleries insist that all images be the same size H and W dimensions.

It just depends on your templates and what you’re using it for. I have 8 equally sized images in a static-sized div, but you could just as easily have 8 (or however many you want) images of different sizes placed all over the page. If you want to style each returned item separately, just add the ID placeholder as mentioned in the original post.

Does that answer your question...or did I miss the point? LOL

If you install the PhpThumbOf addon, you can use that to resize them on the fly and have it cached for next use:


Info on the phpthumb properties can be found in the phpthumb docs: http://phpthumb.sourceforge.net/demo/docs/phpthumb.readme.txt They’re at about 1/3rd into the page.("Parameters")

Thanks for this, Mark. Me being completely useless at anything PHP related - how would I install phpThumb?

PhpThumb is included in the core (aint that awesome! ), and to make it even better: it is properly secured.

To use the output filter you will just need to include the phpthumbof addon via the package manager, that one will hook you into the core phpthumb package.

That pretty much KICKS BUTT!!! Yay for MODX yet again