Commerce v1 Front-end Theming

The Commerce front-end and admin are both built with the Twig templating language.

Twig is similar to the MODX template language, however it's more powerful as it allows conditionals, loops and custom functions. With these features you get more flexibility in output, while drastically reducing the number of individual templates needed. Learn more about the Twig syntax and features here.

The Commerce templates are stored in files, which makes it easier to edit with an IDE like WebStorm/PhpStorm, Sublime Text or Notepad++. Files are also easier to include in version control systems like git.

Disabling the Default CSS

Commerce includes a very simple cart and checkout design out of the box. To disable it, set the commerce.register_checkout_css system setting to 0.

Default Template Files

The default templates for Commerce are stored in core/components/commerce/templates/default/. The files in this folder are overwritten on upgrade, so do not edit them.

Overriding Template Files

To override template files, create a new folder in core/components/commerce/templates/ and create files with the same name as the files in the default folder. Then set the commerce.theme setting to the name of your directory.

For example you might create a directory core/components/commerce/templates/premiumshirts/ and set the commerce.theme setting to premiumshirts.

With the directory in place, you can copy files from their location in the defaults folder, to the same location in your own theme folder. To edit the cart you would copy core/components/commerce/templates/default/frontend/checkout/cart.twig to core/components/commerce/templates/premiumshirts/frontend/checkout/cart.twig and make your changes there.

Note: Do NOT copy all directories and files into your own templates folder blindly; only copy the files you're actually changing. That saves you effort and makes it crystal clear what files are different from the default and may need changes, while also automatically giving you fixes in the default templates where possible.

Note2: Do NOT copy/overwrite the admin templates. While it's technically possible to change the admin templates the same way as front-end templates, we do not currently support custom admin templating and may at any time introduce backwards incompatible changes if you do copy/change admin templates.

Custom Theme Folder

It's also possible to place your theme folder outside the Commerce directories. This is recommended, but as shown before not necessary.

The setting you'll need to update for this is commerce.themes_path. Set this to a fully qualified server path that contains your theme directory. It's possible to use {base_path} and {core_path} values to make the path relative to the base or core path respectively.

To give an example, if you want your theme files in assets/templates/webshop/, you would set:

  • commerce.theme to webshop
  • commerce.themes_path to {base_path}assets/templates/ - note the trailing slash is required.

Theme inheritance

Assuming commerce.theme is set to webshop and commerce.themes_path is set to {base_path}assets/templates/, Commerce will check for matching template files in the following order.

  1. {base_path}assets/templates/webshop/
  2. {core_path}components/commerce/templates/webshop/
  3. {core_path}components/commerce/templates/default/

If it finds the requested template file, it stops there, otherwise it checks the next path. This means you only have to copy the templates you're actually customising; any others will simply fall back to the default.

Different themes per Context

With Contexts in MODX, you can use different Commerce themes for different contexts. To use this, create commerce.theme and/or commerce.themes_path context settings for the specific context.

Note that the Commerce admin area will not use context-specific themes unless you specify the setting on the mgr context. We don't recommend making changes to the manager dashboard for now, to ensure things don't break in a weird way while we continue to evolve that.

Different themes for User (Groups)

Another fun trick is to set specific themes on specific users or user groups in the same way as context settings, by adding the commerce.theme and/or commerce.themes_path setting to a user or user group.

Due to the MODX setting inheritance, user or user group settings will take priority over context and system settings.

It's not recommended to do this for customer user (groups), however it could be useful for allowing admin users to preview a new theme when the site is live. Keep in mind though that the users need to be logged in to the frontend (e.g. using the Login snippet) for this to work.

Debugging templates

Sometimes you may want to know what exact information is available to you in a specific template.

First, create or change the commerce.debug system setting, and set it to 1.

Then, in your template, you can use the dump function. For example:

{{ dump() }}
{{ dump(order) }}

When you've launched your shop, set commerce.debug to 0 to make sure no stray dump functions are used in your templates.