The Goal

Integrate the MODX CMF into a Freeway Pro (WYSIWYG) workflow.

Author
Name:
Profession: Designer/Developer/Artist
Specialties: Front-end dev.; hand-drawing
Years’ Experience: 15
Employer: Self-employed
Tutorial Details
Experience Level: Beginner
Noob: No technical skills required.
Beginner: Basic technical skills and knowledge.
Intermediate: Code literate. Strong technical skills.
Advanced: Code “fluent”. Extensive technical skills.
Über Geek: Need I say more?
Skills: MySQL
Tools: MODX, Freeway Pro
Completion Time: 45-60 minutes
Tags: cms, modx, freeway
Memo +
  • Tested with MODX 2.3+ and Freeway Pro 7.
  • Sequel Pro is great for managing local and remote databases. And if you don’t like MAMP PRO there are alternatives.
Examples
Demo file(s) | 165 downloads

This is a member-contributed tutorial. If possible, contact the author with questions or comments.

An Uneasy Union

Updated July 4, 2016
With Freeway Pro’s future unclear for the time being consider this a proof-of-concept only.

MODX Content Management Framework

MODX is a CMS and a multiple recipient of CMS of the Year. In terms of features, capability and flexibility it falls on the Big Boy end of the CMS stick. Some argue the open architecture is better suited to developers (geeks) than designers, but that completely misses the point. MODX is a CMS, not a design application. Yet despite its technical prowess it manages to give the designer a degree of creative freedom many CMS, big or small, are incapable of providing while still offering a measure of plug-n-play1 functionality.

The best word to describe MODX would be “customizable”. Almost every aspect of the application can be modified to meet your needs. This can be a huge selling point if your goal is to provide a truly bespoke editing experience for your client, or yourself. Just because a project is small doesn’t mean it shouldn’t feel like it was tailor-made.

Freeway Pro

Freeway Pro is a WYSIWYG code-generating Web design application. With roots firmly based on the Desktop Publishing (DTP) apps of the 90s it’s not a tool for those who work at code-level. Rather it’s marketed to the visual designer because it shields the user from anything code-related. While it’s an ok, albeit dated app aimed squarely at the point-n-click crowd, it has serious limitations when used in a modern workflow.

All the effort that goes into protecting the user from HTML and CSS often results in an inflexible and awkward tool which limits its usability and over-complicates simple tasks. It often struggles to get out of its own way and can be a challenge to use with industry-standard development tools such as preprocessors, version control, CMS etc.

Target Audience

Freeway Pro users, though I suspect very few will consider using Freeway Pro with MODX. Nevertheless, for those of you with an adventurous spirit there are a few things worth mentioning:

  • If you've used other CMS (with or without Freeway Pro) then you should already be familiar with the concept of ‘tags’ and setting up a MySQL database.
  • Unlike the ExpressionEngine and WebYep Action suites there are no Freeway Actions specifically for MODX. That said, there are two general purpose Actions you will need. See below.
  • You will have to learn about the different types of MODX tags and how to use them.
  • MODX is a very powerful system and is unlike the über lightweight CMS often used with Freeway, e.g., Pulse and WebYep. This is the deep(er) end of the pool.
  • This tutorial only demonstrates a very basic workflow for creating page templates. MODX also uses other types of components: ChunksTemplate Variables and Snippets. Think of them as the smaller pieces that make-up a page. The process for creating these pieces falls outside the scope of this tutorial.

Freeway Actions (required)

Tim Plumb’s Remove Paragraph Tags and Remote Resources Actions.

Updated December 18, 2015
Tim Plumb has updated his Remote Resources Action which fixes resource path issues sometimes encountered when referencing CMS templates in Freeway Pro.

