Snippet call parameters and default values

22/03/2009 (0) 096x, snippet

Snippet parameters provide a simple method for passing information to the script (snippet) in order to define elements of the script's behavior. The parameters are defined directly in the snippet call and are processed by the MODx parser when the document is loaded.

A snippet can be as simple as a php function to format a date, or it can be as complex as a full featured eCommerce application with thousands of lines of code. Snippets are a powerful MODx feature, however, without a clear way to allow the developer to personalize the snippet's behavior or output display, you would need a unique snippet for each objective. In other words you would need to manually edit the snippet code and alter the output for each instance of the snippet. Through the concept of Snippet Parameters you have a way to set specific predetermined parameters and pass the resulting data directly to the snippet script during it's execution.

Defining a snippet parameter

The snippet call in it's simplest form consists of the snippet name wrapped in the snippet operator:

[[snipetName]] or [!snipetName!]

This will execute a snippet with all of the parameters defined internaly by the script. In many cases this will work just fine. However, MODx allows you to include snippet parameters in the individual call, instructing the snippet to change it's default configuration values by defining the parameter values directly in the snippet call.

Check out the wiki article Snippet Call Anatomy for more information on the snippet call syntax.

The snippet call is more than a simple placeholder for your php script, it is in effect an interface for configuring the individual instance of the snippet. This principle is fundamental in the development of snippets that can be easily customized without editing the source code.

Accessing the parameter value

Ok, so you have a parameter defined in your snippet call, but how do you access the parameter value in your snippet code. You may expect that you will need to use a complex method or sophisticated class to reach the snippet call parameter. Wrong.

Every parameter defined in the snippet call is seamlessly transformed into a variable with the same name as the parameter and made available directly to the snippet. For example if you have a snippet parameter &startId=`123` it is automatically available to use in the script as the variable $startId with the value of 123.

Once you have the value available as a variable you can use it in you script as you would any traditional variable:


[[snipetName? ¶m=`foo`]]

if ($param == 'foo') {
	// do something
}

You can have as many snippet parameters as are required.

Setting default parameter values

There will be several occasions where you will want to define default values for the snippet parameters. However, you may want to allow users to overwrite the default values with the value specified in the snippet call.

Since we have access to the snippet parameters in the form of a variable we can perform a little logic to check if a value exists and load the default or custom value accordingly. The most common and efficient method to do this is via the Ternary Operator. If you look at the large majority of MODx snippets you will see the ternary operator used to define default values. Here is an example from Ditto:


$depth = isset($depth) ? $depth : 1;

This is stating that if the variable $depth is set as a snippet parameter, then use the current value in the variable. Otherwise use the default value which is set to 1.

You could also do an 'if' statement for each variable:


if(isset($depth) {
	$depth = $depth;
} else {
	$depth = 1;
}

Both statements will have the same results, however, as you can see, the Ternary takes less code and once you get used to it, is much easier to read.

Other sources for parameter values

There are other sources that you can use to set configuration parameters for your snippet. We have already seen how to use $_POST and $_GET values into your snippet in the previous Utility Snippet post.


$tags = isset($_GET['tags']) ? $_GET['tags'] : 'no tags';

You also have the option os using sessions variables:


$username = $_SESSION[webShortname];

Check out the article on sotwell.com for some live examples, make sure to login as web and manager users to see the available session vars for each user type. There is a good post by Breezer in the MODx forums that covers ways of returning session values in snippets.

A few snippets have configuration files that can load a preset of parameters in an easy to use (and distribute) configuration file. One snippet that has this option id Wayfinder. Check out the Digg menu config file for Wayfinder for an example of how this is done.

More info on snippets

Conclusion

This has been a simple overview to illustrate how information can be passed from the snippet call to the snippet code and used to configure or customize the snippet behavior. In the next posts I will discuss methods for using data from the MODx content structure within your snippet.

User Comments