George Mason University Antonin Scalia Law School

Using MODx: Tips For Editors


How to Create Internal Links With Resources IDs

In MODX, Resource IDs are the numbers assigned to a Document. For example: About Scalia Law (2). To link to the about page, use the following code:

<a href="[[~2]]">About Scalia Law</a>

How to Create an Anchor Link

To point to an anchor link within a page, use the following shortcode.
<a href="[[~[[*id]]]]#anchorname">Anchor Name</a>

To point to an anchor link on a different page, use the following shortcode:
<a href="[[~2]]#mason">About Mason</a>

Source

Installing an SSL Certificate on Apache

DigiCert:

Godaddy:

Guide:

Once a certificate and key have been purchased and generated, you will need to upload the files to your server.

If FTP is enabled on the server I would recommend Filezilla or CyberDuck FTP Clients to upload your files.

Once the files are uploaded, SSH into the server and sudo mv the files into the /etc/ssl/ directory.

Next, setup your virtual host for port 443. Before you get started, make sure your server has an SSL Engine. If not, you may need to install mod_ssl. To run the mod_ssl install command use the following code:

yum install mod_ssl

Now you will be able to setup the virtual host by configuring the Apache mod_ssl module. On a standard install, the file may be located at /etc/httpd/conf.d/ssl.conf.

The default file will have a number of instructions interspersed between lines of code. The most important lines of code will need to be edited with your server and sites information. See below: (be sure to remove quote marks when entering your information)



...
SSLEngine on
SSLCertificateFile "/etc/ssl/signed certificate"
SSLCertificateChainFile "/etc/ssl/intermediate_certificate"
SSLCertificateKeyFile "/etc/ssl/private/key"

# Uncomment the following directive when using client certificate authentication
#SSLCACertificateFile /path/to/ca_certs_for_client_authentication

...

Test your Apache configuration using the following command:

apachectl configtest

If no errors have occurred, restart Apache to complete the SSL configuration. Use the following command:


apachectl stop
apachectl start

Your website will now have a green padlock when using the HTTPS protocol. To redirect all non secure traffic automatically to HTTPS, edit your site’s non-secure port 80 Virtual Host.

On a standard install, this file would be found in /etc/httpd/. Edit the virtual host using the following (be sure to remove quote marks):


ServerName "Site's url (don't include protocol) ex: mysite.example.com"
DocumentRoot "Site files directory ex: /var/www/html/site"
Redirect permanent /secure "Site's url with new secure protocol https://mysite.example.com/"

Restart Apache and you’re all set.

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>

Homepage Featured Events Display Using DOM

The featured events on the Mason Law homepage is pulled from the master calendar’s RSS. To get the dates and times separated from the titles, accessing the DOM is needed. The following codes, which requires jQuery, make the magic happened:

$('.rssItemLink').each(
function(){
$this = $(this);
$this.
html('<em>' +
$this.
html().
replace(/((\d{1,2}\/){2}\d{2,4}\s*[0-9]{1,2}:[0-9]{1,2}\s*[apAP][mM]\s*to\s*[0-9]{1,2}:[0-9]{1,2}\s*[apAP][mM])/,
'</em><b>$1</b>'
)
);
}
);

Sticky Nav on Scroll

Here’s a little JavaScript function to make your site’s header or navigation stick to the top of the window when users scroll the page:

HTML:

<div id="navigation">
  <!-- your navigation code -->
</div>

CSS:

#navigation{
  position:absolute;
  top:120px;
  left:0;
}
#navigation.fixed{
  position:fixed;
  top:16px;
}

JavaScript:

// Handles the page being scrolled by ensuring the navigation is always in view.
function handleScroll(){
  // check that this is a relatively modern browser
  if (window.XMLHttpRequest){
    // determine the distance scrolled down the page
    var offset = window.pageYOffset
               ? window.pageYOffset
               : document.documentElement.scrollTop;
    // set the appropriate class on the navigation
    document.getElementById('navigation').className =
        (offset > 104 ? 'fixed' : '');
  }
}
// add the scroll event listener
if (window.addEventListener){
  window.addEventListener('scroll', handleScroll, false);
}else{
  window.attachEvent('onscroll', handleScroll);
}

Source: “Detachable navigation using JavaScript

EMS Master Calendar Modification

  1. Connect to the server via Microsoft Remote Desktop
  2. Locate: C:\inetpub\wwwroot\MasterCalendar (under My Computer, C drive)

In order to add the Mason Law logo in the master calendar of events, I had to modify the master template file (Calendar.master). Scroll down to line 105, you’ll see this:

<div>
<input type="hidden" name="__VIEWSTATEGENERATOR" id="__VIEWSTATEGENERATOR" value="28B11E50" />
<input type="hidden" name="__VIEWSTATEENCRYPTED" id="__VIEWSTATEENCRYPTED" value="" />
</div>
<div id="ctl00_HeaderContainer" class="HeaderContainer show-large">

<!--MASON LAW BY DONNY-->
<div style="background-color:#063; width:100%;"><a href="https://www.law.gmu.edu/"><img src="https://sls.gmu.edu/cdn/shared-img/cal-head-logo.png" alt="Antonin Scalia Law School, George Mason University" ></a><a href="http://events.law.gmu.edu/MasterCalendar/"><img src="https://sls.gmu.edu/cdn/shared-img/cal-head-text.png" alt="Calendar of Events" ></a></div>
<!--/MASON LAW BY DONNY-->

<div class="row po">
<div class="twelve columns">
<div id="ctl00_Header_imgBannerDiv" class="imgBanner centered pointer"><img src="http://events.law.gmu.edu/MasterCalendar/ImageWriter.aspx?data=IPkf9F3DB014d7Mcuxnr02hg194Zr%2fYICmc%2b3DyQmrlgKN39%2bJJQUIYsuFOrpOhm" alt="Banner Image" style="border-width:0px;" /></div>
</div>
</div>

This template needs to be update every time the EMS calendar is upgraded.

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.