This page is a work in progress in Google Docs and will change as I edit it.
- Please contact me if you spot errors or have suggestions.
- Feedback is greatly appreciated!
MODX Revolution Client Documentation
Forgot Your Password
Change Your Password and Edit Your Profile
Resource Tree: Managing Resources
Top Buttons and Search Bar
Creating and Editing Resources
Full Edit/ Create View
Search Engine Tips
Other Edit Tabs
Quick Edit/ Create Mode
Rich Text Editor
Using the File Manager
Anchors (linking to a part of a page)
Inserting Media (such as YouTube videos)
Main Menu Tools
This non-technical guide to the MODX manager is meant to be used as a convenient reference after your initial training. Please contact me if you need additional help or if you have any questions about anything to do with your website.
- Each MODX website is different. Your website may have additional components or not use some of the features covered here.
- Each version of MODX brings improvements and slight changes to the manager, so you may notice slight differences between your manager and the examples explained here.
Free to use and distribute: This document is free to modify and distribute, even commercially, under the Creative Commons Attribution 3.0 Unported license, as long as you make a note that I was the original author. I would appreciate an optional link back to the original document or to my website (http://websitezen.com).
1. Point your web browser to YOURDOMAIN.COM/manager, where YOURDOMAIN.COM is your website’s domain name.
- Example: if your domain name is examplewebsite.org, go to http://examplewebsite.org/manager
- Example: if your domain name is test.example.com, go to http://test.example.com/manager
2. Enter your username and password and click “Login”
- Tip: you should have received an email with your username and a random password. If not, please let me know.
- Tip: the first time you log in, you should change your password. See “Changing Your Password” section below.
Forgot Your Password
If you forgot your password, you can have a new password emailed to you:
1. On the login screen, click “Forgot your Login?”.
2. Enter your username in the box that appears and click “Send Activation Email”.
You should see a message saying the email was sent:
3. Open the email that was sent to you and click on the activation link.
- Note: You must click on the link for the new password to be used. This is a security measure to prevent strangers from changing your password and locking you out.
- Tip: The email will be sent to the same email address that you received your original password in, or your current profile email if you changed your profile.
- Check your spam folder if you cannot find the email.
4. After you click the activation link, enter your username and the new password you received to log in.
5. Change your password after you log in.
Change Your Password and Edit Your Profile
You should change your password any time you receive a randomly-generated password, such as when you first log in or when you reset your password.
1. Either click on your username in the top right corner of the manager, or (in the main menu), click on User → Profile. Either one will take you to your user profile.
2. On the profile page, you will see the following tabs:
- The first tab (“General Information”) allows you to change your profile information if needed.
- To change your password, click on the “Reset Password” tab. See step 3.
- The “Recent Resources” tab shows the pages you last edited.
3. After you click on the Reset Password tab, enter your current password, your new password, and your new password again and hit “Save” when you are done.
When you first log in you will see the following manager screen:
Basic manager areas:
- Site name - your website name. This can be changed for your entire website at once.
- MODX version - The version of MODX that your website is running on.
- Main Menu - You do not need to use most of the links in the main menu, as many of them are meant for developers. Some of the menu links are useful for clients, however, and they are explained in later sections.
- Dashboards - Dashboards show useful updates. By default, they include:
- MODX news - This is a short RSS feed display that updates with general MODX news. New MODX versions are listed here, and you should let me know if you want to upgrade to any of them. As an alternative, you can ask me update your website every time an update comes out.
- MODX security updates - Any time a security vulnerability with MODX is discovered, it is listed here, including the versions of MODX it affects. Usually, every security vulnerability is fixed through a MODX version update. I highly recommend you ask me to update MODX every time a security vulnerability comes out with the version you are running.
- Active Users - A list of recently-active manager users, such as yourself, employees that you have allowed to edit your website, or myself.
- Your Recent Edits - A list of the pages you have recently edited. This is also shown in a tab in your Profile.
- Files Tab (Images and Attachments) - The Files tab is part of the MODX file manager, and you can use it to review all of the images, PDFs, downloads, and other files you have uploaded for use on your website. The file manager is explained later.
- Tools: Useful buttons for editing pages, explained later.
- Search Site: If you do not remember the name of a page you created on your website, you can use this search box.
- Site Pages (“Resources”) and Resource Tree: see “Resource Tree” below.
Resource Tree: Managing Resources
On the left of the manager, you will see a “tree” of the pages, or resources, on your website:
- Website pages are called “resources” in MODX because some “pages” are not real pages. E.g. some resources are redirects to other web pages or copies of other pages.
- The list of resources is called a “resource tree” because pages are arranged in a “branching” order similar to trees branching.
- One “parent” resource can have several “children” resources, which in turn can each have other children. Parent resources are marked with folder icons.
- The “root” of the tree is not a resource but the representation of each website context, or area. Most sites only have one area, called “web”.
- Site-wide settings: Most websites I set up have a “settings” context. This area contains rich-text pages you can edit but that do not show up as separate pages on your website. Instead, they show up in areas common to many pages, such as the website top (header) or bottom (footer). Simple site-wide settings (such as the site name) can be set in the Components → Configuration tool in the main menu.
Unique Resource ID:
Each resource name is followed by a number in parentheses. This number is the unique resource ID number, which never changes and uniquely identifies each page.
- Normal, published resources are shown in regular black text. They can be seen by anyone visiting your website and automatically appear in the main menu.
- Hidden (from the menu) resources (gray text color) can still be seen by anyone visiting your website, but they will not automatically appear in the main menu. You can still create links to them manually, however.
- Unpublished resources (italic) can only be viewed by a user who is logged into the manager. This means that only people you allow to edit your website can “preview” these pages.
- Keeping a resource unpublished is a good idea when you do not want the public to see one of your pages, perhaps because it is unfinished or has information that only applies in the future.
- Deleted resources (red and crossed out) cannot be viewed on the website by anyone and will be permanently deleted the next time someone “empties the trash”.
Top Buttons and Search Bar
At the top of the resource tree are some buttons with icons in them. Move your mouse over each button to see its title.
- Expand and Collapse Tree: The down-pointing arrow will show every single resource, “expanding” parent resources to show all of their children. The up-pointing arrow will “collapse” the entire tree, hiding all child resources.
- Create New Resource: these buttons create a new resource at the top of the tree (right under the root).
- Each of the buttons creates a different resource type (document, weblink, symlink, and static resource).
- The different types are explained later, but just know that the first button (document) is what you use to create a “normal” page on your website.
- Refresh Tree: Reloads the tree. If you or another site editor made changes to page names or organization, you may not see the changes until you either refresh the page or click this button.
- Sort Tree: This provides various ways of sorting the tree for your convenience. By default, pages are sorted by “Menu Order”, which is how the pages will appear in the main menu on your website. Changing the sort order here is purely for your convenience; it will not affect how the menu on the actual website is sorted.
- Empty Trash: Clicking this button will permanently delete all deleted resources (shown in red and crossed out) on your website.
- WARNING: if other people are also editing your website, they may have deleted resources you do not know about. Look through all deleted resources and make sure you are OK with permanently deleting them.
- Search Bar: You can use the search bar to search for resources instead of navigating to them in the tree. The results will appear below the search bar and above the main resource tree:
When you rick-click (click using the rightmost button of your mouse) on a page name in the resource tree, you
- Resource Name and ID: The resource page title and unique id.
- Resource Overview: Shows an overview page with information about the resource.
- Edit Resource: Open the resource in full edit view with rich-text editor and other enhancements. Editing resources is covered later in this document.
- Quick Update Resource: Pops up a simple edit window that is useful for quickly changing basic fields such as the page title and description and page settings. Quick-edit does not provide a rich-text editor, however. Editing resources is covered later in this document.
- Duplicate Resource: Creates a copy of the resource. The copy is unpublished by default so that the public cannot see the copied page until you publish it.
- Refresh Resource: This will reload the resource and any children. You may do this to check if anyone else changed the resource.
- Create: Using this menu will create a child resource under the resource you right-clicked on and will open it in full edit view. Editing resources is covered later in this document.
- Quick-create: Using this menu will create a child resource under the resource you right-clicked on and will open it in full edit view. Editing resources is covered later in this document.
- Unpublish/ Publish Resource: Unpublishing marks the resource as unpublished, which means the public cannot view the resource but you can still preview the resource if you are logged into the manager. Publishing allows anyone to see the resource.
- Delete/ Undelete Resource: Deleting a resource prevents anyone from viewing it. Deleted resources are permanently deleted when someone “empties the trash” unless they are undeleted first.
- View Resource: See how the resource actually looks to people on the front-end of the website. If the resource is unpublished, you can still preview it, but it will not appear in the main menu or be visible to the public.
You can click and hold on a resource in the tree to “grab” a resource. You can then drag it to a new location in the tree. Moving a resource in the resource tree automatically rearranges it in any automatic menus on the website, such as the main menu.
Creating and Editing Resources
There are four Resource Types that you can choose from when creating a resource:
- Document: A document is a “normal” webpage. Most pages on your site will be documents. When in doubt, choose “Document” when creating a resource.
- Weblink: A weblink is a “redirect”. When this page is opened, it does not show the page for viewing. Instead, it redirects to another page on your website or to an external URL.
- Symlink: A symlink is a “mirror copy” of another resource. This is used, for instance, when you want to have the same article in two separate categories.
- Warning: Be careful when using symlinks, as they can hurt search engine optimization. Ask me for advice on the best way to use symlinks on your website.
- Static Resource: Static resources store their content in a file on the web server.
- Most websites do not use static resources, and you should avoid using them unless you have a specific reason to do so.
Full Edit/ Create View
Edit an existing resource: You can open a page in full edit view in the following ways:
- Click on the page name in the Resource Tree
- Right-click on the page and select “Edit Resource”
Create a new resource and edit it: You can create a new resource in the following ways:
- Click one of the “Create Resource” buttons in the top of the resource tree.
- Right-click on a page name (or root) in the Resource Tree and select “Create Resource” in the menu to create a resource that is a child of that page.
- In the main menu, go to Site → New Document (or choose another resource type):
Locked Out: If you try to edit a resource and you get a warning saying that the resource is locked or being edited by another user, you have two options:
- Wait until the other user finishes editing the resource.
- If you know that the other user is not currently editing the resource, which happens sometimes due to closed or left-open browser windows, go to Site → Remove Locks in the main menu to remove all page locks.
Saving your changes: After you are finished making changes, remember to click the “Save” button. Otherwise, your changes will be lost or your new resource will not be created.
- Caution: Newly created pages will not exist on your website until you save them for the first time.
Here is a typical edit view:
- Save - Save your changes.
- Duplicate -
- Delete - Mark this page as deleted. This page will not be permanently deleted until someone clicks the “empty trash” button in at the top of the resource tree.
- View - (Opens in a new window) Shows you how the page appears on the actual website.
- Close - Closes the page without saving, unless you click the Save button first.
- Help! - Opens the MODX official manual page that explains Resources.
- The icons at the end allow you to change what happens each time you click the save button:
- Add another - Close this page and create another new page.
- Continue editing (default) - Keep this page open for further editing.
- Close - Close the full edit view.
- Main Tab - this is the main tab and shows the most important options and fields for the page. The main tab fields are explained in the Resource Fields section.
- Settings Tab - this shows you advanced options for each pages. See Resource Settings section.
- Template Variables Tab - this contains the fields that are specific to each template. Because each website will have a unique template, these fields may be different for each MODX site.
- Resource Groups Tab - If your website restricts access to certain page groups, this tab allows you to configure which “resource groups” this resource belongs to.
Content: At the bottom of the full edit view is the main content area for the page.
- Most resources have a “rich-text” editor that generates the HTML for you. This is covered in the Rich Text Editor section.
- Some resources have the rich-text editor disabled because it conflicts with some technical content in this area.
- Weblinks do not have a large main content area. Instead, this area stores the redirect URL for the Weblink.
- See the “Resource Fields” section for more information on the main content area.
Warning: The exact effect of each field may be different for each MODX website. Below is the standard use of each field, but the exact use of each field may vary slightly for your website.
If in doubt:
- Use an unpublished resource to test what happens when you change each field.
- Ask me if you are unsure what a field does on your site.
When you first create or open up a resource for editing, you will see the following fields:
How the fields appear on the website when the page is viewed:
How the Title and Description appear in the search results. Note: I am using a different website as an example here, as the test site used above is not indexed by search engines.
Explanation of each field:
- Title - The main title for the page. This is the only field required to create a page.
- Tips: Make the title short and unique. It should describe what the page is about without copying another page’s title, and no more. Save longer page descriptions for the “Long Title” and “Description” fields.
- The Title is used by default if the other titles are not specified.
- For example, if the “Menu Title” is not specified, this will be used as the title shown in the automatic menu.
- Long Title - Optionally used to specify a longer version of the title. If specified, the Long Title will be used instead of the Title as the main heading on the page.
- Menu Title - Optionally used to set a shorter title for use only in automatic menus. If specified, the Menu Title will be used instead of the Title in the automatic menus.
- Description - A short introduction to the page used by search engines in search engine results. Make sure the description is unique for each page.
- Tips: Keep the description short (one or two sentences) and grammatically correct (written for humans) so the search engines will use it.
- Summary (introtext) - Note: not needed on some sites. The short page summary is displayed under page listings.
- It is used on websites that have featured pages or blog listings to display an introduction to an article.
- If your website does not have any of this, do not use this field, or fill it out for later in case the page is ever put in a “featured” listing.
- Tip: The purpose of this summary is to try to convince a visitor to click the “read more” button. Give (just) enough information to make the visitor want to read more.
- Uses Template - This is the design template for the page.
- Most websites have at least a “Home Page” and “Inner Page/ Default” template.
- The template selection varies for each website. I can add more templates as additions to your site.
- The template selected determines which fields are available in the Template Variables tab.
- Resource Alias - On most websites, this determines the URL of the page. The URL is what is used in a “link” to determine which page to open. The full URL of the page is usually the site URL (or domain name), followed by the Resource Alias.
- The resource alias is usually generated automatically from the Title the first time the page is saved. You can force it to regenerate by deleting the existing alias and saving the page.
- You can set your own custom alias. It must be unique and have no spaces. I recommend you make aliases contain only lowercase letters and numbers and use dashes (-) to separate words.
- Example: if the site with the domain test.example.com has a resource with the Resource Alias test-page, the full URL of the page will be http://test.example.com/test-page
- Link Attributes - Not used on most sites.
- Hide From Menus - Make sure this is unchecked if you want the resource to be shown in the main menu of your website automatically.
- If you check this box, the resource will not be automatically shown in the main menu. However, you can still link to the resource manually.
- Published - If this box is checked, the web page will be available to the public. If this box is checked, only users logged into the manager will be able to view the resource.
- Content - The content area contains the main content for Document resource types. This field usually has a rich text area. See the Rich Text Editor section for instructions on editing this field.
- Question: Where is the keyword field? Search engines ignore the keyword field now due to abuse by website owners in the past, so I no longer use it in websites.
- The best search engine results come from placing keywords strategically as part of human-readable Titles, Long Titles, and Main Content.
- See “Search Engine Tips” section below for more SEO tips.
In Weblink resource types, the content area is replaced by a Weblink field, where you will put the URL that the resource redirects to when the URL for the resource is opened.
Everything else works the same as other resources. For example, if the weblink is not “hidden” from the menu, it will automatically appear in the automatic menus, using the Title or Menu Title as the menu link.
Example Weblink Uses
- You want to have a short link (such as example.site/specials) that will always redirect to the featured special, but you want to keep each special on a separate page. Just create a weblink with an alias of “specials” and change it to redirect to the latest featured special whenever your specials change.
- You want to redirect to your ebay page with a short link called “ebay”.
- You created a document on another website that has a long complicated URL. Create a weblink to redirect to it.
- You want to have a page appear multiple times in the automatic menu. Just create weblinks that redirect to that page and arrange them in the menu as you like.
- Tip: to prevent the original page from showing up, just check its “Hide From Menus” option.
- To redirect to an external website, place the full URL of the external website in the Weblink field, starting with “http”. For example, http://google.com would redirect to the Google home page.
- To redirect to another page on your site, use the following code: [[~#]] (where # is the ID number of the resource you want to redirect to) in the Weblink field of the resource.
- For example, to redirect to the resource with ID number 5, place [[~5]] in the Weblink field of the resource.
- To redirect to your website start without using the home page’s alias, use the following code in the Weblink field of the resource: [[++site_url]]
Search Engine Tips
- Try to make each page about one specific topic. Specific pages are preferred over general pages in search results for specific searches (which are more common than general searches). Examples of good page topics:
- Ontario, CA Used Book Stores
- Marketing to Poodle Owners
- The History of Paper Plates
- Use the keywords for your page topic in the Title, Long Title, the main headings in the Main Content area, and in link text to and from the page.
- But don’t overuse keywords! Make sure the “density” of each keyword is no more than 2-4% of the unique content of each page.
- Speaking of unique content, at least 70% of the text on each page should be unique to that page.
- Avoid copying text from other websites. This can actually hurt search results.
The “Settings” tab of the full edit view usually looks like this (important fields are outlined):
- Searchable - On most websites I set up, unchecking this box prevents the page from being indexed by search engines or showing up in the sitemap.
- Uncheck this box for utility pages such as thank you pages that visitors should only need to go to for a specific reason.
- Uncheck this box for any page you would rather not be found through the main search engines and your site map.
- If you see a page that I set up with the Rich Text setting unchecked, check with me before re-enabling Rich Text for that page.
- Published On - Some blog listings and articles on some websites show the date the article was written. You can change this date here.
- Publish Date - Unpublish a page and set the “Publish Date” to a date in the future to have the page automatically published on that date. This is useful, for example, if you have a sale or special that does not take place until a certain date or if you wrote several articles and want them published one per day.
- Unpublish Date - Publish a page and set the “Unpublish Date” to a date in the future to have the page automatically unpublished on that date. This is useful, for example, if you have a sale or special that ends on a certain date.
- Freeze URI - If this is checked, you can override the resource URL that is automatically generated using the Alias field with a URI of your own.
- Reasons to Freeze the URI:
- You moved your website to MODX and want to make sure your old website’s links do not change.
- You want to create a complex URI that the alias field does not support.
- Some MODX websites automatically create a folder structure for your URLs and/or append suffixes to your aliases. Setting the URI overrides any automatically generated URLs for this resource.
- The URI field appears after you check the Freeze URI checkbox:
- Parent Resource - You can select a new parent resource that this resource will be “located under”. This is the same as dragging the resource to a new parent in the resource tree.
- Menu Index - Changes the menu order for this page. Higher-index pages appear lower in the menu. This is usually automatically set for you when you drag the resource in the resource tree.
- For example, a page with Menu Index of “10” will appear lower in the menu than a page with a Menu Index of “3”.
- Container - If this is checked, the page is marked as a “parent” that holds other pages. This is usually automatically done for you when you drag resources in the resource tree ( resources that contain other pages are set as containers, empty resources are unset as containers). However, sometimes the automatic container setting malfunctions or you may want to force an empty resource to be a container manually.
- Deleted - Checking this and saving the resource is another way of deleting resources.
Advanced Settings - Usually no need to modify!
- Resource Type - Change the resource type. Make sure you back up the page text before changing the resource type.
- Content Type - Used for special purposes when you need a non-HTML page. You should leave this setting alone unless you have a good reason to change it.
- Content Disposition - Changing this to Attachment usually allows the page to be downloaded to a user’s computer instead of opening it in the browser. Again, you should leave this setting alone unless you have a good reason to change it.
- Cachable - Do not change this unless you know what you are doing. Unchecking this forces the page to be generated every time it is loaded.
- Empty Cache - Do not change this unless you know what you are doing. Unchecking this prevents the cache from being cleared every time the page is saved.
Other Edit Tabs
The Template Variables (TV) tab of the full edit view contains all of the template-specific fields for your website.
Template Variables are different for every website, so call me if you have a question about the template variables created for your website.
Example Template Variables (for the example dog rescue website used in this doc):
Resource groups are specific to websites that restrict access to certain parts of the site.
When a resource is part of at least one resource group, access to it is restricted. Only people that have the rights to the resource groups that the resource is in will be able to view it.
To add a resource to a resource group, simply check the box next to the resource group name and save the resource when you are finished.
Quick Edit/ Create Mode
The quick edit/ create window is similar to the full edit view, except it:
- Provides only the most common fields and settings.
- Does not provide a rich-text editor.
- Is much faster to open and close.
Use the quick edit/create window when you need to quickly change a simple field, such as a title or description, or a simple setting, such as the “searchable” option.
- To quickly edit an existing resource in Quick Edit mode, right-click on a resource in the resource tree and select “Quick Update Resource”:
- To quickly edit an existing resource in Quick Edit mode, right-click on a resource (or root) in the resource tree and select “Quick Create → TYPE”, where TYPE is the resource type you want to create:
What the quick edit/ create window looks like:
And the Settings tab:
Rich Text Editor
MODX allows the use of many different rich text editors, but the most common editor, the editor with the most features, and the editor described here is the MODX version of TinyMCE.
- Hover over each button to see what it does.
- Keep it simple! Try to apply as little formatting as possible to the content so that:
- the site-wide styles can take effect
- the site design is easy to change in the future
- your site looks consistent, clean, and professional
- Use cleanup tools or paste content in using the “Paste as plain text” button if anything does not look right or seems to have too much formatting applied.
Keep it simple. Try to use the following formatting primarily:
- Blocks of Text: By default, each block of text in the editor is a paragraph. You can use the “Block Type” dropdown to change the type of the block (to a heading, for example).
- Hitting the ENTER (or RETURN) key will create a new paragraph.
- To go to the next line without creating a new paragraph, use SHIFT+ENTER
- See “Block Types Reference” below for an explanation of each type.
- Numbered and bulleted lists. Use increase indent and decrease indent to change list levels.
- Bold, italic, strikethrough, superscript, subscript, and text alignment. Tip: Try to avoid underline as underlined text is often confused with links.
- Site-specific styles (which are different for each design).
If you really need more styles, use the Edit CSS Style button: .
- Tip: If you find yourself using the same style over and over, ask me to add a site-specific style for you, which will save you time and can easily be updated all at once across the entire site if the need arises.
- Tip: Try to avoid using too many styles, as it might make your website look less consistent and it will make it harder to update all of these styles in the future if the site design changes.
Inserting special content:
- See the expanded sections below for the buttons Insert/ Edit Link, Insert/ Edit Image, and Insert/ Edit Embedded Media for more on links, images, and media.
- Non-breaking spaces (spaces that are treated as if they were part of a word), horizontal rules, and special characters:
- Use the data table buttons to insert and manipulate data tables:
- Templates: If you find yourself formatting a page the same way over and over again, you can ask me to set up a pre-defined template for you. Use the “Insert Predefined Template Content” button to insert a template:
Block Types Reference
- Use paragraph (or p) for regular text. Paragraphs have a space underneath them.
- Use division (or DIV) if you do not want the space underneath the text or if you will be inserting a MODX tag. “Div” stands for “division”.
- There are several “levels” of Headings. Heading 1 (H1) is the most important (“largest”) heading, followed by Heading 2, etc... down to Heading 6, which is the least important.
- You should arrange the headings in a hierarchical order.
- For example, use Heading 3 as a subheading for sections started by Heading 2.
- Because the main title of the page is already inserted in most websites using Heading 1, you should start your subheadings with Heading 2.
- Use a Block Quote for quotes spanning multiple lines
- Use Address for address blocks.
- Use Code for code samples.
- Use Preformatted (or pre) when you need all of the spaces rendered exactly as you put them in.
Any text that starts with [[ and ends with ]] is a special MODX code that will get automatically replaced when the page is generated. For example:
- [[++site_name]] is automatically replaced with your global website name
- [[++site_url]] is automatically replaced with your website url
- [[~5]] generates the URL to the resource with ID number 5
- [[!Wayfinder? &startId=`[[*id]]`]] generates a bulleted list of links to the child pages of the current document and all of their descendents
- [[!Wayfinder? &startId=`[[*id]]` &level=`1`]] is the same as the above, but only lists child pages (one level of children)
Note: Most codes are customized for each website. The above codes will work with most sites. Check your site-specific documentation for useful codes for your websites.
Tips for using codes:
- Do not format “parts” of the code. For example, [[++site_name]] will not work. You must make the entire code bold to generate a bold site name correctly.
- If the code is not working, try removing it and pasting it back using the “Paste as Plain Text” button (which removes any HTML tags that may have found their way into the code).
- The ticks you see in codes such as [[!Wayfinder? &startId=`[[*id]]`]] are not the single quotation mark. They are the backtick located on the key to the left of the number “1” on most keyboards:
- Codes that generate more than just a few words should be placed in a “DIV” block (instead of a paragraph or heading), as some browsers render complex elements inside of paragraphs and headings incorrectly.
Using the File Manager
The file manager shows the files uploaded to the server for use in images, links, and template variables.
Warning: Do not move or rename files you have uploaded and already used unless you are prepared to change (update) every image and link that refers to the moved or renamed file.
File Manager Tips:
- Do not upload huge images, as this puts an increased load on the server.
- Avoid spaces and special characters in filenames.
When the file manager opens (e.g. because you need to choose a file for an image, link, or template variable), here is how to select the file you want to use:
- Click on the directories on the left to navigate to the folder where the file is stored.
- (Optional) upload a new file to the folder by right-clicking on the folder and selecting “Upload File”.
- Click on the file you want to use. The file will be highlighted to show it is selected.
- Click “OK” to select the file.
The “Files” tab on the left of the MODX Manager is is another way to view, organize, and upload files to the file manager (when you are not browsing for a file):
- The “Files” tab is in the same tabbed area as the Resource Tree
- Hover over each button to see what it does.
- Right-click on a folder or file to view available options.
- The Files tab works similarly to the file manager and provides a button to open the full file manager in a new window.
Important: when linking to pages on your website, make sure you let the link dialogue insert the link code for you. DO NOT link to the page using its URL, because the link might break if you change the page’s Alias.
To insert a link from the rich-text editor:
- Select some text or an image that you want to make into a link.
- Click the “Insert/ Edit Link” button:
- In the link selection dialogue:
- To link to an external website, type the URL (starting with “http”) in the “Link URL” field.
- To link to a file for download, such as a PDF or ZIP file, click on the file browser icon to browse for the file using the file manager.
- To link to a page on your website, search for it using the “Search” field and select it from the list.
- A special code will be inserted that looks like [[~#]] (where # is the ID number of the resource).
- This special code will automatically generate the correct link to the resource, even if the resource’s Alias changes.
- Press OK when finished.
Link Selection Dialogue:
Changing and Removing Links:
- Place your cursor on the link. The link and “unlink” buttons will become “highlighted”:
- Click the link button to open up the link dialogue to edit the link, or click the unlink button to remove the link.
Anchors (linking to a part of a page)
Anchors allow you to link to a specific part of a page, such as a specific subheading.
To insert an anchor into a page for later linking-to:
- Position your cursor where you want the anchor inserted (usually to the left of a heading).
- Click the Insert/ Edit Anchor button:
- Type the name of the anchor (no spaces) and click Insert:
- The anchor symbol will mark the place the anchor was inserted in:
To link to an anchor: The new anchor will appear in the “Anchors” drop-down of the Insert/ Edit Link dialogue.
- Tip: If the anchor is on another page, you will first need to “search” for that page before the anchors for that page will appear.
- Caution: Some older installations have a more complicated procedure, but a patch is available. If links to anchors on the same page are not working for you, contact me for a quick fix.
- Technical Note: Anchors Link URLs are in the format: [[~#]]#anchor-name
- [[~#]] is the automatic link to another page.
- When linking to a link on the same page, anchors appear simply as #anchor-name
To insert an image using the rich-text editor:
- In the rich-text editor, place your cursor where you want the image to be inserted.
- Click the “Insert/ Edit Image” button:
- In the Image Dialogue, click on the file browser icon to browse for the image using the file manager.
- Select the image from the file manager.
- Enter an “Image Description” for viewers who are unable to see images.
The appearance tab of the image dialogue allows you resize your image and configure display settings.
- Technical Note: The automatic image resizing available in MODX Revolution may not produce the best size savings or image quality. If you want better results, resize and optimize the image on your computer before you upload it to the file manager and do not change the size in the Appearance tab.
Appearance Tab Options:
- Alignment: Set “left” or “right” to allow the text to float around the image. Experiment with the other options (preview is shown on the right). Note: some websites have site-specific styles that take care of this for you.
- Dimensions: Resize the image here. To reset to the original image dimensions, re-select the image from the file manager.
- Vertical and Horizontal Space: This adds extra space (in pixels) to the top and bottom (vertical) and/or left and right (horizontal) sides of the image. Note: some websites have site-specific styles that take care of this for you.
- Border: Adds a black border of this many pixels around the image.
- Class: Site-specific styles. Caution: not currently working in most versions. Apply site styles from the rich-text editor’s “Styles” menu instead.
- Style: Allows you to tweak the CSS styles generated.
Inserting Media (such as YouTube videos)
Note: older versions of MODX Revolution’s rich-text editor do not support some of these features. Ask me to update your website to get the new features.
To insert media into the rich-text editor:
- Position your cursor where you want your media to go.
- Tip: the best results are achieved by putting the media into a DIV block by itself (see Rich Text Editor section for more on block types).
- Click the “Insert/ Edit Embedded Media” button:
- Configure your media and click “Insert” when finished.
- Source Tab: The easiest way to insert media into the rich text editor is to copy and a pre-generated source code from a media-hosting website, such as YouTube. This code should start with <iframe, <object, <video, or <audio and can be inserted directly into the “Source” tab of the media dialogue.
- See YouTube Tutorial below for instructions.
- If you want to upload media files directly to the file manager, I can set up your own customized media player for you. Contact me for details.
- Save the document and view it to make sure everything is working correctly.
- Go to the page of the YouTube video you want to insert.
- Click the “Embed” button (you may need to click the “Share” button first). You should see some HTML code appear.
- (optional) Configure the options under the HTML code to customize the video player.
- Copy the code for pasting into the “Source” tab of the “Insert/ Edit Embedded Media window”. The code may look like this:
- Back in the MODX rich text editor for the page where you will be placing the YouTube video, position your cursor and click the “Insert/ Edit Embedded Media” button. In the window that pops up, switch to the “Source” tab and paste the YouTube code you copied into the provided box:
- Switch back to the “General” tab to view a preview of the video and adjust the width and height and other options. The fields should have been automatically filled in from the source code. Click the “Insert” button when you are finished.
- The video will appear as a yellow placeholder square in the rich text editor.
Main Menu Tools
Clicking on “Dashboard” takes you to the main manager page (the page you see when you first log in).
The Site menu is packed with useful site maintenance tools:
- View - Shortcut to view the front-end home page
- Clear Cache - If your website does not seem reflect your changes, clicking this often helps “update” the site.
- Technical Note: The cache exists to help speed up your website, sometimes at the cost of responsive updating. Contact me if you experience too many problems with your site not updating with your changes, as this usually indicates a problem with how the cache is configured.
- Remove Locks - Use this button to remove all locks across the site.
- If another manager user is editing a resource, MODX will “lock you out” from editing the same resource. MODX does not always know if someone left a page open or closed their browser; sometimes pages are locked when they should not be and so must be released manually.
- Search - Open the search page, which allows you to search for resources.
- New Document - Create a new document at the root of the site. See resource types.
- New Weblink - Create a new weblink at the root of the site. See resource types.
- New Symlink - Create a new symlink at the root of the site. See resource types.
- New Static Resource - Create a new static resource at the root of the site. See resource types.
- Logout - Logs you out from the manager.
The Components menu contains components specific to your website. Some of the most common components are described in the Components Menu section.
The Reports menu contains logs, reports, and information about the website:
- Site Schedule lists the resources that will be published or unpublished in the future.
- Manager Actions shows a simple log of manager activity. The log is not very detailed; it shows which pages were edited or created but not what was written on those pages, for example.
- The manager log is useful to answer questions such as “Who keeps changing the About Us page?” or “Which page was I working on yesterday?”.
- Use the “Empty Manager Log” button on this page to empty the log, which could reduce the size of backups.
- Error Log is a technical log of MODX errors useful for debugging.
- System Info shows both technical and nontechnical general information, including a list of recently-edited resources.
- About shows some credits and information about MODX.
The User menu gives you access to your Profile and messages. Messages allow you to send simple messages to other manager users and are not often used (email is the usual alternative).
The Support menu contains a variety of MODX support links.
- You may need to use Security → Manage Users to view, edit and add manager and website users. Contact me for help with this or to set up groups and permissions..
- If your website uses more than one language, you can edit translations in Tools → Lexicon Management.
Note: These components are installed on a site-by-site basis, depending on the project specifications, client needs, and the component availability at the time your site was built. Contact me if you need help with components not listed here or if you would like some of these added to your website.
The configuration component allows you to configure non-technical site settings. The available site settings are different for every website.
To edit your site settings, go to Components → Configuration in the Main Menu
- Hover over each setting name to read a longer description of that setting.
- Click the save button when you are finished.
Gallery appearance on the front-end website is different for each site, so this section only deals with basic gallery management. Contact me to find out how galleries are displayed on your site and how the various settings affect your galleries.
To edit your gallery albums and images, go to Components → Gallery in the Main Menu
Creating and Managing Albums
Note: Your design may use only a few pre-set albums, or you may be able to create and place new albums as needed. Check with me if you are not sure which setup you have.
- To create a new album, click the “Create Album” button.
- To create a new child album, right-click an existing album name and select “Create”
- To edit information for an existing album, either click on the album name or right-click the album name and select “Update”. Remember to click “Save” when finished.
- To delete an album, right-click the album name and select “Delete”
Album information fields:
- Name: the album name (required)
- Description: an optional description
- Active: Inactive albums will not be displayed in lists of albums (on some installations).
- Prominent: Only used on some designs for widgets such as “featured albums”.
Adding Images to an Album
Note: Images for each album are completely managed by the Gallery Component and are not the same as images uploaded via the file manager.
There are four ways of adding images to an album:
- Upload Item: Upload a single file from your computer and edit the information for the image at the same time.
- Multi-Upload: Upload multiple images from your computer at once. You will need to add image information individually later.
- Batch Upload: (technical) Imports images from a directory in your file manager.
- Directory: This will vary based on your server and installation. Contact me if you do not know which directory to specify.
- Zip Upload: Allows you to update a zip file from your computer. Gallery will attempt to extract the images inside of the zip file.
Image Information: Right-click on an image and select “Update Item” to edit the information stored with the image. The image information for each image may be used in different ways on each website. In general:
- Name: A short name associated with the image.
- Description: A longer description. May be rich-text. Used differently on each site.
- URL: Usually, this determines the link that opens when the image is clicked in a slideshow or gallery. However, many sites have special uses for this field. Contact me if you are not sure what this does.
- Tip: to link to a page on your website, use the code [[~#]], where # is the unique ID number of the page. See Managing Resources.
- Tags: A comma-separated list of “tags”. Some websites use this for filtering images in an album.
- Active: If this is unchecked, the image will not be displayed in galleries.
- ID: A read-only unique ID for the image.
- To delete an image, right-click on the image and select “Delete Item”.
- To reorder images, click and drag images into a different order.
- To view full-size images and file information:
- Click on an image to select it. Image information will appear in the right panel.
- Click on the image thumbnail that appeared in the right panel. A full-size image should open up.