MODX Evolution Content Editors Guide

Jan 09, 2010

This guide was written in September 2009 by Valeska Scholl - [email protected]. It was published as a PDF for MODx Evolution 1.0.0.


This guide was converted to html in January 2010 by AMDbuilder - [email protected]. This guide has been reformatted to better display online and the information updated to reflect some changes between the current release (1.0.2) and documented version.

The original guide PDF can be downloaded here.

MODx Content Management System 1.0.0
Content Editor’s Guide

  1. Introduction
    1. Purpose of This Guide
    2. Target Audience
  2. MODx Terminology
  3. Introducing the MODx Content Manager
    1. What is the Content Manager?
    2. Accessing the Content Manager
      1. Address of the Content Manager
      2. Logging In
    3. Content Manager Screen Layout
    4. An Overview of the Tabs
      1. The Site Tab
      2. The Elements Tab
      3. The Tools Tab
      4. The Reports Tab
  4. Managing Content
    1. Using the Site Tree
      1. What is the Site Tree?
      2. The Quick Buttons
      3. Understanding the Site Tree
      4. Sorting the Site Tree
    2. Using Resources (Webpages and Weblinks)
      1. What is a Resource?
      2. Viewing an Existing Resource (Summary Mode)
      3. Viewing an Existing Resource (Preview Mode)
      4. What is a Weblink?
      5. Creating a New Weblink
      6. Editing an Existing Weblink Resource
      7. What is a Webpage?
      8. Creating a New Webpage Resource
      9. The Rich Text Editor
      10. Editing an Existing Webpage Resource
      11. Moving a Resource (Webpage or Weblink)
      12. Deleting a Resource (Webpage or Weblink)
      13. SPECIAL NOTE: FirstChildRedirect
    3. Using Chunks
      1. What is a Chunk?
      2. Accessing Chunks
      3. Making a New Chunk
      4. Editing an Existing Chunk
      5. Deleting a Chunk
      6. Using a Chuck in a Resource (Webpage)
    4. Using Snippets
      1. What is a Snippet?
      2. Accessing Snippets
      3. Making a New Snippet
      4. Editing an Existing Snippet
      5. Deleting a Snippet
      6. Using a Snippet in a Resource (Webpage)
    5. Using Files
      1. Accessing the File Manager
      2. Viewing a File
      3. Editing a File
      4. Uploading a File
      5. Deleting a File
      6. Creating a New Directory
    6. Using Meta Tags and Keywords
      1. Accessing the Meta Tags and Keywords Manager
      2. Managing META Tags
      3. Managing Keywords
      4. Using META Tags and Keywords in Resources
  5. Other Functions
    1. The Tools Tab: Import HTML Files
    2. The Reports Tab: Scheduled (Un)Publications
    3. User Administration
      1. Accessing User Administration
      2. Changing Your Password
      3. Accessing Messages
      4. Accessing Help Files
      5. Logging Out
      6. Other User Administration Functions
  6. Appendix I: Editor Styles & Tricks
    1. Applying and Removing Styles
      1. Applying a Style
      2. Removing a Style
    2. Adding and Deleting Styles
      1. Adding Styles
      2. Deleting Styles

I.Introduction

1. Purpose of This Guide

This guide will:

  • Introduce the MODx Content Manager
  • Explain the various Manager screens
  • Detail how to create content in MODx

This guide will not address:

  • How to create or modify Templates, Modules, or Plugins
  • Functions present on the ‘Tools’ Navigation tab
  • Fuctions present on the ‘Security’ Navigation tab

These areas are the domain of a technical web administrator, not a content editor. Technical documentation on these areas can be found on the MODx official website ( www.modxcms.com)

2. Target Audience

This document is aimed at content editors: people who are concerned with the making of webpage content on a MODxbased site. This document is not aimed at website developers: people tasked with the installation, configuration, and theming (CSS design) of a MODx based website.

3. About the Author

Valeska Scholl is an American web designer and technical writer currently living in Flanders, Belgium. She has over twelve years’ experience in various aspects of IT, including five years as a documentation specialist for an international computer hardware manufacturing company and three years (and counting) as a web design and development specialist. She can be reached via email at [email protected] or at www.smalldog.be

II. MODx Terminology

The majority of the words and terminology used in the MODx Content Management System are self explanitory. However, there are some special uses of terminology which require special note:

Child - A child is any Resource which is contained within another (parent) Resource. To use more generalized computer terminology, it is an item in a folder. A Resource can be both a child and a parent at the same time.

Chunk - A Chunk is a predefined piece of raw (X)HTML and/or Javascript code that can be reused later in other resources. It may containt clientside scripting (Javascript), but cannot contain serverside scripting (PHP).

Container - A container is a Resource which contains another Resource. This is another word for ‘parent.’

Element - ‘Element’ is a generic term for any content which is not a Resource. Content editors may only access ‘Chunk’ and ‘Snippet’ elements.

File - A file refers to an actual physical file of any type which exists on the webserver. This is in contrast to Resources, which are held in the website database rather than as distinct files on the webserver.

Parent - A parent is a Resource which contains another (child) Resource inside of it. To use more generalized computer terminology, it is a type of folder. A Resource can be both a child and a parent at the same time.

Resource - ‘Resource’ is MODx’s generic term for any web content; that is, content which is 1) stored in the MODx database rather than in a file on the webserver, and 2) which is potentially visible to webpage visitors. All webpage documents created in MODx are Resources, as are all Weblinks.

Snippet - A Snippet is a predefined piece of PHP code that can be reused later in other resources.

Template - A template is a set of web resources which, together, form a theme or a skin for the website. A template typically includes customized images, a customized layout file, and a customized CSS file.

