Skip to content

Instantly share code, notes, and snippets.

@patrickatwsrn

patrickatwsrn/modx-setup.md

Last active July 31, 2022 14:02
Show Gist options
  • Save patrickatwsrn/0e69a319204f1fcb7069a942a4661b89 to your computer and use it in GitHub Desktop.
Save patrickatwsrn/0e69a319204f1fcb7069a942a4661b89 to your computer and use it in GitHub Desktop.
Download ZIP
Basic MODx setup (German localization)
Raw
modx-setup.md

Introduction

My personal notes for an opinionated MODX setup.

What is MODX?

MODX is an honest down to earth CMS with a whole lot of freedom.

Install MODX

MODX should run on most decent servers.

Procedure

  1. Check the requirements here
  2. Create a new database and add a user. Copy usename, database name and password into a file for later use.
  3. MODX doesn't need all permissions. You may want to set only the required permissions
  • for normal operations: SELECT, INSERT, UPDATE, DELETE
  • for installations and upgrades: CREATE, ALTER, INDEX, DROP
  • for some third party extras: CREATE TEMPORARY TABLES.
  1. Download the latest v2 or v3 version here:
  2. Unzip modx in your webroot for a vanilla install (see hardening for a more secure installation method).
  3. open your setup here: example.com/setup
  4. (2do)
  5. done!

final steps

If you are running an apache server, you shuold rename the following files:

  • /ht.access (basic settings, friendly urls, etc.)

  • /core/ht.access (protect core directory from direct access)

  • /manager/ht.access (you can enforce secure manager access here)

  • Login to your new manager here: example.com/manager

Create status pages

Apart from your content, you web page should have these status pages:

  • site unavailable page (Service Unavailable, error 503): If our page is running under maintenance mode.
  • error page (not found, error 404): If the specific pages is unknown (moved, deleted, etc).
  • unauthorized page (unauthorized, error 401): If a visotor is lacking permission to display a page.

Site unavailable page

You don't want anybody to see what you are doing during development...

  1. create a new resource
  2. set the basic template to none
  3. write something meaningful into the content textarea
  4. publish the resource
  5. update your system settings:
  • site_unavailable_page = id of maintenance page
  • site status = no
  1. check your page white a private browser window. It should show you the maintenance page

Error page

Whenever sombody visits a link that is available for some reason, he should see the error page instead.

  1. create a new resource
  2. set the template to none (you can change this later)
  3. write something meaningful into the content textarea
  4. publish the resource, write down the id
  5. update your system settings:
  • error_page = id of error page

Unauthorized page

The unauthorized page is a resource you want to send users to if they have requested a secured or unauthorized Resource.

  1. create a new resource
  2. set the template to none (you can change this later)
  3. write something meaningful into the content textarea
  4. publish the resource, write down the id
  5. update your system settings
  • unauthorized_page = id of unauthorized page

Download and install add-ons

What are addons?

Addons (plugins) add new functions to MODX. Some addons like extend the modx user interface on the manager side (collections, clientconfig), other addons give you the tools to create a particular type of content on the frontend side (formit, pdoTools). Most frontend addons don't come with complex layouts, instead the offer you some example code and all the tools need to create your own personal solutions.

"core" addons

There are a couple of add-ons available from the official modx.com repository you'll propably need in most of your projects.

My personal favorites

  • "translit" - Fixes special characters like german umlaute for urls, etc. After 12 years it is still "1.0.0-beta", but it does the job beautifully.
  • "ace" - code editor with syntax highlighting
  • "client config" (optional) - adds a simple interface for client related data you can use in footers (phone numbers, etc)
  • "collections" - adds a special interface that makes working with child resources more comfortable
  • "formit" - handles everything releated to forms
  • "modeDevTools" - useful to find and replace code in chunkes, snippet and plugins
  • "pdoTools" - a extremely collection of useful snippets used to retrieve content from your site.

"modmore" addons

The awesome folks at Modmore offer a a couple of very useful addons. Many of them are free and the premium addons are worth every cent!

