George Mason University Antonin Scalia Law School

Tag: modx

How to Upgrade MODX Revolution

  1. Clear the site cache and the two logs (Error Logs and Manager Actions under the Reports menu)
  2. Flush Permissions and Log Out
  3. Backup files and database through cPanel
  4. Use CPanel to delete all the files in the cache folder (core/cache).
  5. Download the latest version of MODX Revolution, unzip, and merge (not replace) with the current installation (folders: connectors, core, manager, and setup) via FTP client
  6. Change setup directory permissions (no sudo is required)
    cd public_html
    find setup/ -type d -exec chmod 755 {} \;
    find setup/ -type f -exec chmod 644 {} \;
  7. Go to law.gmu.edu/setup. Click next, next, next (maybe one more next) and that should be it.

Source: Upgrading MODX
Also check out Bob Ray’s guide for upgrade.

Add Breaking News on The Mason Law’s Homepage

To post one announcement on the Mason Law homepage, use this example:

ANNOUNCEMENTS: <a href="">Information on Spring 2015 Laptop Exams</a>

To post multiple news, use this example:

<div class="announcements">Announcements:</div>

<ul>
<li><a href="[~15~]">Spring 2013 Class Schedule and Registration Information</a></li>
<li><a href="[~8476~]">Information on Fall 2012 Laptop Exam Software</a></li>
</ul>

MODX: Permissions and Users

Contents

It is likely that you will need to provide different types of access to different types of users. Administrators will need full access to everything. Other users will need access to only certain parts of the site, and may need to be restricted in the kinds of actions they can perform.

Users

MODx has two types of users:

  1. Manager Users: the people who can use the MODx manager interface to create and edit content
  2. Web Users: the people who do not need manager access, but who need to log in to other features of the web site, such as for commenting on blogs.

This distinction will disappear in version 0.9.7 and up, but for now the distinction still exists.

To create a manager user

Go to Security > Manager Users, then click on “New user.”

Web Users

For now, this tutorial will not address web users. Most of the time these users will be created by a separate scrip—a blogging script, for example. As such, a full discussion of web users is beyond the scope of this particular tutorial.

Roles

Every manager user will have a role. The role determines the manager user’s global permissions within the MODx system. The role can grant or restrict access to perform functions related to content, template, snippets, user management, and so on. Every situation will have its own unique needs, but here are some suggested roles that will work in many situations:

  • Administrator: The default administrator account (this role cannot be edited or deleted)
  • Developer: Access to everything except user permissions, roles, and site configuration
  • Designer Plus: Access to content, files[note], templates, snippets, and chunks
  • Designer: Access to content, files[note], and templates
  • Editor: Access to content and files[note]
  • Proofreader: Ability to edit content, but not create or delete content, and no access to files.

Notes about files:

  1. To grant access to the file manager (to upload PDFs, Word documents, etc.), you need to scroll all the way to the bottom of the page to the “Configuration management” section and select “Use the file manager.”
  2. You can limit user access to subdirectories within the File Manager.

Important points about roles:

  • All manager users are assigned one and only one role. You cannot give a manager user more than one role, or no roles at all.
  • Roles do not control which web pages or sections of the site a user has access to. To do this, you must use group permissions.

To Create a Role

Go to Security > Roles > Create a new role. Check the boxes next to the permissions you want to grant.

To Assign a Manager User to a Role

Select the appropriate option from the “User’s role” drop-down box when creating or editing a user (Security > Manager Users).

Group Permissions

In MODx, the way to restrict who has access to which documents is done through group permissions. There are two types of groups:

  1. User groups
  2. Document groups

You have to create some of both for the system to work properly. At a minimum you have to create a user group, create a document group, then associate the two with each other. It is possible to assign multiple document groups to a single user group. It is not possible to assign multiple user groups to a single document group.

Example

Here’s a real world scenario. Let’s say you have 13 organizations that you want to publish information about on your web site: Organization A, Organization B, Organization C, and so on through Organization M. You want to grant access to certain people within each organization to edit their own web pages, but not the web pages of the other organizations. To make things more complicated, organizations A through F belong to Category 1, and the others belong to Category 2. You want to assign a group of “Category 1 managers” to oversee the web pages of all of the organizations in Category 1, and you want to assign a different group of “Category 2 managers” to oversee the web pages of the organizations in Category 2. On top of all of this, you have an “Organization Czar” who is in charge of overseeing all organizations in both categories.