Weblink - A weblink is a URL which is stored as a Resource so that it can later be used in menus, navigation, or other Resources. Weblinks can either be to external webpages (e.g. Google) or internal Resources (e.g. your company’s “Contact Us” page). It is not necessary that all URLs included in a webpage be first saved as Weblinks!

III. Introducing the MODx Content Manager

1. What is the Content Manager?

The Content Manager is the main administrative area for managing your website. In this guide, only functions related to the creation and maintenance of content will be addressed.

2. Accessing the Content Manager

a. Address of the Content Manager

The Content Manager is available at http://www.yoursite.com/manager where http://www.yoursite.com is the address of your website’s MODx installation. Note that if your MODx installation is in a subdirectory (e.g. http://www.yoursite.com/modx/), then the Content Manager will also be located in this subdirectory (e.g. http://www.yoursite.com/modx/manager).

b. Logging In

  1. Go to http://www.yoursite.com/manager, as described above.
  2. Enter your username and password in the login screen.
  3. Checkmark the ‘Remember Me’ box (optional)
  4. Click ‘Login’.

Note: Only ‘Manager’ users may access the Content Manager.

3. Content Manager Screen Layout

After logging in, you will see the main Content Manager screen. This screen is made up of five (5) main areas of content, visible on the screenshot below.

1. Main Navigation

The Main Navigation tab row contains the following sections:

  • Site - Controls creation, editing, and deletion of site content (webpages).
  • Elements - Controls nonwebpage site content such as Chunks and uploaded files.
  • Tools - Controls backups and import/export of HTML files.
  • Reports - Provides statistic and logging.
  1. Sub Navigation - The SubNavigation row is context sensitive. It will display different options depending which Main Navigation tab is selected.
  2. Site Tree - The Site Tree displays a tree structured list of all webpage content currently stored in the site, including nonpublished, published, and softdeleted items. It also contains navigational buttons to collapse and expand the site tree, add or remove content, and hide the Site Tree entirely if desired.
  3. Content Window - The Content Windows displays the main content of the navigational area or document which you have selected.
  4. User Administration Bar - The User Administration Bar allows the currently logged in user to change their password, check their messages, access the Help files, or logout. It also displays the installed version of MODx.

4. An Overview of the Tabs

a. The Site Tab

a.i. Home

The Site > Home tab is the first window which you see after logging in to the Content Manager. It contains a small ‘subsubnavigation’ area with six additional tabbed options.

  • Website Tab - The website tab is the first available tab, and is titled with the name of your website (‘Actonomy’ in the screenshot above). It contains shortcut links to various administrative tools, such as security settings, user management, and your personal system mailbox.
  • MODx News - Displays a daily updated news feed of articles from the “MODx Announce” mailing list. These news items contain recent information about MODx and its development.
  • Security Notices - Displays MODx official announcements regarding security vulnerabilities, exploits, patches, and software upgrades.
  • Recent Resources - Displays the most recently created and/or editted documents in your website.
  • Info - Displays statistical information about the currently logged in user.
  • Online - Displays a list of all users currently logged into the website.
a.ii. Preview

The ‘Preview’ subnavigation tab opens your website in a new browser window, allowing you to see the current version of your website.

a.iii. Clear Cache

Documents are stored in the MODx cache system to speed up the response time of the website. However, if cache files become outdated or too numerous, the website may display inaccurate information or experience slow response times.

The ‘Clear Cache’ subnavigation tab refreshes the internal database of the site, checking for changes in content and removing any old, unused cache files or deleted documents. In doing so, it ensures that all displayed data on the website is the most recent version.

a.iv. Search

The ‘Search’ subnavigation tab allowed you to search the content of your site for specific resources (documents), either by Resource ID, title, longtitle, or text present in the content of the document itself.

a.v. New Resource

The ‘New Resource’ subnavigation tab opens the ‘Create Resource’ screen. An indepth guide to creating Resources can be found in Section IV.2.

a.vi. New Weblink

The ‘New Weblink’ subnavigation tab opens the ‘Create Resource’ screen for weblinks. An indepth guide to creating Resources can be found in Section IV.2.


b. The Elements Tab

The Elements tab allows you to create, manage, and delete the following:

  • Chunks (see Section IV.3)
  • Snippets (see Section IV.4)
  • Files (see Section IV.5)
  • Meta Tags and Keywords (see Section IV.6)

c. The Tools Tab

The Tools tab is used to import HTML files into your MODx site. More detailed information about the Tools tab can be found in Section V.1.

d. The Reports Tab

The Reports tab allows you to access the Schedule. The Schedule displays information about Resources which are pending publication or unpublication at a future time.

More detailed information about the Reports tab can be found in Section V.2.

IV. Managing Content

1. Using the Site Tree

a. What is the Site Tree?

The Site Tree is the left most area of the Content Manager and the primary means of navigating through your website. It shows a list of all Resources present in the website as well as a row of ‘quick buttons’ to assist you in managing your Resources and content.

b. The Quick Buttons

The Quick Buttons are the row of small icons across the top of the Site Tree. Hovering your mouse over an icon will reveal its name and function.

The Quick Buttons are, from left to right:

  1. Expand Site Tree: Expands all parent Resources and shows their children.
  2. Collapse Site Tree: Collapses all parent Resources and hides their children.
  3. New Resource: Creates a new Resource (Webpage)
  4. New Weblink: Creates a new Weblink Resource.
  5. Refresh Site Tree: Refreshes the Site Tree so that any changes to Resource status or organization are visible.
  6. Sort Site Tree: Opens a ‘sort’ dialog which allows you to change the sort method used to display the documents.
  7. Purge Deleted Resources: Permanently removes (‘purges’) any Resources which have been deleted.
  8. Hide Site Tree: Removes the Site Tree from view.

c. Understanding the Site Tree

The Site Tree gives a great deal of information at a glance.

  1. The Site Root: The top level of the Site Tree; it is always visible. This is usually the name of your website.
  2. Resource Name and ID: The name and unique ID number of a resource. The unique ID number is contained in parenthesis after the name. E.g. Home (1)
  3. Hierarchical Structure: The Site Tree uses an indented ‘folder tree’ structure to display which Resources contain (are parents of) or are contained in (are children of) other Resources.
  4. Resource Status: Published resources are listed in black, normal type. Unpublished resources are listed in gray, italic type. Resources which have been deleted but not yet purged are listed in red, strikethrough type.

By clicking on the name of a Resource in the site tree, you can view more detailed information about that particular Resource.

d. Sorting the Site Tree

The Site Tree can be sorted in several different ways to make finding your content easier.

  1. Click the “Sort Site Tree” Quick Button (see Section IV.1.b).
  2. Select the field by which you wish to sort in the top box. E.g. “Folder” or “Creation Date”
  3. Choose either “Ascending” or “Descending” for the sort pattern.
  4. Click “Sort the Site Tree”

2. Using Resources (Webpages and Weblinks)

a. What is a Resource?

MODX refers to all content which can potentially be viewed by a webpage visitor, as a “Resource”. There are two types of Resources in MODx: documents (also known as webpages) and weblinks.

b. Viewing an Existing Resource (Summary Mode)
  1. Use the Site Tree to navigate to the Resource you wish to view. (See Section IV.1)
  2. Click on the desired Resource. The Page Data screen will open.

The Page Date screen lists all fields available for a resource and the current values for those fields. If a value was not set for a Resource, it will appear as (Not Set).

The additional tab “View Children” will show links of any Resources which are ‘subitems’ of the Resource you are viewing.

The additional tab “Source” will display the actual source code of the resource, if (and only if) the page is currently being held in the MODx webpage cache.

c. Viewing an Existing Resource (Preview Mode)
  1. Use the Site Tree to navigate to the Resource you wish to view. (See Section IV.1)
  2. Click on the desired Resource. The Page Data screen will open.
  3. Click the “Preview” button in the upper right corner.

If the Resource is a Weblink, “Preview” will take you directly to the target of the Weblink, whether that is a site internal document or a third party webpage or file somewhere else on the internet (see Section IV.2.d – “What is a Weblink?”)

If the Resource is a Webpage, “Preview” will take you to an “enduser” view of how the document will appear when published and available on the website.

d. What is a Weblink?

A Weblink is a reference (a link) to an object somewhere on the internet. This can be a link to a page on your own website, a link to another webpage, or a link to a file, image, or other content somewhere on the internet.

Weblinks are only useful for adding items to your site’s navigation menu which are actually links to other places. This is due to the internal workings of MODx’s automatic ‘menubuilding’ function. They are not used for creating links inside the site’s actual webpages.

Example: You have a “Company” selection on your main site navigation tree. Under this section you wish to have a subnavigation menu with the pages “About Us”, “Contact Us”, and a link to your parent company, Brand X. The “About Us” and “Contact Us” pages will be actual Webpage Resources, while the link to your parent company will be a Weblink Resource.

However, on the “About Us” page, you also wish to mention and link to your parent company. Inside the “About Us” page, you will not use the Weblink Resource. Instead, you will use a normal hyperlink (see Section…)

e. Creating a New Weblink

New Weblinks can either be created at the root level of the main site, or as a ‘child’ to another resource.

Creating a Weblink at Root Level:

  1. Inside the Content Manager, click the “Site” navigation tab.
  2. Click “New Weblink”. The “Create Resource” screen will open.

Creating a Weblink as a Child:

  1. Use the Site Tree to navigate to the Resource you wish to view. (See Section IV.1)
  2. Click on the desired Resource. The Page Data screen will open.
  3. Click the “View Children” tab.
  4. Click “Create Weblink Here.” The “Create Resource” screen will open.

Note: You can also create a new weblink by duplicating an existing weblink. This is done by viewing the existing weblink (see Section IV.2.b) and clicking the “Duplicate” button in the upper right corner.

The ‘Create Resource’ screen has three distinct tabs: General, Page Settings, and META Keywords. The “META Keywords” tab is identical for both Weblink Resources and Webpage Resources. The other tabs are different between the two Resource types.

e.i. The General Tab