Ok, Here We Go... 

  1. Verify your server meets the minimum requirements for MODX Revolution.
  2. Create an empty MySQL database. This can be accomplished several ways on a local server using Sequel Pro or MAMP PRO (phpMyAdmin). Or remotely using your hosting control panel (cPanel etc.) or Sequel Pro. You will need the database: name, username and password.
  3. Download MODX Revolution (Traditional distribution) and follow the installation instructions.
  4. In Freeway create a new blank file.
    • Important: This tutorial assumes you’re starting from scratch. If you choose to use the demo Freeway file then there will be minor differences.
  5. In Freeway go to Menu > Document Setup > Output > Resources and select Common Resource Folder and enable External style sheets.
  6. Now you need to decide how to organize your templates. You can place them wherever you like: loose in the site root (public_html), in a folder, or deeply nested. It’s entirely up to you. I prefer to keep them in a folder:
    public_html
        templates
  7. Ok, now it's time to create a Freeway page (a.k.a. the MODX template). Name it as you wish, but you must add the Remote Resources Page Action.
    • Important: This is key to correcting Freeway’s path issues when referencing external MODX templates.
  8. In the Actions palette you’ll see a Remote resources URL field. You can either:
    • Leave it blank and Freeway will use a relative resource path: ../css/global.css. Or...
    • Enter your domain with trailing slash http://mysite.io/ and Freeway will create a full url to the resource.
  9. In the template let’s keep it simple: insert a single div — an HTML box — into the page (you can go back later and build a fancy-pants layout).
  10. Now you need to insert a MODX tag into the div. In Freeway you'll use a Markup Item: Menu > Insert > Markup Item... then enter the code as shown, but without the space between the opening/closing brackets:
    [ [*content] ]
    • Important: When inserting a MODX tag into a div (via a Markup Item) you should apply the Remove Paragraph Tags action to the parent container to prevent any ugliness in the rendered output.
  11. Once that’s done publish the Freeway file. The structure should now look something like this2:
    public_html
        templates
            my_template.html
  12. Assuming the MODX install was successful go ahead and sign-in to the Manager (admin area)
    • Important: MODX does not install a Rich Text Editor (RTE) by default, but for this tutorial it’s not required. You can install one later, there are few to choose from.
  13. In the MODX Manager click the Elements tab in the sidebar.
  14. Click the New Template icon.
  15. Give the template a name and enable the Is Static checkbox. This will launch a Static File picker which will open a File Browser.
    • Important: This establishes a connection between MODX and the static HTML files (a.k.a. MODX templates) Freeway generates. While this step is necessary with Freeway it's not strictly required in general use, though I find it makes things easier.
  16. Navigate to and select the (template) file you created above. Click OK then Save (in the floating toolbar).
    • Tip: The template code should now appear in the Template code (html) section of the page you’re currently on, if it doesn't refresh the page.
  17. Click the Resources tab in the sidebar and select the New Document (folder) icon. This is where we create the MODX webpage your visitors will see. The settings in the Settings and Resource Groups tabs you can leave as-is for now, though you will want to learn more about them. Fill in the following fields:

    Title - The page name as seen at the top of the browser window.
    Uses Template - Select the template you created.
    Resource Alias - The name of the page in the url scheme, e.g., http://mysite.com/alias.html.
    • Important: By default MODX will use the Title field as the Resource Alias, but you can change it. It will automatically replace spaces with a hyphen (-), which is good. However, if the Title uses punctuation it might not get stripped out (bad) so please be sure the Resource Alias isn’t malformed.
  18. Add some text in the Content section.
  19. In the floating toolbar Save your changes.
  20. Click the View button in the floating toolbar to see your newly created MODX page using the Freeway-generated template with your newly added content.
    • Tip: If after uploading changes made to the Freeway file you then preview the page in MODX using the View button and the changes are not visible it's most likely because MODX has cached the old page. To clear go to Menu > Manage > Clear Cache and refresh the page. Boo-ya!
  21. Now that you have a working page you can edit the Freeway file as needed, publish the changes and upload. But remember, at this point you’re only using Freeway for layout adjustments and adding editable areas (MODX tags), not for content, that’s what MODX is for.

Having Problems?

If you’re struggling with the MODX side of this tutorial you might find help on FreewayTalk but I doubt anyone over there is using it; not much activity these days. You’re better off joining the MODX Forum which is active and helpful.

Extras, Plug-ins, Add-ons

The default MODX installation is intentionally bare-bones. No Rich Text Editor, no code editor/syntax highlighting, no default Extras (plugins). This is a good thing. It’s up to you to tailor MODX to your needs, so going forward the fun part is adding new tools and functionality. Most likely you will want to add a Rich Text Editor (RTE) and a proper code editor.

MODX offers a few options on both counts but the most flexible and powerful is TinymceWrapper which comes bundled with the Ace and CodeMirror code editors. Though the abundance of configuration options can be overwhelming so you may want to consider one of the other less customizable rich-text options for the sake of simplicity.

More, More, modmore

There’s also the modmore3 site which offers free and premium (paid) add-ons such as the Redactor rich text editor, MoreGallery, and the very cool Content Blocks among others.

Looking for a web host? Try A2 Hosting.*
* Yes, it’s an affiliate link.

Freeway Pro 6 Demo File

For simplicity the demo file uses the Freeway Charcoal template. It's not responsive and has only been slightly modified for this tutorial. You will certainly need a more robust and modern template when working with dynamic content.

Demo file(s) | 165 downloads

1 I’m using the term “plug-n-play” loosely. MODX isn’t point-n-click like Wordpress.

2 If necessary use a FTP client to verify the remote structure.

3 Affiliate link. A modmore account is free.