Here’s how you could set this up:

  1. Create a user group for each organization. To make things simple, you could call the user groups “Organization A,” “Organization B,” and so on through “Organization M.”
  2. Create a document group for each organization. I would use the same naming convention (“Organization A,” “Organization B,” etc.).
  3. Create a user group called “Category 1,” and a user group called “Category 2.”
  4. Create a user group called “Organizations.”
  5. Associate the user groups with the appropriate document groups.
    • Associate the user groups for the individual organizations with only one document group, e.g. user group “Organization A” will be associated with document group “Organization A.”
    • Associate the user group “Category 1” with all of the document groups for each of the organizations that belongs to Category 1. Organizations A through F belong to Category 1, so associate user group “Category 1” with document groups “Organization A” through “Organization F.”
    • Associate the user group “Organizations” with each of the organization document groups.
  6. Assign users to the appropriate user group(s).
  7. Assign documents to the appropriate document group(s).

To create a User Group

Go to Security > Manager Permissions > User groups. Type a group name under “Create a new user group.” Click “Submit.”

To Create a Document Group

Go to Security > Manager Permissions > Document groups. Type a group name under “Create a new user group.” Click “Submit.”

To Link User Groups to Document Groups

Go to Security > Manager Permissions > User/Document group links. Select a document group name from the drop-down list of documents. Click “Add.” You may repeat this process to add multiple document groups to a single user group.

To Add a User to a User Group

Go to Security > Manager Users, then click on the user’s name (or click “New user”). Scroll down until you see “Access Permissions.” Select the appropriate user group(s). Note that you can’t add users to document groups, only to user groups.

To Add a Document to a Document Group

Click on the page in the Document Tree on the left, then click on “Edit” in the main view. Scroll to the bottom area of the screen until you see the “Access Permissions” list. Select the appropriate document group(s) from the list. Note that you can’t add a document to a user group, only to document groups.

Important points about group permissions:

  • Documents have no access restrictions by default. If documents are not assigned to a specific group, they are editable by all document groups. In most multi-user settings, this is a bad idea. Unless you are a small team of fully-privileged administrators who trust each other completely, you probably do not want any document to be completely editable by everyone. You should create groups and assign all pages to at least one group.
  • Users can access only those files assigned to their group. If a user is not assigned to a group, the user will be able to access only the documents marked for “All Document Groups (Public).” If all documents are assigned to a group (as they should be), this user would not be able to access any documents.
  • Documents inherit the permissions of their parent documents. By default, when you create a document, it will inherit the permissions of its parent document, which is a usually good thing… unless you realize after the fact that you forgot to assign the correct permissions to the parent document. Then you have to go back and manually associate each document with the appropriate group(s). It is especially important to set the correct permissions as you create pages on the root level of the site, because without any parent document to inherit from, they will be editable by all users by default, which, as I have mentioned before is probably a bad thing.

WARNING: Users must be granted permission to at least one document on the root level. Unfortunately, the permission system in MODx does not allow users to access subdirectories unless they can also access the parent document(s). If you don’t provide access at least one line of parent document(s) all the way up to the root level, the users will see an empty document tree, and they won’t be able to access anything. This is a flaw in MODx, because it means that users must be given full editing privileges to all parent documents in this path, even if you don’t want them to have this access. Using the example from above, if the path to the “Organization A” main page is /organizations/category1/organizationA/, you must designate the documents “organizations” and “category1” as belonging to the document group “Organization A.” People belonging to the document group “Organization A” will be able to edit all of the pages underneath “organizationA”, as you would want and expect, but they will also be able to edit the parent documents “organizations” and “category1,” as perhaps you would not expect, and you certainly don’t want. But that’s the way it is. Currently there is no way to work around this flaw in MODx’s permission system.

Customizing Permissions to the File Manager

If you wisely decide that you do not want all of your users to have full access to all of the files in the file manager (the “assets” folder), you will need to restrict their access to a certain subdirectory within this folder. This sounds easy enough, and in some ways it is, but it is complicated by the way in which the file browser for MODx’s rich text editors works.