If you want to add modmore addons to your site, you need to create a modmore account (don't worry, its free) and create a new api key for your site. Hint: All premium extras can be used for free on a development site. For more details visit this page: https://modmore.com/free-development-licenses/

How to install packages from modmore

  • Create a new account at modmore: https://modmore.com/signup/
  • Create a new api key https://modmore.com/account/api-keys/ (you need a key for each domain)
  • After you have created your api key, drag it into your bookmark tab and then visit your addon page (main menu -> extras -> installer).
  • Now click the api link in your bookmark bar. A new package provider is added.
  • Click on "download extras", then "select provider" and select "modmore"
  • You have now access to modmore addons!

My personal favorites:

  • "ContentBlocks" - Powerful and extremely customizable content manager.
  • "MoreGallery" - Manage you image galleries in a simple interface. Comes with cropping tools and other things.
  • "Redactor" - Extremely customizable richtext eitor

Other package providers

Incomplete list of other providers (may require an account):

"localize" your project (optional)

I'm going to create a page with German content. This language comes with a couple of special characters that need to be fixed for things like urls and filenames. Translit will handle this problem for us automatically:

  • ä becomes ae
  • ü becomes ue
  • ö becomes oe
  • ß becomes ss
  • etc.

Steps:

  • download and install translit (see above)
  • change system settings:
    • friendly_alias_translit = german
    • done!

While we are in the system settings, your might want to edit some language related settings.

Core settings:

  • manager_time_format = H:i (default: g:i a)
  • manager_date_format = d.m.Y (default: Y.m.d)
  • date_timezone = Europe/Berlin (default: empty)
  • locale = de_DE or de_DE.UTF-8 (default: empty)
  • cultureKey = de (default: en)
  • fe_editor_lang = de
  • manager_lang_attribute = de
  • manager_language = de

Note: You can set each system setting for each user individually (see user settings below).

Addon settings (optional):

  • collections.mgr_date_format = d.m.Y
  • collections.mgr_time_format = H:i
  • collections.mgr_datetime_format = d.m.Y H:i (default = M d, g:i a)

You can find a list of available datetimte formats here: https://docs.sencha.com/extjs/3.4.0/#!/api/Date

User settings

User outside the adminstrator group should only be able to change settings that dont have an impact on security and stability. You can use "clientconfig" to provide an interface for such settings.

You might want to change the following settings during development and or for administrators:

  • upload_files - add php,json to the list of files that can be uploaded/edited. NEVER give php to users that dont need to change php files.
  • manager_language - en (my personal preference regardless of target language).

File management

Sooner or late you will have to upload additional files to your server. Some of them will belong to your page design. Other files like images or downloadable pdfs will have a relationship with one or more pages (aka resources).

Note: With a few exceptions (robots.txt, favicon.ico, google webmaster authentication ,etc), all files uploaded through the manager should be stored inside the assets directory.

Media sources

It is a good practice to store uploaded files in a location that is easily found and doesn't mess up your setup.

MODX uses media sources as a solution to this problem.

A media source is a pointer to a specific directory on your file system. Access to a media source can be restricted to specific user groups. You can create multiple media sources. I highly recommend to at least create one media source inside assets/uploads/ where your users can upload images, pdfs, etc.

Examples:

  • assets/tpl/ (for your frontend related files)
  • assets/uploads/ (for general content related files)

Resource specific files

This concept is based on the idea that every resource has a dedicated directory that stores all files used by it.

Example:

  • assets/resources/[[+id]]/

How to create a new media source

  • go to main menu -> media -> media sources
  • duplicate the default (root) media source
  • right click the copy and click update media source
    • change its name and description to something meaningful.
    • add assets/uploads/ to basePath and baseUrl. Don't forget that the path must end with a slash (/).
  • done!

If you are using contentblocks or moregallery, this can be easily achieved by changing the following system settings.

Example:

contentblocks:

  • contentblocks.image.source = id of your media source (2)
  • contentblocks.image.upload_path = [[+resource]]/images/
  • contentblocks.image.crop_path = [[+resource]]/images/crops/
  • contentblocks.file.upload_path = [[+resource]]/files/

moregallery:

  • moregallery.source = 2
  • moregallery.resource_id_in_path = 0 (no)
  • moregallery.source_relative_url = [[+id]]/galleries/

redactor (v3) At this point (MODX 2.8.4 + Redactor 3.1.2 + Contentblocks 1.12.1) "image" and "file" ignore any setting for a resource path. According to Mark this should work an he is investigating.

As I'm not a fan of adding images and files inside a rich tet editor, I'm removing these buttons anyway and I also switch off "drag and drop"

  • Extras -> Redactor Config -> Tooldbar -> Toolbar Buttons -> Remove file and image
  • Extras -> Redactor Config -> Uploads -> Allow drag & drop uploads
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment