Snippets Overview

Overview

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
    echo "Hello, World!";
?>

But wait... let's start some good habits here. Remember that a Snippet is used as a function, so it typically returns a value, therefore a more correct construct of the simple "Hello World!" Snippet might be the following:

<?php
   $output = "Hello World!";
   return $output;
?>

If you named this hello_world, you could call this snippet by using [[hello_world]] 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
   $output =  "My input was: " . $Input;
   return $output;
?>

You might call it using something like this:

[[my_snippet_name? &Input=`Hello World`]]

Or like this (uncached): [!my_snippet_name? &Input=`Hello World`!]

Do not put spaces around the equals sign!!!

Notice that the variable names in the calling bit need to match the variable names in the Snippet EXACTLY (uppercase/lowercase matters... i.e. 'Input' not 'input'). Secondly, don't forget the '&' in front of your variable names. You may get frustrated if you try to enter your Snippet call into the content field with the TinyMCE editor running... it will want to replace the ampersand with the html equivalent, and your Snippet input parameters will be malformed. You can turn off the TinyMCE editor in your user's configuration, or try entering the Snippet call into another field, e.g. the Summary (introtext), just make sure that template variable appears in your template.

Tips

• Whenever possible, write and test your Snippets outside of MODx so you can 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. The contents of a Snippet are interpreted as PHP code; they should always begin with a <?php and end with a ?>. You cannot jump between PHP and HTML in a Snippet! For example, the following code won't work!

<p>This is a horrible mixture of HTML</p>
<?php
   echo "<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, and include the Snippet's placeholder in the Chunk. Or pass a Chunk as an input parameter into the Snippet. The point is that it's good design practice to keep logic and formatting separate from one another as much as practically possible, but don't let that hamstring you: there area times when it's perfectly acceptable to use HTML in a Snippet, e.g.:

// a line from a Snippet that legitimately uses some HTML
$output .= '<td>' . $cell_value . '</td>';

• 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.

• Don't put spaces between your Snippet arguments! Be sure your values immediately follow the variables, e.g. value=`something` -- no spaces!

• You can also run, and configure, other snippets with php from your own snippet.

<?php
 $menuOutput = $modx->runSnippet( 'Wayfinder', array(
           'startId' => $start_id,
           'level' => '4',
           'hideSubMenus' => 'TRUE',
           'sortBy' => 'pagetitle',
           'selfClass' => 'self'
           //,    'debug' => 'TRUE'
   
       )
   );
 return $menuOutput;
?>

See Also

Creating Snippets for more in-depth information for developing your own Snippets, as well as some good documentation for MODx's API and some common-sense best-practices.