Welcome to this new series of tutorials on the MODx CMS where we’re going to be talking about creating custom snippets for MODx Evolution 1.0.x. We’ve been building a website called Learn MODx and so far it’s just a simple but functional website. We’re going to keep building on and enhancing this website. Before we proceed, I should mention that I’ve already updated the Learn MODx website to the most recent version of MODx Evolution 1.0.2. If you started at the beginning with me and still have your site running on 0.9.6.3, please take a moment to upgrade your site. You can watch this screencast on how to upgrade your MODx site.
In this series on creating simple custom snippets, we’re going to look at the basics of creating your own snippets. I’m no PHP guru so we’re not going to be doing anything crazy here 🙂 but I hope to give you enough information to jump start you into exploring and digging further to create bigger and better things and see how truly powerful and extensible MODx is. At this point I assume you know what a snippet is and have probably already used some snippets in your own MODx websites. (If you don’t know what a snippet is, please go over the MODx Beginner Series as that will help lay the foundation for this series).
As the MODx community continues to grow, more and more snippets are added to the repository and so it’s getting easier to find what you need. But what if you want to add something really custom to your website, some functionality for which there isn’t a snippet in the repository, or you just can’t find a snippet in the repository that does what you need exactly the way you need it done? Well, then you can create your own snippet! If you know how to code PHP, or at least have some of the basics down, you can start creating your own snippets for your MODx site, and maybe even share them with the MODx community.
So let’s get to it!! A snippet, at it’s very basic, is just a PHP script. That’s it. So if you can write PHP, you can write a MODx snippet.
A further extension to this is: if a PHP script works outside MODx, then in theory, that script will work in MODx. Now I should add a caveat here that this is probably not 100% accurate and is somewhat oversimplified, but as we proceed I hope you’ll start to get a sense of what’s possible.
Disclaimers aka “it wasn’t me”
First: As I said before, I am not an expert in either PHP or MODx, I am simply sharing what I’m learning as I go, and this blog is more my own notepad for future reference than anything else. Therefore this tutorial is not intended, nor does it claim to show you the best way or even the right way to create a snippet. What I do hope is that at the end of this process you will have an idea of what is possible in terms of adding your own customizations and addons to sites you build with MODx, and you’ll have gathered some resources that you can refer to in your own ventures. The other thing I hope to accomplish is to show you that with even basic PHP knowledge, patience, and persistence, you can do your own custom stuff with MODx without having to learn a whole other syntax and language. I hope that if you’re new to MODx and to PHP, this simple tutorial will get you more interested in exploring and hopefully contributing to the MODx snippet repository.
If you’re a MODx and/or PHP guru, I apologize because the knowledge shared here will probably be very rudimentary to you, but I hope that you will stay, read through, and give some input and feedback to help me and other beginners in our journey of learning to code and create our own snippets.
Second: I am very much aware that I may be reinventing the wheel here. I am sure that there is something out there in the repository that does what I’m aiming for and trying to develop and does it well, but I will confess that I haven’t looked, simply because I wanted to go through the process and try to learn how to do this myself. I definitely recommend that you look through the MODx repository first before starting out to code your own snippets because there may be something already there that you can add to and/or customize for your own needs.
Drumroll please…
So with all that out of the way, let’s talk about the little snippet we’re going to create.
Through a series of about 4 or 5 posts, we’re going to create a simple custom MODx snippet that will allow us to retrieve RSS feeds from one website/blog and show them on our own website. The purpose of this process is not so much to develop a snippet for distribution as it is to explore some aspects of the process of creating simple snippets for MODx evolution.
This snippet isn’t going to be particularly elegant or powerful, but it will be functional enough for my purposes and hopefully someone else will find it useful. So this is a journal of my journey to creating what I’m calling the rssfeedFetcher snippet 🙂 .
Here are the steps we’re going to follow:
1. Create and test the raw PHP script
2. Transform the script into a MODx snippet
3. Add parameters and placeholders
4. Add some simple styling and templating
5. Talk about how it rocks and how it sucks
As we work we’re going to try and adhere to the recommended best practices of creating a snippet as outlined in the MODx wiki. We will also use some parts of the MODx API. At the end of this process, I will address the limitations and shortcomings of my rssfeedFetcher snippet and what I would like to add to it.
Just as a preview, this series will create rssfeedFetcher v1.0 which will only work to fetch RSS feeds from one website, and will probably not be able to parse all kinds of feeds. If all goes according to plan and we don’t get too frustrated, we may follow this up by creating rssfeedFetcherI (I for improved) or rssfeedFetcherX (X for eXtreme 🙂 ) or something like that which hopefully will be an even better feedFetcher to allow us to pull feeds from several different websites… maybe 🙂
What about you?
I am going to assume that you know the basics of MODx, and have some basic PHP knowledge, at least enough to know where to look for answers about things in the code that you don’t understand. Even though this is not a PHP tutorial per se, I will try to explain as much of the code as I can so that even if you’re a complete PHP novice, you will have somewhat of an idea about what I’m doing. I am also going to be including a list of links to basic PHP tutorials that should help you get started and figure stuff out. And ofcourse you may ask about anything that’s unclear in the comments and I will answer as clearly as I can, and hopefully others more knowledgeable than me will chime in.
So make sure you subscribe to the feed and stay tuned for Part 1, coming soon to an rss feed near you! 🙂
Useful Links
PHP.net
PHP 101 Tutorial for Beginners
MODx Wiki on Creating Snippets