Building a Website with MODx for Newbies – Part 5: Introducing Snippets
Welcome to part 5 of our series of tutorials on building a website with MODx CMS. So far we’ve looked at:
As we work through these tutorials, we’re building a MODx resource site called Learn MODx. In the last installment we introduced chunks and learned how to use them to clean our template and make it more manageable. So far our website looks like this: (you can click on the images to see a larger view)
Today, we’re going to introduce snippets and learn how to use them to add functionality to our website using one simple example. At this point in our tutorial, if you’ve been following along, our website navigation is simply cosmetic and the links don’t really lead anywhere. We’re going to use a snippet to rectify that and make our site navigable from the horizontal menu links.
What is a snippet?
Snippets are bits of code to perform some dynamic action, such as retrieve data from a database or read from the SESSION values or a cookie. They provide the ability to separate “business logic” from the layout and presentation of your web page. (MODx Wiki)
When we installed the core MODx install, we had the choice to install some snippets along with it, and we opted to install all the ones that were listed. If you didn’t install any of these and find that you need them, you can find them and more on the Extras page on the MODx website (under MODx Addons.
There are two ways to call snippets: [[Snippet]] or [!Snippet!]. If you use the [[ ]], then the Snippet will be cached. But if you use the [! !] call, the Snippet will be uncached. This quote from the MODx documentation explains it better than I possibly could 🙂
Now when you have some dynamic content on the page, i.e. snippets and you call them using [[Snippet]], they will be cached. They’ll run only at the first request and after that, its all coming from cache. If you change some parameters on your cached snippet call on a cached document, you might not see the changes because it’s not parsed on every request. But you can force the snippet to run on every request even if the document itself is cached by using [!Snippet!] call (note the ! chars). Then your snippet will be parsed on every visit to the page. Or you could set the whole page to be uncached at the “Page settings” tab (uncheck cacheable). Then it doesn’t matter if the snippet calls are [[cached]], because the entire document will be parsed on every request regardless. (http://svn.modxcms.com/docs/display/MODx096/Document+Caching)
Snippets can take on arguments/parameters to customize and refine their behavior, and you’ll see this as we work through these tutorials. It’s always a good idea to read through the documentation for any snippet you use so that you can learn how to install and use it correctly, and how to use it’s arguments to exploit it’s full power.
The Wayfinder Snippet
For our menu to work, we’re going to use the Wayfinder snippet, which is a menu snippet. This is one of the snippets that we installed during our MODx installation. To make sure you have it installed, navigate in your site admin backend to Resources -> Manage Resources -> Snippets.
If you don’t have it, then you need to go to the MODx website, download the Wayfinder snippet, and follow the installation instructions.
Before we proceed with our snippet, let’s add some pages to our website so that our navigation has several items to list. In the document tree, click on Learn MODx. This will allow you to create a page in the root. Then click on the New Page icon as shown:
Go ahead and create a page titled “About Us”. This page is going to contain some basic information about our site.
Remember you need to specify the template as swansong. The next thing you need to make sure is that your page is published. MODx pages are not published by default when you save them, so you need to check this box on the Page settings tab.
You can change this default behavior in the site configuration, but I’m not going to do that right now. Let’s save our page, and we now have two pages in our document tree.
Now that we have two pages to start with, let’s call our Wayfinder snippet and create our navigation. Remember our menu is in the header chunk, so go ahead and open that chunk.
When we call the Wayfinder snippet, we need to add some arguments/parameters to this basic call to make it do what we need it to. All we want is the primary links at this point, so we need to tell Wayfinder not to go any deeper than the first level. Also, because it’s possible to create menus for child pages of any page we create, we need Wayfinder to know what our starting point is. All this will become a lot clearer as we progress in building our site and add child pages and secondary menus, but for now, we’ll stick with the basics.
For a comprehensive guide on Wayfinder, you can download the free Wayfinder ebook by Kongondo, at the MODx forum: http://modxcms.com/forums/index.php/topic,34176.0.html
Alright, so based on my requirements above, my Wayfinder Snippet will simply need to have two arguments, startId to tell it where in the Document tree to start building the menu from, and the level argument to tell it how deep to go in the document tree. Again, these will become clearer as we build different menus for our website. For now, I want the menu to be built from the root, the first level only. So my startId will need to be 0 (zero) and my level will be 1 since I only want the first level of links. Here is what my Wayfinder snippet call will look like:
[[Wayfinder? &startId=`0` &level=`1`]]
Look carefully at the syntax here: Note that that you put a ? sign right after Wayfinder with no space between them, and then each argument is preceded by the ampersand sign (&). Note also that those are back ticks `, not apostrophes or quotes. In the standard English keyboard layout, the back tick is found right above the Tab key:
Alright, let’s replace the menu links in our template with our Wayfinder call. In the header chunk, replace:
<ul id="navlist"> <li id="active"><a href="#" id="current">Active link</a></li> <li><a href="#">Item two</a></li> <li><a href="#">Item three</a></li> <li><a href="#">Item four</a></li> <li><a href="#">Item five</a></li> </ul>
[[Wayfinder? &startId=`0` &level=`1`]]
Save the chunk and then navigate to your site, and you’ll see the navigation is now actually functional, and you can navigate between our two pages, Home and About.
Any pages you add to the root of the site will now appear on this menu. If you don’t want a page to appear in the menu all you have to do is uncheck the box in the page creation screen that says “Show in Menu”. We will be revisiting the Wayfinder snippet in future tutorials as we build more pages and more navigation links on different sections of our websites.
In this post we’ve started touching on the basics of what snippets are and how we can use them to add functionality to our MODx site. I used the Wayfinder snippet as an example to make our site navigation functional, removing the old links that didn’t go anywhere and calling the Wayfinder snippet to show our primary links and allow us to navigate the main portions of our site. Our website now looks like this:
As you continue to venture into MODx, you will find that a lot of the power of MODx lies in the ability to create and call snippets. We’re going to continue this series using different snippets to add all kinds of functionality to our website, including search, a blog, secondary menus, aggregation, and so on. We will also introduce Template Variables (also known as TVs) in the next couple of posts as we continue to build our MODx resource site.
For now, I recommend that you get a hold of the free Wayfinder ebook by MODx community member Kongondo so that you can continue to explore Wayfinder. The link is in the “More Reading” section at the end of this post. Also remember to grab your copy of the MODx Web Development book.
Stay tuned for the next installment of our MODx tutorial for beginners.
http://svn.modxcms.com/docs/display/MODx096/Document+Caching – On Document Caching
http://modxcms.com/forums/index.php/topic,34176.0.html – Free Wayfinder ebook