Placeholders used by MODx Pages and Templates

From MODx Wiki

This page attempts to document the placeholders used by MODx by augmenting and clarifying the official documentation of MODx tags. Technically, the term placeholders is incorrect because MODx uses that term to refer specifically to the [+something+] style tags that are replaced by the execution of a PHP snippet, but for the sake of simplicity and easy searching, I'm going to use the term in its general definition. The placeholders are what makes a template a template instead of merely static text. The concept is simple to understand: e.g. if [FIRST_NAME] is our placeholder, then "Hello, my name is [FIRST_NAME]" becomes "Hello, my name is Bob" when the sentence is parsed using 'Bob' as the value for [FIRST_NAME].

You'll notice MODx has a lot of different flavors of placeholders, more complex than the above example. Usually they are surrounded by some kind of square or curly bracket combinations, and in that way, the behavior is pretty similar to a lot of templating software on the market (e.g. PHP's Smarty, or Perl's Template Toolkit).

For a step-by-step guide for creating a template, please refer to Beginner's Guide to MODx

Contents 1 Template Variables (built in) 2 Template Variables (custom) 3 Configuration Variables 4 Chunks 5 Snippets (Samples) 6 System Info: PHP and MySQL 7 Links 8 META tags 9 Plugins 10 Modules 11 Placeholders

Template Variables (built in)

These values are probably the first things you think of when you think of what values might be abstracted into a variable. They correspond to the fields visible when you edit a document in the control panel.

• [*pagetitle*] = page title
• [*longtitle*] = often h1 or h2
• [*description*] = this can be a handy one to use in a meta description, RSS feeds, or with the Ditto Snippet.
• [*introtext*] = a.k.a. Summary; also may be useful to creating RSS feeds or Ditto Snippets.
• [*content*] = the content of the document.

Variables that can be edited using the Quickedit module/plugin may have a "#" after the "*" like so: [*#content*]

Template Variables (custom)

The format here is the same as the "standard" template variables. Template Variables must be assigned to templates in order to access them from snippets and documents. They are essentially the same as the "standard" variables, but they are scoped to a specific template(s). See Template Variables for more information.

See admin control panel: Resources --> Manage Resources --> Template Variables Notice that the convention is to use camel-case (lowercase first, then Uppercase) with no spaces. Built-in examples:

• [*loginName*]
• [*blogContent*]
• [*documentTags*]

Configuration Variables

These are used to read configuration details about MODx.

• [(site_name)] = The name chosen for this configuration
• [(site_url)] = e.g. href="[(site_url)]"
• [(site_start)] = The ID of the homepage
• [(base_url)] = e.g. href="[(base_url)]assets/templates/default/modx.css"
• [(modx_charset)] = Character set, eg. a meta tag with content="text/html; charset=[(modx_charset)]"

Chunks

Chunks are 'raw' HTML code, so any raw PHP code won't be processed directly. You can, however, include a snippet and any PHP code in the snippet will run. Basically, you create a 'chunk' of static text, then reference its name with the double-curly brace {{placeholders}}. The global [(placeholders)] are still parsed inside the chunks. You can define as many of these as you want, but here are the most common:

• {{meta}}
• {{footer}}
• {{styles}}

Chunks can also make use of the special [+placeholders+]. This is used e.g. to create a customized menu with Wayfinder.

Snippets (Samples)

These are PHP scripts that produce output of some sort (i.e. PHP functions). The double-square bracket [[placeholders]] are replaced by the output of the function. Why they're called snippets, I don't know. These PHP functions can be passed variables in a format that resembles the standard CGI format, but with a couple key differences (see the Snippets page for more details on passing values to a Snippet):

1. The values are often quoted with back-ticks,
2. Each name in the name/value pair MUST be preceded by an ampersand (&).

Example Snippet Call:

  [[my_snippet? &variable1=`value1` &variable2=`value2`]]
 

Snippets can either be cached or un-cached.

Cached:
[[double-square-bracket]]
Un-cached:
[!square-bracket-exclamation-point!]

* A simple mnemonic is that the exclamation point is used in almost every programming language as a synonym for 'NOT'.

What's the difference? Say I have a snippet named random_number that prints out a random number between 1 and 10. If I call it using [[random_number]], I will get the same number each time the page reloads until the page is re-cached. If I use [!random_number!], each page load will generate a new random number.

Shows the most recent documents

• [[ListIndexer?LIn_root=0]]

Shows the Ajax search box (notice, this is not cached):

• [!AjaxSearch? ajaxSearch=`1` &AS_landing=`8` &moreResultsPage=`8` &showMoreResults=`1` &addJscript=`0` &extract=`0` &AS_showResults=`0`!]

Drop Down menu Creation (Wayfinder):

• [[Wayfinder?startId=`0` &outerTpl=`mh.OuterTpl` &innerTpl=`mh.InnerTpl` &rowTpl=`mh.RowTpl` &innerRowTpl=`mh.InnerRowTpl` &firstClass=`first` &hereClass=``]]

Contact Us page:

• [[ContactForm? &sendTo=`[(emailsender)]`]]
• [!eForm? &formid=`ContactForm` &subject=`[+subject+]` &to=`[(email_sender)]` &ccsender=`1` &tpl=`ContactForm` &report=`ContactFormReport` &gotoid=`46` !]

Login form for web page (User & Password)

• [!WebLogin? &tpl=`FormLogin` &loginhomeid=`[(site_start)]`!]

System Info: PHP and MySQL

• [^qt^] Query Time (in seconds)
• [^q^] Queries. Number of requests (queries) made for the page-load where this appears.
• [^p^] PHP parsing time (in seconds)
• [^t^] Total load time (in seconds)
• [^s^] Source of the load (usually, this reads 'database', but presumably this could also be 'cache' ???)

Links

Links to documents within your site can be referenced using the document's unique ID (this is the primary key from the database). You can see the document IDs in the document tree in the MODx manager: each page has its name and a number in parentheses, e.g. "Home (1)" -- 1 is the unique ID.

• [~1~] gets parsed out to be the link to your first page e.g. href="[(site_url)][~11~]" or simply href="[~1~]"

META tags

Navigate here via the admin control panel: Resources --> Manage META tags and Keywords These aren't typical placeholders, but they do allow you to use small constants, e.g. Create a new META tag using Name="JFK author tag" Tag="Author" Value="John F. Kennedy" and add the tag. Now when you edit a page, you can go to its 'META Keywords' tag and add the 'JFK author tag' to the page.

What is completely tricky about these is that they DO NOT rely on a placeholder. They seem to just get inserted immediately after your HTML document's opening head tag. If you view the HTML source of any one of the default pages and then examine the code in its template file, you'll be asking yourself "Hey, how did all that stuff get in there?!"

<head>

becomes...

<head>
<meta name="author" content="John F. Kennedy" />
[...]

Plugins

Plugins are 'raw' PHP codes that are invoked whenever the selected System Events are triggered. They are different than Snippets because Snippets are executed when a page loads. Plugins are more low-level. Presumably, their output can be tapped and displayed via a placeholder, but I don't know what that format is.

Modules

A Module is a collection of resources (e.g. plugins, snippets, etc). Again, presumably, the output of a module could end up on any given page, but I don't know the formatting required.

Placeholders

• [+placeholder_name+]

Used for programmatic processing by plugins or snippets. For example in below plugin fragment placeholders like [~[+alias:document_alias+]~] will be replaced by [~document_id~]

foreach ($modx->documentListing as $linkAlias=> $linkDocId) {
	$modx->setPlaceholder("alias:{$linkAlias}", "{$linkDocId}");
}