Placeholders used by MODx Pages and Templates

From MODx Wiki
Jump to: navigation, search


Please note that Revolution uses slightly different versions of these placeholders. See Revolution Placeholders.

What you might call a "placeholder" is not necessarily what MODx would call a placeholder, but this page uses that term in its title so this page is more easily found by newcomers. The different tags used in MODx have specific names according to their usage, but all of them denote a place where substitution will occur, e.g. [*pagetitle*] might become "This is My Page". The most common tags that appear in templates are technically named "Template Variables"; that's not the most obvious search term, but once you know it, you can find other references to help you understand them.

This page attempts to document the Template Variables used by MODx by augmenting and clarifying the official documentation of MODx tags (ack... the page moved... new link required). The Template Variables are what makes a template a template instead of merely static text.

You'll notice MODx has several different flavors of MODx tags, some more complex than the above [*pagetitle*] example. Usually the tags use some kind of square or curly bracket combinations such {{footer}} or [*content*], 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

Built in Document Object fields

The Document Object 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.
  • [*id*] = the unique numerical identifier of the document.
  • [*parent*] = the unique numerical identifier of the document's parent.

A common use of the [*id*] and [*parent*] placeholders is to create links. This can be achieved via [~[*id*]~]. See the section below about links.

NOTE: 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 -- you can create any Template Variable you want to extend the placeholders available to your documents. 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. Examples:

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

REMEMBER: you have to create these yourself... a default install won't have any of these added by default.

System Settings

These are used to read configuration details about MODx. Sometimes thought of as "global" in scope, these store information about the system that is running 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 call to a Snippet (and the Snippet will execute PHP code). Basically, you create a 'chunk' of static text, then reference its name with the double-curly brace {{like_this}}. The [(system_settings)] are still parsed inside the chunks. You can define as many of these as you want. Here are some common examples:

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

Not only can Chunks be included directly in a page content or in a page's template, they are also frequently used to format the output of Snippets. When they are used to format Snippet output, Chunks frequently employ placeholders in the [+placeholder+] syntax. When a tag uses that format, it really is a placeholder; Placeholders are just that: they hold the place where some variable value will go. A common example of a Chunk used to format Snippet output are the various Tpl named Chunks used to format the output of the Wayfinder Snippet. Often Snippets use parameters named with Tpl in their name when referring to a Chunk; this is because when they are used in this way, a Chunk is really a mini-template (and Tpl is short for Template).

Snippets (Samples)

These are PHP scripts that usually produce output of some sort (i.e. PHP functions). The double-square bracket [[snippet_names]] are replaced by the output of the function. A Snippet is a bit of reusable code (you can remember it remembering the double P: sniP(h)Pet). 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 (&).

A great way to learn about Snippets is to examine the built-in Snippets that are used in the demo site (which you can choose to install when you install MODx).

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~]"

Often these get combined with the [*id*] or [*parent*] tags to create links to a page or its parent, e.g.

[~[*id*]~]

META tags

These are the black sheep of the otherwise uniform MODx substitution methods.

To view or edit these, navigate here inside the manager control panel: Resources --> Manage META tags and Keywords

These aren't typical placeholders really because you don't actually put in a block demarking where substitution should occur, but like the other placeholders listed on this page, the META tags do allow you to utilize 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' tab and add the 'JFK author tag' to the page.

What is completely tricky about these is that they DO NOT rely on a Template Variable or a [*block*] of text. They just get inserted immediately after your HTML document's opening head tag (surprise!!). 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 written PHP, and in many ways they are similiar to Snippets except that you can choose when a Plugin is executed: you choose from a list of available System Events whereas Snippets are simply executed when a page loads. Plugins are more low-level and they tend to do more "invisible" things; Snippets usually print their output to the page, so Snippets are a bit easier to understand.

Modules

A Module is a collection of resources (e.g. plugins, snippets, etc). In the simplest implementation, it is like a Snippet, but rather than executing on the front-end when a page loads, it executes ON DEMAND inside the manager control panel. Have a look at the existing modules, e.g. Doc Manager. It runs when you click it.

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~]
  1. foreach ($modx->documentListing as $linkAlias=> $linkDocId) {
  2. $modx->setPlaceholder("alias:{$linkAlias}", "{$linkDocId}");
  3. }
Personal tools