General MODX Training

What is MODX?

MODX is a web-based Content Management System (CMS) that allows you to manage the content of your site. See our MODX Glossary for terminology used throughout your dashboard.

Browser Support

All of our sites are designed to work in Penn’s current supported computing products.

How Do I Log In?

*Login requires a PennKey.

1. Go to the site manager URL:
   • If your site is in development, go to: https://cmsdev1.pmacs.upenn.edu/SITENAME/manager/
     *update SITENAME with your account name​​​​​​​
     • Note that, in order to edit the site in development from outside the United States, you will need a PMACS account and access set up via Pulse Secure. If you don’t already have that, please submit a ticket or call 215-573-INFO to get setup. 
   • If your site is live, go to: http://www.med.upenn.edu/SITENAME/manager/
     ​​​​​​​*update SITENAME with your account name
2. Enter your PennKey credentials and click “continue with PennKey” to proceed to the dashboard.

What is the Dashboard?

The dashboard is the user interface when you login to manage your site. It is organized with information about your site and includes resources to help manage your site. The dashboard includes the following:

• a top menu bar
• a lefthand side box with Resources and Files tabs
• the publisher dashboard on the right with Manager Quick Start, Custom Instructions, Recently Edited Resources and Who’s Online sections

Top Menu Bar

The menu bar along the top of your window will appear on every page in your MODX manager view.

The menu bar includes the following:

• MODX Logo: click to navigate back to the dashboard you first see when you log into the manager.
• Site title: the site name/title is displayed next to the MODX logo.
• Search: click the search icon that displays a search form to search resources by page title.
• Content: includes quick links to New Resource and Preview Site.
• Media: includes Media Browser, the file library.

Resources & Files

On the lefthand side of your dashboard, there is a box with tabs for Resources and Files (see image to the right). It is included on every page in your MODX manager view.

Resources

The Resources tab displays icons that are quick links to create/delete a resource and a list of all the resources on your site in the order it displays in the navigation and breadcrumb. In the list of resources, the following information can be gathered about each resource at a quick glance:

• the resource ID# - an auto-generated unique identifying number displayed in parenthesis
• the type of resource which can be identified by the icon in front of the resource title:
  • file icon is a document
  • link icon is a weblink
  • file icon with 3 lines is a static resource
  • house icon is the home page
  • 3 cogs icon is the Global Settings page
  • down caret & folder icon is a container with nested page(s)
    • Note: if there is no down caret and just the folder icon, the resource is set as a container with no nested page(s)
• the status of a resource
  • lighter grey text is a resource that is hidden from the navigation menu
  • italicized text is a resource that is not published
  • red and has a strikethrough text is a resource in the deleted state, ready to be permanently deleted

Files

The Files tab allows you to view all files uploaded to the file system at a quick glance. You can quick upload, rename, download, or delete files by contextual clicking (right-click or Ctrl + Click) directly in the Files tab. To manage the full library of media files, navigate to the top menu bar under Media and go to Media Browser.

Note: All files should be uploaded into the appropriate directory (documents, images, secure)

Publisher Dashboard

The publisher dashboard is the main section, right of the Resources and Files tabbed box and below the top menu bar. It includes the Manager Quick Start, Custom Instructions, Recently Edited Resources and Who’s Online sections.

To view the publisher dashboard, click the MODX logo.

The Global Settings includes all the global configurations and information for your site. It is located in the Resources tab on the lefthand box. On the Global Settings page, there are 2 tabs: Global Configurations and Global Information.

• Global Configurations includes settings for your site. For example, google analytics is set here by entering your Google Analytics Tracking ID (unique ID to track analytics on your site, managed using the Google Analytics site).
• Global Information includes information that is global and displayed on all the pages within your site. For example, contact information is a commonly displayed globally.

File Types & Size Limit

• Allowed file types for documents: .doc, .docx, .ppt, .pptx, .pdf, .txt, .xls, .xlsx
  • Note: Recommended document format is a PDF file so that the user cannot make any edits or “copy” the information.