The General Tab for Weblink Resources contains a list of basic information used to display the Weblink.

  • Title: The name of the Weblink as it will appear in the Site Tree
  • Long title: A longer, userfriendly title. By default not visible to site visitors.
  • Description: A description of what the link does or where it goes. By default not visible to site visitors.
  • Resource’s Alias: All resources are stored internally with ID numbers (e.g. http://www.yoursite.com/12). An Alias allows you to assign a userfriendly name to the Resource instead (e.g. http://www.yoursite.com/favorite_links)
  • link Attributes: Attributes to be added to the link, such as “target” and “class” declarations. These attributes must be valid HTML attributes.
  • Weblink: If the Weblink is directed towards a page or item which is not part of your website, this must be the full URL of the target item. If the Weblink is directed towards a page or item within your website, this must be the numeric ID of the target Resource (e.g. 7)
  • Summary: A brief text description of the link or its content. By default not visible to site visitors.
  • Uses Template: Used to select which template (layout/style combination) will be used to display the content of the weblink.
  • Menu Title: The name of the weblink as it will appear in a menu list.
  • Menu Index: Controls the ordering of an item in a menu list. “1” would be the first item in a list, “2” the second, etc.
  • Show in Menu: Determines whether or not the weblink appears in a menu list.
  • Resource Parent: Determines where in the site hierarchy the weblink is positioned.

e.ii. The Page Settings Tab

The Page Settings tab contains “nonvisible” information used for internal management of the Weblink.

  • Container? Specifies whether the Weblink ‘contains’ other Resources. This is only useful in constructing navigation menus. “Contained” resources will appear as submenu items of the Weblink.
  • Rich Text? Specifies whether the Weblink contains Rich Text formatting. By default it is checked; however, as Weblinks contain no actual content, the setting is not actually used.
  • Published? Determines whether the Weblink is visible to site visitors.
  • Publish Date: If the Weblink is not published and a Publish Date is entered, then the Weblink will automatically become published (visible) upon that specific date.
  • UnPublish Date: If the Weblink is published and an Unpublish Date is entered, then the Weblink will automatically become unpublished (invisible) upon that specific date.
  • Searchable: Determines whether or not the site’s “Search” function (if enabled) will return the Weblink as a possible result.

e.iii. The META Keywords Tab

The “META Keywords” tab controls what (if any) META Tags and Keywords are associated with a document.

See Section 5.d. (“Using META Tags and Keywords in Resources”) for instructions on how to use META Tags and Keywords.

f. Editing an Existing Weblink Resource
  1. Use the Site Tree to navigate to the desired Weblink. (See Section IV.1)
  2. Click the Weblink. The Page Data screen will open.
  3. Click “Edit” in the upper right corner.
  4. Change the desired field(s).
  5. Click “Save” in the upperright corner.

Note: It is not necessary to click “Save” after editing each individual tab (“General”, “Page Settings”, “META Keywords”). As long as you click “Save” before navigating away from the Weblink (by opening another screen or another document), any changes to all three tabs will be saved.

g. What is a Webpage?

A webpage is a Resource which has content of its own (rather than being a redirection or ‘pointer’ to another document; i.e. a Weblink). Webpage Resources will make up the vast majority of your sites content, and are used to create all the pages that your website visitors see.

h. Creating a New Webpage Resource

New Resources can either be created at the root level of the main site, or as a ‘child’ to another resource.

Creating a Resource at Root Level:

  1. Inside the Content Manager, click the “Site” navigation tab.
  2. Click “New Resource”. The “Create Resource” screen will open.

Creating a Resource as a Child:

  1. Use the Site Tree to navigate to the Resource you wish to view. (See Section IV.1)
  2. Click on the desired Resource. The Page Data screen will open.
  3. Click the “View Children” tab.
  4. Click “Create Resource Here.” The “Create Resource” screen will open.

Note: You can also create a new webpage by duplicating an existing webpage. This is done by viewing the existing webpage (see Section IV.2.b) and clicking the “Duplicate” button in the upper right corner.

The ‘Create Resource’ screen has three distinct tabs: General, Page Settings, and META Keywords. The “META Keywords” tab is identical for both Weblink Resources and Webpage Resources. The other tabs are different between the two Resource types.

Beneath the tabspecific fields there is also a “Resource Content” area, visible on all three tabs. This is addressed in Section IV.2.i “The Rich Text Editor”.

h.i. The General Tab

The General Tab for a webpage Resource contains basic information for the display and organization of the webpage.

  • Title: The name of the webpage as it will appear in the Site Tree
  • Long title: A longer, userfriendly title. This is used by default as the main ‘header’ text of the webpage.
  • Description: A description of the page’s content or purpose. Not visible to site visitors.
  • Resource’s Alias: All resources are stored internally with ID numbers (e.g. http://www.yoursite.com/12). An Alias allows you to assign a userfriendly name to the Resource instead (e.g. http://www.yoursite.com/favorite_links)
  • link Attributes: Attributes to be added, such as “target” and “class” declarations. These attributes must be valid HTML attributes and affect how the page opens (for instance, when clicked from a menu list).
  • Summary: A brief text description of the link or its content. Not visible to site visitors.
  • Uses Template: Used to select which template (layout/style combination) will be used to display the content of the webpage.
  • Menu Title: The name of the webpage as it will appear in a menu list.
  • Menu Index: Controls the ordering of an item in a menu list. “1” would be the first item in a list, “2” the second, etc.
  • Show in Menu: Determines whether or not the webpage appears in a menu list.
  • Resource Parent: Determines where in the site hierarchy the page is positioned.

h.ii. The Page Settings Tab

The Page Settings tab contains “nonvisible” information used for internal management of the Webpage.

  • Container: Specifies whether the webpage ‘contains’ other Resources.
  • Rich Text: Specifies whether the webpage contains Rich Text formatting. By default this is enabled; however, if the webpage content contains special coding (such as Javascript), you may wish to disable this.
  • Enable Stats Tracking: Logs stastitical information, such as how many visitors view the page.
  • Published: Determines whether the webpage is visible to site visitors.
  • Publish Date: If the webpage is not published and a Publish Date is entered, then the webpage will automatically become published (visible) upon that specific date.
  • UnPublish Date: If the webpaged is published and an Unpublish Date is entered, then the webpage will automatically become unpublished (invisible) upon that specific date.
  • Searchable: Determines whether or not the site’s “Search” function (if enabled) will search within the webpage content.
  • Cacheable: Determines whether or not the webpage may be stored in the site cache. Items stored in cache can be delivered more quickly to visitors; however, if the webpage contains dynamically generated code, it may return out of date results.
  • Empty Cache: Instructs MODx to remove older copies of the document from the cache, after you save changes to the document. This ensures that, after an edit is complete, only the newer version is available for visitors.

h.iii. The META Keywords Tab

The “META Keywords” tab controls what (if any) META Tags and Keywords are associated with a document.

See Section 5.d. (“Using META Tags and Keywords in Resources”) for instructions on how to use META Tags and Keywords.

i. The Rich Text Editor

The Rich Text editor which is built in to MODx is called “TinyMCE.” It is the default editor for webpage content. Most TinyMCE functions should be familiar to due to the software’s strong resemblance to other major word processing programs. Hovering your mouse over an icon will display the button’s function.

As the majority of functions are self explanatory, this guide will only cover the following:

  • Inserting hyperlinks
  • Inserting images and multimedia
  • Editing HTML code
  • Applying styles

i.i. Inserting Hyperlinks

A hyperlink is a weblink to another webpage or file, either within your own website or on another webpage. To insert a hyperlink into a webpage document:

  1. Type the text which you wish to transform into a link (e.g. “Learn more about our company.”)
  2. Use your mouse to highlight the exact words which will become the link. (e.g. ‘our company’).
  3. Click on the chainlink icon.

A new window will appear.

  1. Fill in the data for the link on the General tab.
  2. Click “Insert” to add the link to your document.

The “General” tab is all that is necessary to create a basic web link. There are, however, three additional tabs available:

  • Popup: Used to set a link which functions as a Javascript popup.
  • Events: Used to set ‘onmouseover’, ‘onfocus’, and other events.
  • Advanced: Used to set advanced HTML link attributes, such as target MIME type, CSS classes, tab indexes, and access keys.

If you are not already familiar with the functionality and fields of the Popup, Events, and Advanced tabs, you should avoid using them, as they are meant for advanced users.

j. Editing an Existing Webpage Resource

  1. Use the Site Tree to navigate to the desired Resource. (See Section IV.1)
  2. Click the Resource. The Page Data screen will open.
  3. Click “Edit” in the upper right corner.
  4. Change the desired field(s).
  5. Click “Save” in the upperright corner.

Note: It is not necessary to click “Save” after editing each individual tab (“General”, “Page Settings”, “META Keywords”). As long as you click “Save” before navigating away from the Resource (by opening another screen or another document), any changes to all three tabs will be saved.

k. Moving a Resource (Webpage or Weblink)

  1. Use the Site Tree to navigate to the desired Resource (See Section IV.1)
  2. Click the Resource. The Page Data screen will open.
  3. Click “Move” in the upper right corner.
  4. Click the Resource in the Site Tree under which you wish the target Resource to appear,
  5. Click “Save” in the upper right corner.

Example: You have mistakenly created the page ‘Product X’ as a child of the ‘News’ webpage resource. You wish to move it so that it is a child of the ‘Products’ webpage resource instead. Using the steps above, you will open the ‘Product X’ resource, click ‘Move’, select ‘Products’ from the Site Tree, and click ‘Save.’

l. Deleting a Resource (Webpage or Weblink)

  1. Use the Site Tree to navigate to the desired Resource (See Section IV.1)
  2. Click the Resource. The Page Data screen will open.
  3. Click “Delete” in the upper right corner.
  4. Click “OK” on the confirmation box.

Note: If you delete a resource which has children resources, all children resources will also be deleted.

m. SPECIAL NOTE: FirstChildRedirect

It is possible to cause a parent resource to automatically redirect to one of its children resources, using the FirstChildRedirect command. Although this is an advanced command, it is very useful to content editors and thus included here.

m.i. What FirstChildRedirect Does

FirstChildRedirect tells a parent resource that instead of displaying itself, it should instead automatically display the first child resource that it has.

Example: You do not have any particular text on your ‘Company’ page which you wish to display, but you do want it to appear in the main menu. When people click on ‘Company’, you want them instead to be automatically redirect to the ‘About Our Company’ webpage (which is one of the children of ‘Company’, along with other children resources such as ‘Company History’ and ‘Join Our Team’). You will use FirstChildRedirect to do this.

m.ii. How to Use FirstChildRedirect

  1. Use the Site Tree to navigate to the desired Resource. (See Section IV.1)
  2. Click the Resource. The Page Data screen will open.
  3. Click “Edit” in the upper right corner.
  4. Scroll down to the ‘Resource Content’ field and type only the following line: [!FirstChildRedirect!]
  5. Click ‘Save’ in the upper right corner.

The command must be typed exactly as given above. After saving, the document will no longer display its own content, but instead will redirect to the first child document available. You may always remove the command at a later date to stop the redirect behavior.

3. Using Chunks

a. What is a Chunk?

A Chunk is a piece of (X)HTML and/or Javascript code which is written and stored for later insertion and use. This allows the same piece of code to be used in multiple webpages without the need to write the code in each individual webpage.

b. Accessing Chunks

  1. Click the “Elements” navigational tab from the Content Manager screen.
  2. Click the “Manage Elements” subnavigational tab.
  3. Click “Chunks” in the content window.

c. Making a New Chunk

  1. Navigate to the “Chunk” section of the Content Manager (see Section IV.3.b)
  2. Click the “New Chunk” hyperlink in the content window.
  3. The “Create/edit Chunk” screen will open.

Note: You can also create a new Chunk by duplicating an existing Chunk. This is done by editing the existing Chunk (see Section IV.3.d) and clicking the “Duplicate” button in the upper right corner.

Each Chunk consists of six (6) fields:

  1. The Chunk Name is a short, one word name for the Chunk. This name is used to identify the Chunk in the Chunk list, and will be used when you insert the Chunk into another document. Example: BackToTop
  2. The Description is a line of text used to describe the function of the Chunk. Example: Displays a ‘Back to Top of Page’ link.
  3. The Existing Category can be used to select an organizational category to which a Chunk belongs; e.g. Chunks made by certain authors or used only in certain templates.
  4. A New Category can be entered to create a new organizational group for a chunk and place the chunk within that group.
  5. Lock Chunk for Editing sets a security permission on the Chunk so that only Administrator users can edit it in the future.
  6. Chunk Code is a text field in which the raw (X)HTML code can be entered. Example: <a href=”#top”>Back to the Top of Page</a>

Note that only clientside code (code that is interpreted and parsed by the viewer’s internet browser) can be used in a Chunk. This includes normal (X)HTML as well as clientside scripting languages such as Javascript. Serverside code (code which is sent to the webserver for processing, such as PHP, Python, and Java) cannot be used in a Chunk.

Remember to save the Chunk after creating it. The ‘Save’ button is located in the upper righthand corner of the editing screen.

d. Editing an Existing Chunk

  1. Navigate to the “Chunk” section of the Content Manager (see Section IV.3.b)
  2. Click the name of the Chunk you wish to edit, in the content window.
  3. The “Create/edit Chunk” screen will open.
  4. Edit one or more fields of the Chunk.
  5. Click “Save” in the upper righthand corner to save your changes.

e. Deleting a Chunk

  1. Navigate to the “Chunk” section of the Content Manager (see Section IV.3.b)
  2. Click the name of the Chunk you wish to edit, in the content window.
  3. The “Create/edit Chunk” screen will open.
  4. Click the “Delete” button in the upper righthand corner.
  5. Click “OK” when asked for confirmation.

f. Using a Chuck in a Resource (Webpage)

In order to use a Chunk in a Resource, you must know the name of the Chunk you wish to use.

To insert the Chunk into a Resource:

  1. Navigate to the Create/edit Resource screen (see Section IV.2)
  2. Locate the area in the Resource content where you wish to insert the Chunk
  3. Enter the Chunk’s name in the format {{ChuckName}}.
  4. Save the Resource by clicking the ‘Save’ button in the upper right corner.

Example: A Chunk named “BackToTop” would be entered as {{BackToTop}}

Chunk names are casesensitive. “backtotop” is not the same as “BackToTop.”

If you attempt to add a Chunk which does not exist (i.e. it has not yet been created, or you have typed the name incorrectly), the Chunk insertion code will have no effect.

If you have added a Chunk but do not see the results of the Chunk on the Resource:

  1. Ensure that the Chunk exists.
  2. Ensure that you have spelled the Chunk’s name correctly.
  3. Ensure you have used the proper brackets: {{ChunkName}}
  4. Navigate to the ‘Site’ tab and click the ‘Clear Cache’ subnavigation tab.

4. Using Snippets

a. What is a Snippet?

A Snippet is a piece of PHP code which is written and stored for later insertion and use. This allows the same piece of code to be used in multiple webpages without the need to write the code in each individual webpage.

Users who are not comfortable with writing PHP code should not create new Snippets or edit existing Snippets.

b. Accessing Snippets

  1. Click the “Elements” navigational tab from the Content Manager screen.
  2. Click the “Manage Elements” subnavigational tab.
  3. Click “Snippets” in the content window.

c. Making a New Snippet

  1. Navigate to the “Snippet” section of the Content Manager (see Section IV.4.b)
  2. Click the “New Snippet” hyperlink in the content window.
  3. The “Create/edit Snippet” screen will open.

Note: You can also create a new Snippet by duplicating an existing Snippet. This is done by editing the existing Snippet (see Section IV.4.d) and clicking the “Duplicate” button in the upper right corner.

Each Snippet consists of five (5) fields:

  1. The Snippet Name is a short, one word name for the Snippet. This name is used to identify the Snippet in the Snippet list, and will be used when you insert the Snippet into another document. Example: TodaysDate
  2. The Description is a line of text used to describe the function of the Snippet. Example: Displays the current date and time.
  3. Execute Snippet after saving: If the Snippet is meant to have an immediate effect (rather than an effect when viewed on the webpage), checkmark the box. This is usually not necessary.
  4. Lock Snippet for Editing sets a security permission on the Snippet so that only Administrator users can edit it in the future.
  5. Snippet Code is a text field in which the PHP code can be entered. Example: echo “Today’s date is: “ . date("l F d, Y") ;

Note that only serverside code (code that is interpreted and parsed by the webserver itself) can be used in a Snippet. Clientside code (code which is sent to the viewer’s browser for processing, such as Javascript) cannot be used in a Snippetk.

Remember to save the Snippet after creating it. The ‘Save’ button is located in the upper righthand corner of the editing screen.

d. Editing an Existing Snippet

  1. Navigate to the “Snippet” section of the Content Manager (see Section IV.4.b)
  2. Click the name of the Snippet you wish to edit, in the content window.
  3. The “Create/edit Snippet” screen will open.
  4. Edit one or more fields of the Snippet.
  5. Click “Save” in the upper righthand corner to save your changes.

e. Deleting a Snippet

  1. Navigate to the “Snippet” section of the Content Manager (see Section IV.4.b)
  2. Click the name of the Snippet you wish to edit, in the content window.
  3. The “Create/edit Snippet” screen will open.
  4. Click the “Delete” button in the upper righthand corner.
  5. Click “OK” when asked for confirmation.

f. Using a Snippet in a Resource (Webpage)

In order to use a Snippet in a Resource, you must know the name of the Snippet you wish to use.

To insert the Snippet into a Resource:

  1. Navigate to the Create/edit Resource screen (see Section IV.2)
  2. Locate the area in the Resource content where you wish to insert the Snippet
  3. Enter the Snippet’s name in the format .
  4. Save the Resource by clicking the ‘Save’ button in the upper right corner.

Example: A Snippet named “TodaysDate” would be entered as

Snippet names are casesensitive. “todaysdate” is not the same as “TodaysDate”.

If you attempt to add a Snippet which does not exist (i.e. it has not yet been created, or you have typed the name incorrectly), the Snippet insertion code will have no effect.

If you have added a Snippet but do not see the results of the Snippet on the Resource:

  1. Ensure that the Snippet exists.
  2. Ensure that you have spelled the Snippet’s name correctly.
  3. Ensure you have used the proper brackets:
  4. Navigate to the ‘Site’ tab and click the ‘Clear Cache’ subnavigation tab.

5. Using Files

a. Accessing the File Manager
  1. Click the “Elements” tab in the Content Manager.
  2. Click the “Manage Files” subnavigation tab.
  3. The “Files” screen will open.

b. Viewing a File
  1. Navigate to the File Manager (see Section IV.5.a)
  2. Locate the file you wish to view in the Directory listing.
  3. Click the binoculars icon to view the file.

The file will open in a textbox in the lower half of the screen. You are able to make changes to the file, but you will be unable to save these changes and make them permanent.

c. Editing a File
  1. Navigate to the File Manager (see Section IV.5.a)
  2. Locate the file you wish to edit in the Directory listing.
  3. Click the green checkmark icon to edit the file.

The file will open in a textbox in the lower half of the screen. You are able to make changes to the file. Click the “Save” button at the bottom of the screen to save your changes.

d. Uploading a File
  1. Navigate to the File Manager (see Section IV.5.a)
  2. Use the Directory listing to navigate to the level at which you wish to upload the file.
  3. Scroll down to the “Upload File” section of the screen:
  4. Click “Choose”. A file explorer window will appear which shows the files of your local computer.
  5. Locate and click the file which you wish to upload.
  6. Click “Open.” The file will now appear underneath the “Upload File” area.
  7. Note: You may repeat steps 4-6 to upload multiple files at one time.
  8. Click “Upload file” to upload the files to the website.

e. Deleting a File
  1. Navigate to the File Manager (see Section IV.5.a)
  2. Locate the file you wish to delete in the Directory listing.
  3. Click the red minussign icon to delete the file.
  4. Click “OK” on the confirmation box.

Note: Deleting a file or folder cannot be undone. Make certain that the file you are deleting is not used by other parts of the site. Deleting necessary system files can damage your site.

f. Creating a New Directory
  1. Navigate to the File Manager (see Section IV.5.a)
  2. Use the Directory listing to navigate to the level at which you wish to create a new directory.
  3. Click the “New Directory” link at the top of the screen.
  4. Enter the name of the new directory and click “OK”. The new directory will immediately appear as a new folder at the level which you chose.

6. Using Meta Tags and Keywords

a. Accessing the Meta Tags and Keywords Manager
  1. Click the “Elements” tab in the Content Manager.
  2. Click the “Manage META Tags and Keywords” subnavigation tab.
  3. The “META Tags” screen will open.

b. Managing META Tags

i. Viewing META Tags

A list of all META Tags present in the website is immediately visible in the upper half of the META Tags screen.

ii. Adding a New META Tag

  1. Navigate to the META Tag manager (see Section IV.6.a)
  2. Enter the Name desired for the tag. This name will help you remember what the tag does or represents.
  3. Select the appropriate META Tag type.
  4. Enter the Value of the META Tag.
  5. Click “Add Tag”

If you are not sure what a particular Tag type represents or what value is appropriate, click the “HTML Reference Guide” link just below the “Tag” field for more information.

iii. Editing a META Tag

  1. Navigate to the META Tag manager (see Section IV.6.a)
  2. Click the “Name” of the META Tag you wish to edit.
  3. The META Tag information will appear in the META Tag edit fields.
  4. Edit the Name, Tag, and Values as desired.
  5. Click “Save Tag”

iv. Deleting a META Tag

  1. Navigate to the META Tag manager (see Section IV.6.a)
  2. Checkmark the “Delete” box next to the META Tag you wish to delete.
  3. Click “Delete Tags”

c. Managing Keywords

i. Viewing Keywords

A list of all keywords present in the website is immediately visible in the lower half of the META Tags screen. Keywords are simple phrases and have no additional properties.

When editing keywords, it is possible to rename or delete multiple keywords at the same time.

ii. Adding a New Keyword

  1. Navigate to the META Keyword manager (see Section IV.6.a)
  2. Type the new keyword in the “Add new keyword” box.
  3. Click “Save all changes.”

iii. Renaming a Keyword

  1. Navigate to the META Keyword manager (see Section IV.6.a)
  2. Type the new name of the keyword in the “Rename” box next to the keyword.
  3. Click “Save all changes.”

iv. Deleting a Keyword

  1. Navigate to the META Keyword manager (see Section IV.6.a)
  2. Checkmark the “Delete” box next to the keyword you wish to delete.
  3. Click “Save all changes.”

d. Using META Tags and Keywords in Resources
  1. Use the Site Tree to navigate to the Resource you wish to edit (see Section IV.1)
  2. Edit the Resource (see Section IV.2)
  3. Select the META Keywords tab.
  4. Using your mouse, click the keywords and META Tags which you wish to add to the document. Hold down the CTRL key while clicking to select multiple tags.
  5. Click the “Clear keywords” or “Clear META Tags” buttons to remove all keywords or tags from a document.
  6. Click the “Save” button in the upper right corner to save your changes.

V. Other Functions

1. The Tools Tab: Import HTML Files

MODx has the ability to import normal, nonMODx HTML documents and transform them into MODx Resources. This is not the recommended way to add content to your MODx site, but it is very useful when converting a site that contains a large number of existing HTML pages.

The Import HTML function will convert an entire HTML site, including folders, subfolders, and all content contained therein.

Note: You can also export a MODx site into normal HTML files; however, this is an advanced function which is only available to administrators.

1.a. Importing HTML Files

  1. Upload all of the desired HTML files and folders into the /assets/import directory of your MODx website (see Section IV.4 – “Using Files”).
  2. Click the “Tools” tab in the Content Manager.
  3. Click the “Import HTML” subnavigation tab.
  4. Click on the desired Parent Resource in the lefthand Site Tree.

All imported HTML files will be placed directly under the Parent Resource which you select.

5. Click “Start Import” in the content window

Note: Changing the “Max import time” is not recommended. The Import function is capable of processing almost 1000 documents per second; thus 30 seconds is more than sufficient for most websites.

2. The Reports Tab: Scheduled (Un)Publications

The Reports Tab allows you to access the Schedules: a list of Resources which are pending publication or unpublication at a future time.

The Resources are not directly editable from the Schedule screen. Clicking on the Resource’s title will open the general overview screen of the Resource itself, from which it can be edited or deleted.

3. User Administration

a. Accessing User Administration

The User Administration screens are accessible via the small toolbar in the upper right corner of every screen.

The bar contains six (6) fields:

  1. The name of the currently loggedin user (here: “editor”)
  2. A link to change your Content Manager password.
  3. A link to access your Content Manager messages.
  4. A link to generic MODx help resources.
  5. A link to log out of the Content Manager
  6. The version number of the current MODx software installation.

b. Changing Your Password

  1. Click the ‘Change Password’ link in the User Administration bar.
  2. Type your new password. Passwords must be between 6 and 15 characters long.
  3. Retype your new password in the ‘Confirm Password’ box.
  4. Click ‘Save’ in the upper right corner.

Password changes are immediate. You will need to use your new password the next time you access the Content Manager.

You will not receive email confirmation of the change.

c. Accessing Messages

The Content Management message interface can be accessed by clicking the ‘Messages’ link in the User Administration bar.

c.i. The Inbox

The Inbox contains a list of all messages sent to you or a User Group of which you are a member. Unread messages are marked with a star and green text. Messages which have already been read have black text and no star.

c.ii. Reading, Replying To, and Deleting Messages

Clicking on a message in your inbox will open the “Read Message” screen.

From this screen you can use the topmost row of buttons to reply to the sender of the message, forward the message to another user, or delete the message.

The options to ‘Reply’ or ‘Forward’ a message transfer you into the ‘Compose a Message’ screen (see Section X.2.iii), with some fields already filled in for your convenience.

Note: Clicking on the Delete button immediately removes the message. There is no way to ‘undo’ the deletion of a message.

c.iii. Compose a Message

The ‘Compose a Message’ screen is automatically open at the bottom of every ‘Message’related screen. You may send a message either to a specific user (such as johndoe), a user group (everyone who is an Administrator), or everyone registered in the system.

Note: Clicking ‘Send’ immediately sends the message. There is no way to ‘undo’ a message once it is sent.

d. Accessing Help Files

General help resources for the MODx CMS can be accessed by clicking the ‘Help’ link in the User Administration bar. Most help resources are available directly from the MODx website.

Note: As of this writing, the MODx online help does not make a distinction between Content Editor users and Administrative users. Adminstrative content will be displayed along with editorial content.

e. Logging Out

Logging out of the Content Manager is done by clicking the “Logout” button on the User Administration bar. You will be immediately logged out and returned to the Content Management login page.

f. Other User Administration Functions

All other aspects of user administration (e.g. changing a user’s name, email address, or other information) must be done by the site administrator.

Appendix I: Editor Styles & Tricks

Within the content editor window is a small dropdown menu called “Styles.” This section contains “special formatting” that can be used on text or images which are present in a page.

1. Applying and Removing Styles

a. Applying a Style
  1. Click and hold your left mouse button while dragging it over the desired text or image. This will ‘highlight’ the target text/image.
  2. With the text/image highlighted, select the desired style from the dropdown list.

Note: It is not possible to add more than one style to a particular image or text.

b. Removing a Style
  1. Highlight the target text/image (see section 1.a. above).
  2. With the text/image highlighted, select ‘Styles’ from the dropdown list. This will remove any styles currently in place.

2. Adding and Deleting Styles

Adding and deleting styles is simple but requires a knowledge of CSS and full administrative access to the server. As such, Content Editors are unable to add or delete styles. Nonetheless, the process will be described here for reference purposes.

a. Adding Styles

  1. Locate and open the site.css file for the site template being used. This is usually located at: /assets/templates/(your template)/site.css
  2. Add a new CSS rule for the effect you wish to use. Example: .red { color:#FF0000; }
  3. Save the CSS and reupload if necessary.

4. Log in to the MODx Content Manager interface using a full administrator username and password. (See section 3.II – “Accessing the Content Manager”) Styles can either be set per individual user or sitewide.

To set the style for an individual user: 5a. Navigate to “Security” > “Manage Users” > (Username) > “User” tab. Locate the “CSS Selectors” field on this tab.

To set the style for all users sitewide: 5b. Navigate to “Tools” > “Configuration” > “Interface & Features” tab. Locate the “CSS Selectors” field on this tab. Once you have located to the “CSS Selectors” field:

6. Enter the display text which will appear in the “Styles” drop down list, followed by the name of the CSS selector in the CSS file itself.

For example: Red Text=red;

Note: No leading dot (.) is required before the CSS class. Entries must be separated by a semicolon, but the final item in the CSS selectors list should not have a trailing semicolon.

7. Click “Save” in the upper right corner.

b. Deleting Styles
  1. Navigate to the appropriate “CSS Selectors” field (see Section 3.A for instructions)
  2. Remove the desired Style from the list.
  3. Click “Save” in the upper right corner.

Back to Top


Related Articles

Website Revolution

The MODx developers recently celebrated the launch of MODx Revolution. A total rewrite of the CMS many have known to grow and…

MODx Web Development…

If you are considering the MODX books by Packt Publishing, give a little extra thought to why you want them.

MODxpo Videos on Vimeo

The MODxpo videos get an upgrade!

MODxpo Slideshow

A video recap of MODxpo by zaighamz

© 2008 - 2018 AMDbuilder. The views expressed on this site are mine alone.