Snippet call anatomy
From MODx Wiki
Contents |
The anatomy of a snippet call:
Newcomers to MODx are often overwhelmed with the apparent complexity of snippet calls. My first encounter with an eForm or Ditto snippet call sent shivers up my spine and sweat to bud on my forehead. It was so intimidating that it kept me away from some more powerful snippets. However, once new users get the hang of implementing snippet calls they soon discover its easier than first expected. Its certainly worthy of a little study as snippet calls are an integral and powerful tool within the MODx framework.
What is a snippet?
A snippet is a PHP function. That's it, simple. Snippets are commonly referred to as widgets, add-ons or modules in other environments. One common misconception is that snippets are part of MODx. They are not. MODx simply provides the method, the actual snippets are contributed by the MODx community. There are no rules to creating snippets, it is up to the snippet author.
The snippet call
A snippet call has two purposes; 1) to assign and execute a function on a specific document, and 2) to pass vital configuration parameters to the function to be executed. Every snippet has it's own unique set of parameters, dictated by the author, so it is always a wise idea to check the documentation for each snippet before using.
The basics
Here is an example of a basic snippet call:
This basic structure is the same for most (if not all) snippets, lets take a closer look;
The first thing to notice (and I am sure you all know this already) is that a snippet is identified (up to MODx 0.9.6.x) by two square brackets [[ for cached execution, and one square bracket followed by an exclamation point [! for un-cached execution. These tags need to surround the call so you need the corresponding closing ]] or !] tags at the end of the call as well.
The next important item is the snippet name. Snippets are case sensitive so make sure to type it as it reads in the snippet panel in the manager. The same goes for chunk names as well.
The minimum requirements for a snippet call are the surrounding tags and the snippet name. The following call will work for a snippet that does not need any parameters defined or one that you wish to call with the default parameters:
[!SnippetName!]
Snippet parameters
OK, so far so good. Now lets start to work with some parameters. In order to let MODx know that there are parameters in the call we need to add a question mark after the snippet name before the parameters (no space between the snippet name and the ?). Now we can define each parameter with the following syntax: ¶meter=`value`, there can be as many parameters as necessary.
¶meter=`value` <-- Let's look closer at this and break it down.
First thing to take notice is that each parameter name has a & before it (no spaces in between). This is important since this identifies each individual parameter to the MODx parser.
Next we see the actual parameter name, which will, in general, correspond to a variable within the snippet itself (as defined by the snippet author). This is then followed by an equal sign = and a value contained within back-ticks `` (not single quotes). The back-tick key can be found in the upper left corner of your keyboard. The value within the back-ticks is the value for the parameter. This value can be anything from a string, a chunk, a document or template variable, or even another snippet. Here are some examples:
¶meter=`string`
¶meter=`{ {chunk_name}}`
¶meter=`[*document_or_template_variable*]`
¶meter=`[ [Snippet? ¶m=`value`]]` <- notice the back-ticks around the entire snippet call. Also note that when nesting snippets within snippets you need to alternate the cache settings with the outside snippet cached [[ ]] and the nested one uncached [! !].
In some cases you can also use a binder like @EVAL or @CODE as a parameter values. For example:
¶meter=`@EVAL date()` <- this is PHP to be executed and the parameter will be the value returned from the PHP.
Learn more about the different MODx tags: http://modxcms.com/modx-tags.html
Learn more about data Binders: http://www.modxcms.com/data-binding.html
A parameter can be any bit of data that the snippet requires to make the snippet work. There are basically two categories of parameters, input and output. The input parameters refer to data that the snippet needs in order to perform it's specific function. This will normally be stuff like document ID, depth level, sorting and filtering information etc...
Output parameters (could also be called display parameters) refer to how the snippet will present the results of the snippet's logic. The most common output parameter is the "tpl" or template chunk. This parameter will refer to the chunk that holds the output HTML "template". Here is a basic example of a tpl parameter call:
&tpl=`chunkName`
In order for this to work the corresponding chunk needs to exist and have the correct format for the particular snippet's output.
Some snippets have a simple single "tpl" output while others (notably Wayfinder) have multiple "tpl" structures as well as other output related parameters like css classes etc... Read up on the documentation for each snippet to learn more about the particular structure available. Note that the template chunk may not be named tpl, it is up to the snippet's author what it will be named.
The config file
Most of the complex snippets (ex: Ditto and Wayfinder) allow the use of a config (or configuration) file where you can store the snippet parameters. This is a great feature for reusing common setups as well as keeping the call parameters tidy. Look into each snippets documentation to learn if it has config file support as well as the proper syntax.
Troubleshooting snippet calls
The most common problems are typos (double check the spelling), missing back-ticks and missing & before each parameter.
Snippets and the MODx Cache
If a document is cacheable then the snippets on that document need to be called as unchacheable [! !]. This is true of any interactive snippets, or snippets that will fetch dynamic content, such as forms or feed readers.
If the page with the snippet output is cached, the page is served next time without processing the snippet, which means there's nobody listening to the POST from the form.
Calling the snippet uncached means that even if the page is cached, any uncached snippets will be processed, and then it will pick up the POST and generate the appropriate output.
Embedding Snippets in a parameter
If embedding snippets within snippets remember to alternate the cache setting by setting the outer snippet to cached [[ and the inner one to uncached [!. For example:
[[Wayfinder? &startId=`[!UltimateParent!]`]]
Snippet Calls vs. Setup Wizards
At first I would ask "wouldn't it be better to have setup wizards instead of snippet calls?" However, after getting some experience, you will find that the snippet call allows: 1) much more flexibility allowing you to tweak every parameter; 2) easy to develop...Why is this important, well imagine if every snippet developed for MODx required an input module "wizard". Being a volunteer community this would greatly limit who could develop snippets. By adopting the call method MODx opened up the door for any php enthusiast, from the seasoned pro to the amateur. When you look at it this way it really makes a lot of sense and opens up a lot of doors for snippet developing.
As you can tell the call structure for snippets is very flexible and allows you to easily use, customize as well as develop powerful snippets. It is a good idea to feel comfortable with snippets and the call structure since this is one of the base concepts for MODx development. Hope this helps understand the snippet call and take the edge off of using them.
For learning about how to build a snippet read the "Creating Snippets" article in the wiki:
http://wiki.modxcms.com/index.php/Creating_Snippets
Also check out Bob's Guides guide to snippets:
http://bobsguides.com/modx-snippets.html
Learn more on how the MODx Parser works (and other great stuff):
http://sottwell.com/how-modx-works.html
Categories: Tips | HOWTO
