MODx Tags

Introduction

The core of any templating or content management system is the way it creates blocks of different kinds to separate the presentation of content from the creation of the content. MODx uses simple tags to create content that an editor can insert into a document without having to worry about how that content is created.

MODx Tags give you a simple, powerful way to include more variable content into your web pages.

Tags are replaced with the content they output. Here are a few examples:

• [[snippet]] or [!snippet!] for non-caching snippets Inserts the output of a snippet named 'snippet' into your page.
• [(setting)] Inserts the value of a site-wide setting named 'setting' into your page.
• [*resourceField/TV*] Inserts various blocks of content specific to the page being displayed.
• [^timing^] Shows how long it took to create the current page.
• [~link~] Makes a link to another document in your MODx site.
• { {chunk} } Inserts a chunk of HTML into your page.
• [+placeholder+] Acts as a placeholder for content generated by a snippet. Usually used in a chunk specified in an argument of the snippet to format the snippet's output.

Snippets

To execute snippets, insert the snippet's name in the snippet tag where you want the snippet's output to appear in your document or template. For example, [[MySnippet]]
Snippets are simply raw PHP code whose output is displayed in the location where the snippet tag is placed. For more information see Adding Snippets, as well as Document Caching, in the Designer's Guide.

Settings

Settings tags insert the specified site-wide system setting. For example, [(site_name)] will insert the name of your site. This is often used in page headers.

A list of settings can be found in the MODx database in the table "(PREFIX)system_settings" where (PREFIX) is your table prefix.

Following is a complete list of the settings, with a line through settings that are no longer used as in [(config_setting_name)]:

• [(allow_duplicate_alias)] - indicates if duplicate alias' within different friendly alias paths are allowed.
• [(automatic_alias)] - indicates if alias' are automatically created from the pagetitle.
• [(cache_default)] - indicates the default cache setting for new documents.
• [(captcha_words)] - the words used for Captcha settings when logging into manager.
• [(cm_plugin)] -
• [(custom_contenttype)] - comma-delimited list of the content types served by MODx.
• [(default_template)] - ID of the default template for new documents.
• [(editor_css_path)] - CSS path used by rich-text editors.
• [(emailsender)] - the site's main email address.
• [(emailsubject)] - webuser registration email subject.
• [(error_page)] - the document ID of the site's error page.
• [(etomite_charset)] - character encoding for site.
• [(fck_editor_autolang)] - indicates if FCKeditor is set to auto-detect languages.
• [(fck_editor_style)] - indicates the FCKeditor style to use.
• [(fck_editor_toolbar)] - indicates the FCKeditor toolbar to use.
• [(fck_editor_toolbar_customset)] - indicates custom toolbar set to add to FCKeditor.
• [(filemanager_path)] - root path for MODx filemanager access.
• [(friendly_alias_urls)] - indicates if friendly alias URLs are enabled.
• [(friendly_urls)] - indicates if friendly URLs are enabled.
• [(friendly_url_prefix)] - friendly URL prefix.
• [(friendly_url_suffix)] - friendly URL suffix.
• [(im_plugin)] -
• [(im_plugin_base_dir)] -
• [(im_plugin_base_url)] -
• [(manager_language)] - language for the MODx Content Manager.
• [(manager_layout)] - layout for the MODx Content Manager.
• [(manager_theme)] - theme for the MODx Content Manager.
• [(number_of_logs)] - number of log entries shown per page when you browse the Audit trail.
• [(number_of_messages)] - number of messages to show in inbox when viewing messages.
• [(number_of_results)] - number of results to show in the datagrid when viewing listings and search results.
• [(old_template)] -
• [(publish_default)] - default Published setting for new documents.
• [(rb_base_dir)] - base path for resource browser.
• [(rb_base_url)] - base URL for resource browser.
• [(reset_template)] - indicates if all templates or just documents assigned the current default_template are reset when the default template is changed in the manager.
• [(resolve_hostnames)] - indicates if MODx will try to resolve visitors' hostnames when they visit the site (applies to MODx internal logs).
• [(search_default)] - default Search setting for new documents.
• [(server_offset_time)] - the number of hours time difference between where you are and where the server is.
• [(server_protocol)] - determines if the site uses an http or https (SSL) connection
• [(settings_version)] - MODx version.
• [(show_preview)] - determines if preview is shown when viewing documents in MODx Content Manager.
• [(signupemail_message)] - email message sent to users when registered as a MODx Content Manager user.
• [(site_id)] - (replaceThisText)
• [(site_name)] - the site's name.
• [(site_start)] - the document ID of the site's starting page.
• [(site_status)] - determines if the site is online (1) or offline (0).
• [(site_unavailable_message)] - Message to show when the site is offline or if an error occurs. Note: This message will only be displayed if the Site unavailable page option is not set.
• [(site_unavailable_page)] - ID of the document you want to use as an offline page.
• [(strict_editor)] -
• [(strip_image_paths)] - determines if image paths are rewritten as relative paths when rendering pages.
• [(theme_refresher)] -
• [(tiny_css_path)] -
• [(tiny_css_selectors)] -
• [(top_howmany)] - a setting indicating the number of items to display in summary reports in the manager.
• [(to_plugin)] -
• [(track_visitors)] - determines if MODx should track visitors using it's internal logs.
• [(txt_custom_contenttype)] -
• [(udperms_allowroot)] - indicates if MODx Content Managers can edit files in the root level of the site.
• [(unauthorized_page)] - the document ID of the site's unauthorized access page.
• [(upload_files)] - comma-delimited list of file extensions that can be uploaded via the filemanager.
• [(upload_maxsize)] - maximum bytes for files uploaded via the manager.
• [(use_alias_path)] - indicates if Friendly Alias Paths are enabled.
• [(use_browser)] -
• [(use_captcha)] - indicates if MODx Content Manager login uses Captcha.
• [(use_editor)] - indicates if Rich-Text Editing is enabled for the site.
• [(use_udperms)] - indicates if user permissions are enabled for the site.
• [(webpwdreminder_message)] - email message sent to web users when they forget their password.
• [(websignupemail_message)] - email message sent to new web users following registration.
• [(which_editor)] - indicates which Rich-Text Editor is enabled by default.

