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.
This guide will:
This guide will not address:
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)
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.
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
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!
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.
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).
Note: Only ‘Manager’ users may access the Content Manager.
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.
The Main Navigation tab row contains the following sections:
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.
The ‘Preview’ subnavigation tab opens your website in a new browser window, allowing you to see the current version of your website.
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.
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.
The ‘New Resource’ subnavigation tab opens the ‘Create Resource’ screen. An indepth guide to creating Resources can be found in Section IV.2.
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.
The Elements tab allows you to create, manage, and delete the following:
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.
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.
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.
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:
The Site Tree gives a great deal of information at a glance.
By clicking on the name of a Resource in the site tree, you can view more detailed information about that particular Resource.
The Site Tree can be sorted in several different ways to make finding your content easier.
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.
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.
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.
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…)
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:
Creating a Weblink as a Child:
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.
e.ii. The Page Settings Tab
The Page Settings tab contains “nonvisible” information used for internal management of the Weblink.
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.
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.
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.
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:
Creating a Resource as a Child:
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.
h.ii. The Page Settings Tab
The Page Settings tab contains “nonvisible” information used for internal management of the Webpage.
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:
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:
A new window will appear.
The “General” tab is all that is necessary to create a basic web link. There are, however, three additional tabs available:
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
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)
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)
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
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.
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
c. Making a New Chunk
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:
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
e. Deleting a Chunk
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:
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:
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
c. Making a New Snippet
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:
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
e. Deleting a Snippet
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:
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:
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.
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.
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.
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
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
iv. Deleting a META Tag
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
iii. Renaming a Keyword
iv. Deleting a Keyword
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.
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.
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:
b. Changing Your Password
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.
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.
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.
Note: It is not possible to add more than one style to a particular image or text.
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
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.
The MODx developers recently celebrated the launch of MODx Revolution. A total rewrite of the CMS many have known to grow and…
If you are considering the MODX books by Packt Publishing, give a little extra thought to why you want them.
The MODxpo videos get an upgrade!
A video recap of MODxpo by zaighamz
© 2008 - 2021 AMDbuilder. The views expressed on this site are mine alone.