- What is a Snippet?
- How Do They Work?
- Simple Example
- Passing Values Into a Snippet
- Reading Values in your Snippets
- Database Interaction in Snippets
- Recommended Methods and Tips
- Write your Snippets outside of MODx.
- Don't try to mix PHP and HTML in a Snippet.
- Don't Work on Live Snippets
- Use Default Properties
- See Also
Snippets are the method by which MODx allows you to run dynamic PHP code in any of your pages. They are the main development vehicle for most developers.
According to one definition, a "snippet" is "a short reusable piece of computer source code". Some people have a hard time distinguishing this from a "chunk", so a helpful mnemonic might lie in the p's... as in "PHP", e.g. sni-"P(h)P"-et.
First off, most Snippets are cached, meaning they're stored as a temporary, dynamic function in the cache. If they're flagged as uncached, then they are not parsed until the parser has done all of the other cached content.
Then, once they're up to be cached, Snippets are then parsed by the MODx Parser. They have access to the $modx object.
Here's the perfunctory super-basic example of what a Snippet's code might look like:
If you named this "helloWorld", you could call this snippet by using [[helloWorld]] in your documents, templates, or Chunks (see Tag Syntax). You can also call a Snippet from another Snippet using the runSnippet API method.
|Note how we returned the code rather than echo'ed the content out. Never use echo in a Snippet - always return the output.|
Values are passed to your Snippet using a modifed CGI web-form type notation that follows the Snippet's name. If your Snippet were named "mySnippet", you might call it using something like this:
And the code for your Snippet might look something like this:
Notice that the variable names in the calling bit need to match the variable names in the Snippet EXACTLY (case matters... i.e. 'input' not 'INPUT' or 'Input'). Secondly, don't forget the '&' in front of the would-be variable names. And last but most certainly not least, take note that those are backticks, not single quotes!
In general, you can read your values by referencing the arguments that were passed: &someParameter in the call translates to $someParameter in the PHP code.
You can also read all parameters by using the built-in $scriptProperties array. This is useful if your Snippet takes variable parameters – it handles a similar use-case as PHP's func_get_args() function.
For example, if you call your Snippet using a call like this:
Then the $scriptProperties array will contain this:
Accessing the database layer in MODx relies on an Object Relational Model (ORM) called xPDO for database connectivity, so you won't often write raw database queries like you might do in other CMS's. Usually you will access data from the database using several MODx objects and methods such as getObject and getCollection. This relies on the underlying xPDO framework.
You might be asking, why use an ORM instead of just straight SQL? Well, a few reasons:
- SQL Abstraction - This means that you can write code that works in a variety of different database types, such as MySQL, sqllite, postegresql, and more, as MODx expands to those databases. All without having to rewrite a single line of code. This makes it ideal for plugin authors who want their code to be executable on the widest possible variety of systems.
- Parameter Escaping - No more having to worry about SQL injection; xPDO uses PHP's PDO to escape all variables passed in to the SQL call to prevent any malicious calls.
- Cleaner, shorter Code - What could be done in 40+ lines in mysql_* calls can now be done in 10 or less.
There are more reasons, but that's for brevity. Let's look at a few examples:
Let's get a chunk named 'LineItem', and change the placeholders in it (done with [[+placeholderName]] syntax) to some custom values:
That code would get a chunk with the name of 'LineItem', and return it processed with the placeholders set. The $chunk variable there is actually an xPDOObject, which is an object representation of the Resource.
What about more complex queries? Like, say, getting the first 10 Resources with a parent of 23, 24 or 25. And let's make it so they aren't hidden from menus or deleted, are published, and sort them by menuindex. That's when we use the powerful $modx->newQuery() method:
Note how we first create an xPDOQuery object ($c) using $modx->newQuery(). We passed in the name of the class we wanted to build the query from - here 'modResource', or Resources - and then used our where() function to add some restrictions. Then we sorted and limited them.
And finally, we called getCollection which - unlike getObject - returns a collection, or array, of xPDOObjects. We could then iterate over those using foreach and do whatever we want with them.
For further reading on xPDO, read up on these:
As of 2.2.0, you can simply add a "static" Snippet: just reference the static file.
Pre 2.2.0, it's still pretty easy to do - just create an 'include' snippet, but make its content be this:
You can use the include snippet on a page like such:
And run your Snippets externally while you develop them!
Then you can test them to make sure they work (e.g. on the bash command line, you can use the command php -l my_script.php to check the script for syntax errors). Depending on your environment, you may also get some useful error messages to help you with debugging. Copy and paste the code into MODx only when you're sure it's working.
Remember that a snippet in a file on your web site can be executed by anyone with a web browser, so don't leave them there on a live site unless you've placed the snippet code outside the web root so the file can't be accessed via the web. In MODx Revolution, you can put the snippet files under the core directory and move the entire directory outside the web root. You can also put a test in the snippet that makes it exit if it's not running inside MODx, but it's safest just to move the file or paste the code into a snippet in the Manager and delete the file.
Snippets execute PHP code. They should always begin with a <?php and end with a ?> You cannot mix PHP and HTML in a Snippet! For example, the following code won't work:
You'll find that MODx will append PHP tags to beginning and end of the snippet, creating an invalid syntax, e.g.:
If you need to do something like this, use a Chunk - separate the PHP into a Snippet, load its output into a placeholder with the modx API placeholder functions or chunk processing, and include the Snippet's placeholders in the Chunk:
If you're writing new versions of Snippets, duplicate the old version! That way you can go back to the old version of the code if something doesn't work correctly! MODx doesn't inherently do versioning control, so you have to backup code yourself.
Consider adding your properties for your snippet into the Properties grid, so that the user can add custom Property Sets to override them.