MODx Revolution for Complete Beginners Part 7 – Working with Snippets
Welcome to part 7 of the MODx Revolution for Complete Beginners series. In the last installment we learned about template variables and how we can use them to create custom editable fields on our site pages. As we work through these tuts we’re building a resource site for learning MODx Revolution. We’re using the 7 in 1 Business Success Site Template from Themeforest, although you can follow along with any template that you choose. We’re learning how to transform the static stuff on the HTML/CSS/JS template into dynamic content from our site. Everything we’ve looked at so far has been about presentation and layout. In this installment, we’re going to very briefly start talking about how to add functionality to our site using Snippets. This is going to be just a brief primer on snippets, and in subsequent installments we will be working through several snippets, each post covering one or two snippets at most.
What is a Snippet?
Snippets are pieces of PHP code that enable you to add functionality to your MODx site. According to the official documentation:
Snippets are MODx’s answer to inline PHP code. They provide customizable dynamic content, such as menus, blog or news listings, search and other form-based functionality and anything else that your site needs to generate on-demand.
Snippets allow you to add functionality such as navigation, twitter feeds, search, image galleries, contact forms, content aggregation, commenting, and so on to your MODx site without actually having to write the PHP code yourself (unless of course you want to create your own snippets 🙂 )
The MODx repository has a growing collection of snippets, some created by the core developers and others contributed by community members, and you have access to all these snippets often with just a couple of clicks. As I alluded to above, you can also create your own snippets for custom functionality if nothing available out there strikes your fancy, it just depends on how comfortable you are coding PHP and learning the MODx API. Since this is a beginner series, we’re going to focus our attention on existing snippets, but down the line I will do a series on creating your own snippets.
How to Install Snippets in MODx Revolution
If you have used MODx Evolution, you know that the core install of Evolution comes with a number of snippets by default. To add other snippets, you have to download them from the MODx website, upload the files to your server, and then manually copy and paste some code to create the snippet. In Revolution, this process has been significantly simplified 🙂 While the default Revolution install does not come with any snippets at all, all you need to do is go into your site manager, under System->Package Management, click Download Extras, and then find the snippet you want, download it and install it. Simple!
I won’t go into great detail on how to do this in this post as I already covered the process in Part 3 of this series, so if you need a reminder, please visit and reread that post.
How to Call a MODX Revolution Snippet
Once you’ve installed the snippets that you want to use, the next step is to call the snippet into your template or page, wherever you need the functionality. The basic syntax for a snippet call is [[snippetName]]. If the snippet is expected to produce different results for different users or different sessions, such as an aggregator, or an RSS feed, then you would need to call the snippet uncached, and you do this by adding an exclamation mark before the snippet name, [[!snippetName]]
Now, for most snippets, the basic call that just has the snippet name is not enough to get the desired functionality. For example, if you’re pulling in an RSS feed from another site into your site using a snippet, you want to be able to state how many feeds to show at one time, how much of the feed to show (just the title, or the title plus the date, etc.) and so on. For this reason, snippets have properties, some of which are compulsory and some optional. In most cases, snippets will also give you a way to style and template their output.
Most of the snippets in the MODx repository are very well documented, and it’s always a good idea to look in the MODx documentation for more information on each snippet. Each snippet will likely also have a dedicated topic in the MODx forums where you can ask questions and get peer support or support from the developer. If you’re having trouble with a snippet, this is one of the best places to look as chances are that someone else has had that problem before you.
I know you’re probably wondering… is that it?? 🙂 Well, as I mentioned, this is just a primer. We’re going to be delving into snippets one at a time in the coming installments. In the next installment, we’re going to start with Wayfinder, a snippet that produced unordered lists and is perfect for creating menus. We will use Wayfinder to replace the static menu on our website with a dynamic one that will pull from site pages that we want to have in the menu.
I recommend that you go ahead and install Wayfinder in your Revolution site, and stay tuned for the next installment. In the meantime, feel free to leave any comments, questions, or suggestions you may have, or just to say hey 🙂