Template Variables

TVs are a powerful method of inserting blocks of content specific to the page being displayed. They take two basic forms:

1. TVs can display basic document attributes, which are found in the MODx database in the table (PREFIX)site_content table in the MODx database where (PREFIX) is your table prefix.

These are the most commonly used document attributes:

• [*pagetitle*] - the title of the document
• [*longtitle*] - the long title of the document
• [*introtext*] - the summary of the document
• [*content*] - the content of the document

2. TVs can be programmed to generate widgetssuch as tickers, sliders, marquees, and data grids displaying the results of database queries. They can generate Rich Text Editors for user comments or forum entries.

With TVs, you don't need to be concerned about how these things are created, all you need to do is insert the TV tag where you want the widget to appear in your page.

Many TVs can even be customized for a specific document at the same time you are editing the document. They can provide lists or options you can select to apply to the document you are editing.

For more information see Template Variables in the documentation.

Timing

There are several timing tags in MODx:

• [^qt] - Query Time - Shows how long MODx took talking to the database
• [^q] - Query Count -Shows how many database queries MODx made
• [^p] - Parse Time - Shows how long MODx took to parse the page
• [^t] - Total Time - Shows the total time taken to parse/ render the page
• [^s] - Source - Shows the source of page, whether is database or cache.

For example, for this page, MySQL queries took 0.0000 seconds for 0 queries(s), document parsing took 0.3043 seconds, for a total time of 0.3043 seconds, and retrieved from cache.

Links

To insert a link to another document within your MODx site, simply put the id number of the document in the link tag. For example, [₁₂₃] will create a link to the document with ID 123.

Once MODx starts parsing the document, it will automatically select the best URL to create for this document, where 'alias' has precedence over 'friendly urls', which have precendence over 'index.php?id=123' style links. You can combine this with other tags, so [(site_start)] will output the URL for your site start page.

Chunks

Chunks contain plain text, usually HTML code, which will not be parsed by MODx, but simply inserted into the page.

They are very convenient for holding general content, such as for a page footer, that is to appear on all pages of a site. For example, if your footer contains your telephone number, and your number changes, you only have to make the change in the chunk, and not on every page on the site!

By using combinations of snippets, TVs and chunks, you can make your site pretty flexible! For example, you could have a snippet which outputs the tags for a chunk, which can contain tags for other snippets.

Chunks are also used to contain lists of options for TVs, and the same chunk can be included into any number of TVs to provide the same options (@CHUNK binding).

For more information about Chunks, see Chunks in the documentation.

Placeholders

The most common use for placeholders is to position the output of a snippet. An example of this can be seen in the NewsListing snippet's default template:

<div class="nl_summaryPost">

<h3><a href="[+id+]">+title+</a></h3>

<div>+summary+</div>

<p>+link+</p>

<div style="text-align:right;">by <strong>+author+</strong> on +date+</div>

</div>

A placeholder can be used anywhere in any HTML code where you wish that particular piece of a snippet's output to appear. A good example of that is the Personalize snippet. It merely returns the user's name, and can be used either as a normal snippet or as a placeholder. You can put the snippet once in your template or document, then put the placeholder in as many places as you like, such as in a greeting at the top of the page, and in the "logout" section of the weblogin snippet's template.