The principle is easy enough: to restrict a user to a certain directory in the file manager, set that user’s “File Manager Path” to a subdirectory within the “assets” folder. For example, if the default path to the file manager is “/home/web/public_html/assets/”[note] you could set the directory for a user in the “Organization A” group to something like “/home/web/public_html/assets/org_a/”. But you need to take into account other factors. If you want people in the user groups “Organizations” and “Category 1” to also access this folder, you probably ought to put the path in a similar hierarchy. Something like this could work: “/home/web/public_html/assets/orgs/cat1/org_a/”.

Note: The default path for the File Manager is set in the site configuration under Tools > Configuration > File Manager > File Manager Path.

To customize the File Manager Path

Go to Security > Manager Users, click on the name of the user you want to edit (or select “New user”), then click on the “User” tab and type in the desired path for the “File Manager Path.”

  • Customizing the File Manager Path has no effect on the file browser from within the rich text editor. You must set that path separately (see customizing permissions to TinyMCE).

Customizing Permissions to TinyMCE

TinyMCE can be customized for each user, in terms of the interface and the file browser. The default settings for the site are available under Tools > Configuration > Interface and Features > TinyMCE Settings. To customize these settings for individual users, Go to Security > Manager Users, click on the name of the user you want to edit (or select “New user”), then click on the “User” tab and scroll down to the “Resource path” and “Resource URL” options.

Customizing the File Browser Folder

You probably want the path of the file manager to match the path of the file browser used within the rich TinyMCE text editor. The two paths you have to change are “Resource path” and “Resource URL.” Make the “Resource Path” the same as the “File Manager Path.” In our example, the path would be “/home/web/public_html/assets/orgs/cat1/org_a/”. For the “Resource URL, convert this path into the public URL of the web site: “http://your_web_site.com/home/web/public_html/assets/orgs/cat1/org_a/”.

Important: If you customize the path to the file browser, you will need to create two subfolders within this path: “images” and “files.” The file browser looks for all images within the folder called images, and looks for all files within the folder called “files.” If these folders don’t exist, users won’t be able to take advantage of the file browser. In our example, the folders will be found at these paths: “/home/web/public_html/assets/orgs/cat1/org_a/images/” and “/home/web/public_html/assets/orgs/cat1/org_a/files/”. You do NOT need to enter these paths anywhere in the configuration settings, but the folders must exist for the file browser to work.

Customizing the TinyMCE Interface

You do not have to customize the TinyMCE interface. If you leave all of the files under “TinyMCE Settings” blank, users will be given the default features as specified in the site settings (Tools > Configuration > Interface and Features > TinyMCE Settings). But you may decide that you want some users to have customized versions of the TinyMCE interface. There are preset “Themes” to choose from: Simple, Advanced, Content Editor, and Custom. Choose from among these options.

Setting the options for “Custom Plugins,” “Custom Buttons,” and “CSS Selectors” goes beyond the present scope of this tutorial, but I will mention one useful option: adding table editing controls. This should probably be done for all users, rather than just for certain ones. To add table editing options, type “tablecontrols” in Row 3 of the “Custom Buttons.” Scroll to the top and click “Save.”

WARNING: It is impossible to set a custom CSS file for each user. If you set a “Path to CSS file” in the site configuration (Tools > Configuration > Interface and Features > TinyMCE Settings), you are stuck with this style sheet no matter what, even on pages that don’t use it. This is a real shame, and severely limits the usefulness of the “Path to CSS file” option. One clumsy workaround is limit the number of classes available to TinyMCE by listing them in the site’s “CSS Selectors” option, and then ensure that all style sheets have all of these particular classes.

MODX: Designing a Web Site

Contents

  • Templates
  • Template Variables
  • Snippets
  • Chunks
  • Plugins

    Templates

    In the MODx manager interface, go to Resources > Manage Resources > Templates to create or modify templates.

    Every page uses a template. Templates contain regular HTML markup, plus placeholders for variables. It is common to use the pagetitle field in MODx for the <title> element in the template, for example. In the template, that line would look like this:

    <title>[*pagetitle*]</title>

    The longtitle is often used for the first heading above the page content, like this:

    <h1>[*longtitle*]</h1>