• Allowed file types for images: .jpg, .jpeg, .png, .gif
• Max file size: 5MB (the larger the file size, the longer it takes to load on your webpage)

Manage File(s)

Manage files by uploading, renaming, deleting them in the Media Browser, located under Media in the top menu bar.

Upload File(s)

Make sure to upload all files in the appropriate directory: documents, images and secure (PennKey-protected). If you need to upload a file that is beyond the maximum file size allowed, contact us to request a quota increase. Keep in mind, however, that this is a server that provides pages for hundreds of users and departments, and that we have other servers, like media3, that are optimized to host large files. It may be better to get an account on that server instead, or to use Penn+Box.

To upload file(s) in the Media Browser:

• Click the upload icon at the top lefthand corner OR contextual click (right-click or Ctrl + Click) on the directory you want to upload your file to and select Upload Files.
• The upload pop up window will appear. Either drag and drop your file(s) into the window from your computer OR click Choose File(s) and select your file(s) to upload.
• Once all file(s) are selected, they will display as a list.
• Click Upload to upload added file(s) in the pop up window.
• When upload is successful, a confirmation message “Upload Successful!” in green will appear next to each uploaded file.

Rename File(s)

To rename a file:

• Contextual click (right-click or Ctrl + Click) on file.
• Select Rename.
• Edit name and click Save.

Tips for naming files

• Use a descriptive name.
• Use – or _ between the words. For example: ioa-pilot-grants-announcement-2012.jpg.
• Do NOT use spaces within a file name.
• For images only: include unique descriptive ALT tag.

Delete File(s)

To delete a file:

• Contextual click (right-click or Ctrl + Click) on file
• Select Delete File. A warning pop-up window will appear.
• Click Yes. If you still see the file, refresh your page.

Note: Once you delete a file, it is permanently gone from your file system.

Edit Image(s)

Edit/crop images before uploading to the images directory within the file system. All images in richtext areas should be edited before including on your site. Images with set sizes include a built-in cropping tool and do not need to be cropped beforehand.

For photo-editing tools suggestions, go to Manager Quick Start in your publisher dashboard and click the Photo Editing button.

Resource ID#

The resource ID# is the unique identifier assigned to each resource. This ID# is used when you link to a page within your site.

Resource Types

A resource is a representation of a page in MODX and there are 3 types of resources you can create on your site.

• Document: basic webpage, most commonly used
• Weblink: link to an external website
• Static resource: link to a PDF or Word Document file

Other types

• Container: a folder/container
  • Note: if there is a down caret along with the folder icon, it indicates you can toggle the container open/close to see/hide nested page(s)

These resource types are specific to the navigation. For example, you would only use a static resource to add a navigation item that is linked to a PDF.

Status of a Resource

• lighter grey text is a resource that is hidden from the navigation menu
• italicized text is a resource that is not published
• red and has a strikethrough text is a resource in the deleted state, ready to be permanently deleted

How to Create New Resources

In the Resources tab, there are icons that are quick links to create any one of the 3 types of resources (see image to the right). Each resource type has specific fields for the content type. See instructions for each resource type below.

Document Resource

To create a new document, a web page:

• Click the paper icon in the Resources tab.
• Fill in fields for the document
• Click Save.

Weblink Resource

To create a new weblink:

• Click on the link icon in the Resources tab.
• Add title, resource alias and set Uses Template to ‘(empty)’ (*required).
• Weblink: copy and paste the URL of the desired linked website.
• Click Save.

Static Resource

To create a new static resource:

• Click on the file icon in the Resources tab.
• Add title, resource alias and set Uses Template to ‘(empty)’ (*required).
• Static Resource: click on file icon (far right) to navigate your file system and select your PDF file.
• Switch to the Settings Tab, go to the Content Type dropdown and select PDF or Word Document.
• Click Save.

