Bob's Guides

MODx Snippet Properties

Snippets are sections of PHP code that are executed by MODX whenever it sees a snippet tag. Whatever the snippet returns, prints, or echos, replaces the tag. Often, you want to send information to the snippet in the snippet tag. Sometimes, the snippet needs information to do its job, such as the ID of the current document. Sometimes, you just want to send information that controls how the snippet behaves. In either case, you send the information in the form of snippet properties (formerly called "parameters"). Most snippets have properties, which may be required or optional.

Snippet Documentation

To know if a property is required or optional, how it is used, and what values it takes, look for the snippet's support page in the snippet section of the MODX Wiki. All of the most commonly used snippets are listed there. If the snippet is new and hasn't made it to the Wiki yet, look for a readme.txt file or a documentation folder in the downloaded .zip file. Another place to check is the resource page where you downloaded the snippet. Go to the MODX Resource Repository page and search for the snippet by name. On the Resource Repository page for the snippet, you will also find a link to the support forum for that snippet on the MODX Forums. There may also be a reference to the author's web site, which may contain extra documentation or tutorials on how to use the snippet. The support forum is a good place to look for more information about using the snippet and to ask questions about how to make it meet your particular needs. Be sure to read through the existing posts before asking questions that may have been answered already. If you're still stuck, you may have to look in the .php source code of the snippet.

Using Snippet Properties

MODX snippets are usually called with one or more properties (formerly called parameters). If you have done any programming, these are much like the arguments in a function call. The properties are just pieces of information that the snippet needs to do its job. Properties can be numbers, text, urls, or even chunks.

Here is a typical snippet tag:

[[MySnippet? &property1=`value1` &property2=`value2`]]

Notice the question mark right after the snippet's name. That tells MODX that there are properties coming. Each property is identified with an ampersand and the value of that property is enclosed in back-ticks. In the snippet's PHP code, the properties will be available as regular PHP variables (in this case $property1 and $property2). In MODX Revolution, the properties are also available in the $scriptProperties array (as $scriptProperties['property1'] and $scriptProperties['property2']).

Important!! Notice that the delimiter placed around the property values is not a single-quote but a back-tick character (usually found on keyboard as the lower-case '~' or tilde character). The most common mistake made by newcomers to MODX is using the single-quote mark as a delimiter in snippet tags. The authors of MODX chose the back-tick because it allows quotation marks and apostrophes to be used inside property values.

Optional Properties

In many snippets, some properties are required and some are optional. For optional properties, the snippet will have a default value for the property. If you don't include any properties in the snippet tag, the default values will be used. If you include the property, the value you use will override the default value.

Copyright © 2011-2024
Bob Ray