If none of the available output modifiers do what you want, MODX Revolution allows you to create your own custom output modifier. If MODX doesn’t recognize the name of a modifier it finds in a tag, it looks for a snippet with that name and runs it. The snippet will receive the result of the tag as $input and can process that variable. If the snippet returns a value, the tag will be replaced by whatever the snippet returns. If the snippet doesn’t return a value (or can’t be found), the tag will be processed as if the modifier were omitted.
Let’s say you want to have a chunk that mentions MODX many times. You realize that you’ve spelled it modX, however. You could edit the chunk, but here’s how to correct it with a custom modifier. First, create a snippet called co rrectjn o d x containing the fol
lowing line of code. This is a good time to use the Quick Create Snippet command. Go to
the “Elements” tab at the left in the MODX Manager, right-click on “Snippets,” and select
“Quick Create Snippet.” Fill in the name (co rrectjn o d x ) and the line of code below, and click on the “Save” button.
return str_replace('modX',’MODX',$input);
Then, wherever you have a tag referring to the chunk that needs correcting, add the co rrectjn o dx modifier to it:
[[$ChunkName:correctjnodx]]
For a more practical example, let’s look at a custom modifier that will highlight the output of a chunk or snippet by surrounding it with <strongx/strong>. Create a snippet called high Light containing the following code:
<?php
/* highlight Snippet */
return ’<strong>' . $input . '</strong>’;
?>
Now, to highlight your output, just add the highlight custom modifier at the end of the snippet or chunk tag:
[[SnippetName:highlight]]
[[iChunkName:highlight]]
You can also include information for the custom modifier in your modifier reference. It will be available in the modifier as the $options variable. Using the following tag, for example, the $options variable will contain ' optionl,option2' as a string.
[[SnippetName:customjnodifier_name-' optionl,option2' ]]
The snippet code would have to parse the $options variable to separate the two options (e.g., with the PHP explode () function).
If we wanted to send the type of tag to be used as a property to the highlight snippet we created above, we could change the snippet code to:
$output = '<’ . $options .
$output .= $input;
$output .= '</' . $options .
And use a tag like this:
[[iChunkName:highlight^ strong']]
In addition to the $input and $options variables, the following variables are also available in a custom modifier snippet:
» $token — The token at the beginning of the tag (e.g., $, ++, +, etc.); empty for snippets.
• $name — The element name at the beginning of the tag (e.g., the snippet or chunk name).
■ $tag — The complete contents of the tag containing the modifier.
You can add any of the standard output modifiers after your custom modifier to further modify the output:
[[SnippetName:custom_modifier_name:ucase]]
Technically, MODX also has Input filters in addition to the default output filter containing the output modifiers we’ve discussed. The default input filter simply parses the tag in preparation for the output filter. Custom input filters that act on the element before it is processed are possible but are beyond the scope of this book.
Weblinks
A weblink is a MODX resource that contains a URL or MODX link tag in its Resource Content field. Note that although the link is stored in the content field in the database, on the Create/Edit Resource panel, the field label is Weblink.
With a weblink, the URL can be to a page at the MODX site or any other site on the Web.
The main use of weblinks is to make pages from other parts of the site show up in menus created with Wayfinder or another menu snippet. If you have a Contact page, for example,
doesn’t contain the contact resource), you can add a weblink tied to the Contact page to that part of the tree. You can also add links to pages at any other site to your menus by creating weblinks for them.
If you’re familiar with (X)HTML, you’ve created plenty of links already. Because a weblink is a MODX resource, however, it comes with many useful features not available with a standard (X)HTML link. It will have all the standard fields of a Resource. You can make it published or unpublished, for example, and you can give it a future publish or unpublish date.
A weblink can have a Title, a Long Title, and a Summary, although these have limited use since the user is actually forwarded to the page specified in the URL or link tag. They are available to snippets and plugins, however. The weblink’s Menu Title and Menu Index fields, for example, could be used by menu and sitemap snippets.
You can also designate whether the weblink will be hidden from menus, and you can use the MODX permission system to make it unavailable to unauthorized users. If the weblink is unpublished, for example, and the document it refers to is published, a user accessing the weblink directly or via a link will not reach the page the weblink refers to. Instead, they’ll be directed to your error (Page Not Found) document.
if the weblink is to a page on the MODX site, the template used will be that of the target page rather than the template of the weblink.
Symlinks
Like a weblink, a symlink refers to another page. Unlike weblinks, however, the page must be on the MODX site. Since symlinks are also MODX Resources, they also have all the characteristics we discussed for weblinks in the previous section.
There are two important differences between weblinks and symlinks. First, while web
links are specified by a full URL or a MODX link tag, symlinks are specified simply by the Resource ID of the document being referred to. In other words, what goes in the Symlink field on the Create/Edit Resource panel is just a number rather than a URL or link tag.
Second, while a weblink actually forwards the user to the page referred to, a symlink pulls that document into the URL of the symlink itself. In other words, when the user reaches the
target page, the URL shown in the browser’s address window will be that of the symlink.
One use of symlinks is to allow you to serve the same page in different parts of your menu structure without duplicating the page.
Unlike weblinks, the template used will be that of the symlink rather than the template of the target page.