Snippets
Overview
Snippets are the method by which MODx allows you to run dynamic PHP code in any of your pages.
What is a Snippet?
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.
Simple Example
Here's the perfunctory super-basic example of what a Snippet might look like:
<?php return "Hello, World!"; ?>
If you named this "helloWorld", you could call this snippet by using [[helloWorld]] in your documents, templates, or Chunks.
Passing Values Into a Snippet
Snippets can take input values using a modifed CGI web-form type notation. For example, if your Snippet looks something like this:
<?php
return 'My input was: ' . $Input;
?>
You might call it using something like this:
[[my_snippet_name? &Input=`Hello World`]]
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'). 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!
Recommended Methods and Tips
- Write your Snippets outside of MODx. 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.
- Don't try to mix PHP and HTML in a Snippet. 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:
<p>This is a horrible mixture of HTML and PHP</p> <?php return "<p>and PHP! Don't try it! It's bad architecture and it won't work!!</p>"; ?>
You'll find that MODx will append PHP tags to beginning and end of the snippet, creating an invalid syntax, e.g.
<?php <?php //something here ?> ?>
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, 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.
- If your Snippet is going to accept more than one or two parameters, have it offer the use of external config files. Simply add a block of code at the beginning of the Snippet's code to check if a config parameter was used, and include the .php file if it was. This way the user can configure the Snippet with an external .php file, declaring the parameters as normal PHP variables. Even view templates can be defined in the file, rather than as a chunk. Since it's an ordinary .php file, it can be used to generate conditional parameters for the Snippet. With this external config file, the Snippet tags only need one &config=`name` parameter.
- If the Snippet generates forms or other complex structures, you can give the user the option of specifying a custom .css file by checking for a configuration parameter and loading the specified .css file into the document's HTML head, using the $modx->regClientCSS() API function. This also applies to any .js files specific to the Snippet. This way the main .css file for the site doesn't have to be cluttered up with the styles for the Snippet's output when the Snippet only uses one or two documents.