Duplicate an Existing Page

To duplicate a page:

• Go to the page you wish to duplicate.
• At the top right, click Duplicate next to Save.
• A box will appear asking if you want to duplicate this page, click Yes.

There are 2 identical pages with the newly duplicated page highlighted with a new ID# in the Resource tree. The duplicate document will appear on your screen with no value for the resource alias. Update the resource alias along with additional changes and click Save.

Delete a Page

To delete a page:

• Contextual click (right-click or Ctrl + Click) on the resource title in the Resources tab
• Click Delete.
• A pop-up menu will display asking if you are sure you want to delete. Click Yes.

The page title will now display as red strikethrough text in the Resources tab to reflect the deleted state. The deleted page is no longer published and cannot be edited but it is also not permanently deleted yet.

How to Recover a Deleted Page

A deleted page that is found in the Resources tab in red strikethrough text is not permanently deleted and can be recovered. To recover the page:

• Contextual click (right-click or Ctrl + Click) the page.
• Click Undelete.

How to Permanently Delete a Page

To permanently delete page(s) in the deleted state with red strikethrough titles in the Resources tab:

• Click the trashcan icon in the Resources tab.
• A list of resources ready to be deleted will appear In the Trash Bin tab.
• To delete select resource(s), select the resource(s) you want to delete, click ‘Bulk Action’ dropdown and click ‘Purge selected resources’.
• To delete all resources listed, click ‘Purge all’.

Page Reorder

The reordered list will reflect in your site navigation and breadcrumb.

To reorder pages:

• Go to the Resources tab to the list of resources on your site.
• Click, hold and drag any page up or down to reorder.

Your site navigation can be organized with nested/child page(s), which is a second level of navigation, also called submenu.

A navigation item that has nested pages, a submenu, are called containers or parents. Containers/parents are not pages themselves but categories that hold the nested pages.

How to Create a Container (Parent)

To create a container:

• Create a new document
• Add a title, resource alias, set Uses Template to ‘(empty)’ and  check Published so the nested page(s) are visible in the browser
• In the Settings tab, check the box that says Container to indicate it is not a web page and just a container navigation item with nested page(s).
• Click Save.

A resource that is a container can be identified in the Resources tab with a folder icon in front of the resource title. If the container has nested page(s), it will also have a caret icon in front of the folder icon as well.

Auto-generated Container Overview Pages

If a page is a container that has Uses Template field set to “Subpage Template” and content, the content will display as a separate page that is autogenerated and by default called “Overview”.

Follow steps in How to Create a Container (Parent) and set Uses Template to “Subpage Template” along with content to the container page. Remember to make all edits to the Overview page content directly in the Container page.

How to Add Nest (Child) Page(s) to a Container

In the Resource tab, reorder the child page to be nested in a container. Be sure to directly place the child page on the container, not below.

Any resource that is a container with nested page(s) will display a down caret, folder icon and resource title. The caret icon allows you to toggle the container open and close to view or hide all the nested page(s)

Breadcrumbs display the user’s location in a website and are displayed on all subpages. The breadcrumb is a list that reflects the organization of your pages so it is important that child pages are nested correctly. For example, a faculty profile page should be properly nested within the main Faculty page (Home > Faculty > Profile Page).

Document Tab

The Document tab is the default tab view with most of the page properties and all features available to the template set are located here. Be sure to fill in values for all the required fields in order to save the page.

Title

The Title field is a required field on all resources and is used as the main page title.
The Title populates:

• The title displayed in the Resources tab
• Default page title at the beginning of the page content, unless the Long Title is specified
• Title displayed in the navigation, unless the Menu Title is specified
• The title displayed in the browser tab

Long Title

This is an optional textfield to display a different page title than the Title. If the field is left blank, the Title will display as the page title by default.

Uses Template