[*content*]

    Other useful page variables include id, alias, description, and menuindex (which allows you to sort pages in any order). You can use these fields any way you like within the template.

    Note: When designing templates in MODx, it is usually best to define a base URL in the <head> of the template like this:

    <base href="http://www.law.gmu.edu/org/" />

    With the base URL in place, you will need to define your links relative to this url. For example, with the above base URL in place this link

    <a href="mypage">My page</a>

    will point to this web address:

    http://www.law.gmu.edu/org/mypage

    BUT most links should be created by using the ID of the document (e.g. <a href=”[~1234~]”>Link text</a>). Refer to the information about links for more information.

    Template Variables

    In the MODx manager interface, go to Resources > Manage Resources > Template Variables to create or modify template variables.

    When you use template variables, you turn your MODx pages into a database of data objects, which you can query and manipulate to display in an almost unlimited number of ways. For example, you could create a template variable called “fname” to store a person’s first name, and “lname” to store a person’s last name. You could create template variables for email, phone, address, and anything else you need to store in a database. The data can be input as text input, or from a drop-down list of pre-defined options, or radio buttons, or checkboxes, or textarea fields, or a number of other options. You define the data type and parameters when you create the template variable.

    To make use of this data, you can use “snippets” of PHP code. You can design your own snippets, or you can make use of snippets included with MODx. The Ditto snippet is especially useful for working with template variables.

    Refer to the documentation at http://modxcms.com/template-variables.html for more information about template variables.

    Snippets

    In the MODx manager interface, go to Resources > Manage Resources > Snippets to create or modify snippets.

    In MODx, reusable bits of PHP code are referred to as snippets. You reference a snippet by it’s name, and put it in brackets, like so:

    [[SnippetName]]

    If you are passing parameters to the snippet, you add a question mark to the end of the snippet name and add the parameters, preceded by an ampersand:

    [[SnippetName? &parameter1=`21` &parameter2=`Here is a string of text`]]

    The snippet will interpret the parameters into the output. Notice that the parameters are contained within backtick marks: ( ` ) rather than quotation marks ( ” or ‘ ).

    Snippet: “Wayfinder” — Creating Navigation Menus

    You should take advantage of the Wayfinder snippet to automatically generate navigation menus. Wayfinder creates an unordered list that can be styled in many different ways. The snippet is embedded in the template like this:

    [[Wayfinder? &startId=`[[UltimateParent]]` &level=`1`]]

    Notice that the UltimateParent snippet is embedded within the Wayfinder snippet. The UltimateParent snippet finds the topmost page in the hierarchy and generates the id number of that page. The Wayfinder snippet generates the menu system as an unordered list, based on the children documents of the document referenced by the startId parameter, which in this case is the topmost page in the hierarchy. You can also create menu systems for pages deeper down in the site hierarchy. The &level parameter tells the Wayfinder snippet how deep to look within the hierarchy when generating the menu. With the level set to 1, the menu will consist only of the immediate child documents. With level set to 2, it would look at the child and “grandchild” documents.

    The Wayfinder snippet can also be used to generate a list of all pages in a certain directory, even if the list is not meant to be a navigation menu per se. Wayfinder will create a bulleted list of the pages, with each page title as a link to the page itself.

    Snippet: “Ditto” — Using Data from other Pages

    Ditto is a snippet that can pull in data from other pages, including not only the standard page variables (pagetitle, longtitle, content, etc.), but also the template variables. If you have a template for entering data about people, such as first name, last name, email, etc., you can pull in this information from multiple pages and display it on a single page. Here is an example of a Ditto call:

     [[Ditto? &parents=`11` &depth=`1` &tpl=`people` &sortBy=`lname` &sortDir=`ASC`]]

    In the above example, the Ditto snippet will display data from all of the pages immediately below document 11 (id=11). It will not include data from pages further down in the hierarchy because we have limited the scope to &depth=`1`. We format the data using the chunk called “people” with the &tpl=`people` parameter (tpl stands for “template”, but these are mini-templates, not complete web pages). We’re sorting the pages by last name, as specified with &sortBy=`lname`. The “lname” field is a template variable that would have been created before hand (there is no “lname” field unless you create a template variable by that name). The sort order is ascending, as specified by &sortDir=`ASC` (sortDir stands for “sort direction”).

    Ditto is a powerful and somewhat complicated snippet. Refer to the documentation at http://ditto.modxcms.com/ for more information. The list of Ditto parameters (http://ditto.modxcms.com/files/snippet-ditto-php.html) is especially helpful.

    The chunk that contains the mini-template must also contain placeholders for the different data fields. Placeholders are designated by brackets and plus symbols; for example: [+my_placeholder+]. The chunk for the above example might look something like this:

    <p>Name: [+fname+] [+lname+]</p>
<p>Email: <a >href="mailto:[+email+]">[+email+]</a></p>
<p>Biographical Sketch: [+bio+]</p>

    Each placeholder above refers to the name of a template variable which would need to be defined beforehand.

    Snippet: “Breadcrumbs”

    The Breadcrumbs snippet allows you to automate the creation of breadcrumbs. Here is an example call for this snippet:

    [[Breadcrumbs]]

    Parameters for this snippet include:

    • &maxCrumbs
    • &pathThruUnPub
    • &respectHidemenu
    • &showHomeCrumb
    • &showCrumbsAtHome
    • &showCurrentCrumb
    • &currentAsLink
    • &crumbSeparator
    • &homeCrumbTitle
    • &homeCrumbDescription
    • &titleField
    • &descField

    For more documentation, see http://wiki.modxcms.com/index.php/Breadcrumbs

    Snippet: “eForm”

    eForm allows you to create a form that sends the information in an email to the designated recipients. This is a rather robust snippet, and can be somewhat complex to implement, but works quite well when used knowledgeably. Refer to the documentation at http://www.law.gmu.edu/org/assets/snippets/eform/docs/eform.htm for more information, including the examples at http://www.law.gmu.edu/org/assets/snippets/eform/docs/eform_examples.htm.

    Chunks

    In the MODx manager interface, go to Resources > Manage Resources > Chunks to create or modify chunks.

    In MODx, reusable bits of HTML code are referred to as chunks. You
    reference a chunk by it’s name, and put it in braces, like so:

    {{ChunkName}}

    Chunks cannot contain any PHP code, but they can contain references to snippets which do contain PHP code.

    Plugins

    Plugins are like snippets, except that they are activated by certain trigger events, such as when a page is rendered, or when a user saves a page, and so on. You probably don’t need to create a plugin for most things. Snippets are the best and safest option. The danger with plugins is that they run on all pages whenever the trigger is activated, so if you create a plugin with a syntax error in the code, you may bring down the whole site. So be careful.

    Plugin: “PHx” — Extensible Placeholders

    One useful plugin that is already installed in the system is called PHx. This plugin allows you to extend the behavior of placeholders. You can give them logical if/then conditional constructions, convert the content to all upper or lower case, and format the placeholders in many ways. Here is an example of an if/then conditional statement:

    [+phx:if=`[+pref_name+]`:isnot=``:then=`[+pref_name+]`:else=`[+fname+]`+]

    This statement says to display the pref_name (preferred name) template variable if it is not empty. Otherwise it will display the fname (first name) template variable. There are many ways to use this plugin, with multiple syntax variations. Refer to the PHx documentation for more information.

    Plugin: “Page TOC Generator”

    Another useful plugin is the Page TOC (Table of Contents) Generator. This allows you to automatically create a page-specific table of contents based on the headings on that page. Detailed instructions are found at http://modxcms.com/Page-TOC-Generator-0.9.2-1731.html.

    To simplify things, I have created a few chunks of HTML code that condense some of the more common TOC parameters. To create a table of contents based on all of the <h2> elements on a page, do this:

    {{toc_begin_2}}
Put page content (with headings, paragraphs, etc.) here.
{{toc_end}}

    To create a table of contents based on all of the <h2> and <h3> elements on a page, do this:

    {{toc_begin_2_3}}
Put page content (with headings, paragraphs, etc.) here.
{{toc_end}}

    For other configurations, refer to the Page TOC Generator documentation.

MODX: Getting Started

The George Mason University School of Law uses a web content management system called MODX. MODX allows for template-driven web sites with a great deal of flexibility, and easy editing from anywhere using a web browser. There is no need to install HTML editing software, FTP software, or anything else. Just log in and begin editing the web site.

Overview of the Interface

Navigation Tabs: The navigation tabs at the top of the interface allow access to the various parts of MODX. Depending on what level of permissions you have, you may see only one tab or up to 6 tabs. The “Site” tab allows access to pages for editing. The “Resources” tab allows access to files (PDF, Word, etc.), and, depending on your level of permissions, may allow access to templates, PHP code, and other features. The other tabs, if present, allow access to more advanced administrative functionality.

Document Tree: You’ll see a list of the pages that you have permission to edit in the left hand column. If there are container pages (“folders”), you will see a plus symbol next to the page name. Click on the plus to expand the list of pages within that container.MODX

Main Window: The main window to the right of the document tree is where you can edit pages and perform other actions.

Editing Pages

There are two ways to begin editing a page:

  1. Click on the page in the document tree, then click on “Edit” at the top of the Main Window, OR
  2. Right-click on the page in the document tree, then select “Edit document” from the menu

Once you are in editing mode, you will need to fill out some information in the top of the Main Window:

Title: This is the <title> HTML element which will show up in the title bar of the browser (above the “File” and “Edit” menus of the browser).

Long Title: This is the main heading in the content of the web page (using a <h1> HTML element). Usually the Title and Long Title contain the same text.

Document’s Alias: This is the “file name” of the page, which will show up in the web address of that page. For example, the alias of the Faculty section of the web site is “faculty” and the full web address is http://www.law.gmu.edu/faculty.

Template: The template is probably already selected, and probably does not need to be changed. There are specific templates for each section of the web site. Using the wrong template can give the page the wrong look, or break the page’s functionality in other ways.

Menu Index: This refers to the order of the pages in the Document Tree in MODX. The Menu Index can also used to display navigation menus on the public side of the web site. The pages will be ordered alphabetically if the menu index is the same (for example “0”) for all of the pages within a given directory. For the main Law School web site, the number 990 should be typed in as the default Menu Index. Other sub-sites may use different numbers. (Using a large number like 990 allows you to type in lower numbers later on for other pages, if you want them to appear at the top of the menu system.)

Show in Menu: If this is selected, it makes the page available to scripts that can generate navigation menu systems on the web site. Not all folders or pages are used by these scripts, but with the “show in menu” option checked, the pages will show up in the menu; with it unchecked, they won’t show in the menu.

Document Content: This is where you edit the main part of the web page. Most user accounts have a word processor style interface here, so you don’t need to know HTML markup code.

  • Links:
    • Links to external web sites: Select the word(s) that you want to make clickable, then click on the link icon (which looks like a chain link). Type in the full web address of the link (including the “http://”)
    • Links to pages within MODX: It’s best to use the MODX ID of the page, rather than the path or file name. Click on the link icon, then type the MODX ID using this format: [~1234~] where “1234” is the MODX ID of the document. The brackets and tildes (~) are required. How do you find the MODX ID? Look at the number in parentheses after the page name in the Document Tree. Note: You may not have permission to see all of the files in the MODX system. If that is the case, you will need to use the path of the file, relative to the root directory of the site. The link to the faculty page would look like this: “/faculty”. The link to a page deeper in the system would look something like this: “/faculty/news/details”. But if the ID number is available to you, please use it! It is definitely the preferred method.
    • Links to files (Word, PDF, etc.):MODX Click on the link icon, then click on the red/white/blue icon to the right of the “link URL” field. Browse to the folder where the file is (or where you want to put the file). Click on the file to select it, or use the features at the bottom of the file browser to upload a new file. Remember to first go to the correct directory before uploading it!
  • Headings: Always use real headings (not just big bold text, for example). Choose the appropriate heading from the “Format” drop-down list. The “Long Title” is heading 1, so any headings in your content should start with heading 2.
  • Text alignment: Use the “Styles” drop down menu to align text left, right, center, or justified.
  • Images: To insert an image, put your cursor where you want the image to be, then click on the icon that looks like a tree. You can either use an image that’s already on the web site, or else upload a new image. Either way, you will need to click on the red/white/blue icon to the right of the “Image URL” field. This will bring up a file browser. Either choose an image from among the existing ones, or use the features at the bottom of the file browser to upload a new image. Make sure you upload it to the correct directory! (You must be in the correct directory before you upload the file.)
  • Other options: On most pages, the other options (description, summary, menu title, etc.) are not required, and can be left blank.

Creating New Pages

To create a new page, go to the Document Tree, find the folder where you want the document to be, right-click that folder, then select “Create document here.” Then fill in the information for that page in the Main Window.

Other Features

MODX has many other features. This tutorial will be expanded over time to give more information about those other features.