Uses Template is a required field that allows you to set a template for your page, applying the site design and included features specific to the template. It is a required setting on all pages except the Global Settings page and the Home page. The Uses Template field is not available on the Global Settings and Home pages as they each have a unique template that is exclusive to these pages and set on the pages already. You may have more template options depending on the design of your site. Additional templates would be included in the custom instructions found on the dashboard.

Description (Meta Description)

The Description field is a page-specific meta description used in search listings. The description should be a brief summary of the web page. This field is set per page and is optional.

Menu Title

The Menu Title is an optional field that allows you to display a different title for the page than the Title in the navigation. It is commonly used to display a shorter title in your navigation. If the field is left blank, the Title will display in the navigation by default. For example, a page title like ‘About the Institute for Translational Medicine and Therapeutics’ can have the Menu Title ‘About Us’ for the navigation.

Hide From Menus

The Hide From Menus checkbox determines if the page should display or be hidden in the navigation. Any resource with Hide From Menus checked will be lighter gray in the Resources tab view.

Published

The Published checkbox determines the page visibility on the web. Any resource with Published checked can view the page in the browser. When a page is unpublished and does not have Published checked, the page in the Resource tab will be italicized.

Content

The Content area is the richtext area where all the main content of your page is included. 

Settings Tab

There are only a few properties for your web page to set in the Settings. All other fields/checkboxes should be left alone. Here is a list of properties on the Settings tab:

• Parent Resource: manually set a web page to be a nested/child page of a container.
• Resource Type: set which type of resource you are using: document, weblink, static resource, symlink.
  • For all documents, it should be set to HTML and this is the default value.
  • For static resources, it should be set to PDF or Word Document.
• Published On: by default, this field gets auto-populated by the date and time that the page is created
• Publish Date: option to set a date for the page to be published and go live
• Unpublish Date: option to set a date for the page to be unpublished and not accessible on your site
• Container: check the checkbox set the page as a container with nested page(s)
• Searchable: check/uncheck the checkbox to show/hide the resource from appearing in the sitemap

A template applies a consistent design and layout on all the pages within your site. Each template includes varying features along with page content and global information.

Homepage Template

The Homepage Template is unique to the homepage. It includes its own set of features, called "template variables" in MODX.

Subpage Template

The subpage template should be used for all pages of your site, excluding the homepage.

Rich-Text Editor Toolbar

In the Content area, the richtext editor includes a toolbar above the content area box.

Copying and Pasting Content

Copying and pasting content from other programs is a common practice. When copying/pasting content, styles get copied over as well. To ensure that all styles are removed to keep styles consistent with the site design, follow these steps: 

• Copy and paste into the Content richtext area
• Manually highlight or select all of the pasted content
• Click the button to remove format on text (see 8.1 Rich-Text Editor Toolbar image)

Page Structure using Headings

Heading styles are used to structure your content and create hierarchy of information. All other content that is not a heading should use Normal to display as paragraph text. For more information, go to the Typography Tips page.

In the toolbar under the Format dropdown, you can find the following paragraph format options: Normal, Heading 2, Heading 3, Heading 4, Heading 5 and Heading 6.

Styling Content

Basic Content Styles

Common text styles included are bold, italic, subscript and superscript. We strongly suggest not to use underline as it can
be identified as a link. For more information, go to the Typography Tips page.

Blockquote

Highlight quotes by using the blockquote style.

• Highlight blockquote text.
• Click the double quote icon in the toolbar (see 8.1 Rich-Text Editor Toolbar image).
• Click Save and preview the page to view the blockquote styled.

Lists

Numbered and bulleted lists are available in the toolbar. To create a sub-item within the list, use increase indent or the Tab key on your keyboard. To decrease indent, click the left arrow in lines icon or SHIFT+Tab.

Links

Link to a Page within Your Site

• Highlight the word(s) you want to link.
• In the Resources tab on the lefthand side, locate the page you want to link to.
• Click on the page, drag and drop the page onto the highlighted word(s) in the content area.

When linked successfully, a little green checkmark will appear and the word should change to blue with an underline.

To manually link a word to a page within your site:

• Highlight the link word(s).
• Click the link icon in the toolbar and the link pop-up window will appear.
  Set the following:
  • Link Type: URL
  • Protocol: <other>
  • URL: [[~ID]] * Replace ID with resource ID 
• Click OK and the word should be linked properly.

Link to a URL

• Highlight the link word(s).
• Click the link icon in the toolbar and the link pop-up window will appear. 
  Set the following:
  • Link Type: URL
  • Protocol: http://
  • URL: go to the site you want to link to in your browser, copy and paste into the textfield
• Click OK and the word should be linked properly.

Link to a File

• Highlight the link word(s).
• Click the link icon in the toolbar and the link pop-up window will appear.
  Set the following:
  • Link Type: URL
  • Protocol: <other>
  • Click Browse Server and navigate the file system to select your file
  • URL: this will be auto-populated once you select your file using Browse Server
• Click OK and the word should be linked properly.

Link to an Email

• To link to an email:
• Highlight the link word(s).
• Click the link icon in the toolbar and the link pop-up window will appear.
  Set the following:
  • Link Type: E-mail
  • E-mail Address: include email address
  • Message Subject: this field is optional, include a pre-populated message subject as needed
  • Message Body: this field is optional, include a pre-populated message subject as needed
• Click OK and the word/email address should be linked to an email.

Link to a Phone Number

• Highlight the link word(s).
• Click the link icon in the toolbar and the link pop-up window will appear.
  Set the following:
  • Link Type: URL
  • Protocol: <other>
  • URL: tel:+1-215-000-0000 (replace number with real phone number)
• Click OK and the word or phone number should be linked to a phone number. On mobile devices, this will provide the option to call the linked number.

Create and Link to an In-Page Anchor

In-page anchors can be added to the content of your page to word(s) can then be linked to the anchor on the page.

To create an anchor:

• Click your cursor in the content to the location where you would like to add an anchor. It is usually created for subsections within the page.
• Click on the Anchor icon in the toolbar which looks like a little flag.
• Name the anchor something meaningful so it can be easily identified when you are linking to it.
• Click OK and a red flag will appear to indicate the anchor.

Link word(s) to anchor on the same page:

• Highlight the link word(s) and click on the link button. A pop-up window will appear.
  Set the following:
  • Link Type: “link to an anchor in text”
  • By Anchor Name: select the anchor name you want to link to
• Click OK and the word should be linked to the specified anchor on the page.

Link word(s) to anchor on a different page within your site:

• Highlight the link word(s) and click on the link button. A pop-up window will appear.
  Set the following:
  • Link Type: URL
  • Protocol: <other>
  • URL: [[~ID]]#anchorname
  • Replace ID (see 5.2 Resource ID) and anchorname with appropriate values
• Click OK and the word should be linked to the specified anchor on the page.

Images

Add an Image

To add a new image to your content area:

• Click on the Image button in the toolbar and a popup window will appear.
  Set the following:
  • Add image: click Browse Server next to URL to navigate through the file system to select your image. Make sure the image is already uploaded to the /images directory.
  • Alternative Text: add a short description for the image. This is important for accessibility as screen readers will read the alternative text to describe the image on the web page
  • Alignment: align your image left, center, right, or none
  • Captioned image: check to include a caption, a caption box will appear in the content area once you close out of the pop-up window.
  • Click OK and you should see the image in the Content area.
• If you included a caption, update text.

Crop an Image Using Image Cropper

*This is a new feature in SSFlex added in February of 2021.
Contact us at psom-somweb@pennmedicine.upenn.edu to request this feature.

To crop an image using the image cropper tool:

• Right click your image and select Crop this Image
• Choose the Target Image cropping size (Thumbnail, Medium, Large, Full Width, Free Crop)
• Click Crop to preview your cropped image and then click Save.

Link an Image

To link the image:

• Select image in the Content area or follow instructions to add an image first and then select image.
• Click the link button in the toolbar.
• Set the type of link for the image and link. 

YouTube

Find YouTube video embed code OR URL. Both methods work to include a YouTube video.
To find the embed code and/or URL:

• Go to YouTube and locate your video.
• Below the video, there is an option to Share. Click Share. A pop up window will appear.
• Copy the URL OR click Embed and copy iframe code provided.

Add YouTube video to your page:

• Go to your page in the site manager and click in the Content area where you would like to add your video.
• Click the YouTube button (see 8.1 Rich-Text Editor Toolbar image). A pop up window will appear.
• Paste the copied URL or embed code in the appropriate fields.
• Make sure Make Responsive is checked.
• Click OK and the video should display in your Content area.

IFrame

Embed content using a URL such as a DCI list or a Vimeo video using the iFrame tool.
To add an iframe:

• Click the IFrame button in the toolbar, which looks like a globe (see 8.1 Rich-Text Editor Toolbar image).
• Include iframe content with the URL.
• Click Save.

Tables

To add a table:

• Click the Table button in the toolbar.
• Click ‘more’ at the bottom of the box. A pop-up window will appear.
• Add your table properties by specifying the number of rows, columns and headers as needed.
• Make sure to keep the width and height empty so the table is responsive.
• Click OK. An outline of the table will appear in the Content area and as you enter content, the cells will expand. 

Additional Tools 

There are additional tools available to you. Here are some of the tools listed below:

• Cut
• Paste
• Undo
• Redo
• Horizontal Rule
• Special Characters: characters and symbols
  (!#$%)
• Find & Replace
• Select All
• Spell Checker
• Show blocks: visually defines each
  element such as
  paragraph, table,
  image etc.
• Styles: provides options for visual treatments that can be applied to the content. The available options will vary depending on your site design.

Pennkey Protected pages and files are viewable only to users with a PennKey username and password.

PennKey Protect a Page

To PennKey protect a page:

• Go to the page you want to PennKey protect.
• In the Resource Alias textfield, add ‘secure/’ before the alias name given i.e. secure/contact.
• Click Save.

When the viewer tries to view the page, the PennKey log in page will appear. When they enter their Pennkey credentials, they will be able to view the page.

PennKey Protect a File

The file MUST be in the ‘/secure’ directory before you link it on your webpage, otherwise it will not be protected.

To PennKey protect a file:

• Go to your Media Browser.
• Upload your file to the ‘/secure’ directory to PennKey protect. If the file has already been uploaded, locate the file and drag that file into the secure directory.
  • Note: If you are moving a file from a directory, make sure you relink to the file on your webpage with the updated file location.

Versions allows you to view, compare one version to another and revert to a previous version. In the Versions tab, there is a list of every saved version of your resource with a version number, date, and editor.

To revert to a previous version you have identified in the list of versions:

• Contextual click (right-click or Ctrl + Click) and click Revert Resource to Version # to revert to version.
• A pop up window ‘Are you sure?’ will appear. Click Yes to revert, No to cancel.
• When the page has reverted successfully, a success message at the top right will appear to confirm the change.

To view a previous version:

• Contextual click (right-click or Ctrl + Click) and click View Version Details.
• The page will reload with details, organized into tabs. Look through page details.
• Once you are done viewing the details and want to revert to the version, click Revert Resource OR click Back to Resource to go back to the page.

To view a comparison of 2 versions:

• Contextual click (right-click or Ctrl + Click) and click View Version Details. on the first page you want to view.
• On the details page, click Compare To dropdown and select the second version to do the comparison. You will be able to see each version detail side by side.
  • Note: The first version in the dropdown is the current version of the page.
• Take a look at the difference(s) between the 2 versions.
• If you are ready to revert to the selected version after reviewing the details, click Revert Resource dropdown and select the version you want to save.
• Click Back to Resource to go back to the page and click View to preview page.