Themes

While most users will typically only have a single theme, you can have many installed in a site. Themes include all the things needed to create a site except example pages (caveat: see Blueprints below).

Being able to have multiple Themes allows Theme Builders to create and release a variety themes that share common options (Option sets) across Elements.

What makes up a Theme

Themes are made of multiple things:

About Fred Themes
- What makes up a Theme
- Build a Theme to Share

When you create a Theme, Fred will automatically create a directory named for the theme in assets/themes/{{theme-name}}. Use this to store all your theme-specific assets like images, css, fonts and javascript.

IMPORTANT NOTE: As of 1.0, Fred currently does not support exporting Media Sources. If you have used them in your Theme, please include instructions on setting them up in your README file.

Default Element

The default element setting allows you to choose a default Fred Element and target area for placing the content on existing documents. The setting is formatted as UUID|target where UUID is the universally unique identification number of the Fred Element and the target is the HTML object within containing a data-fred-name attribute. This is useful for converting a standard resource to Fred, as it will place the existing content in the default element.

If you aren't finding the UUID of the Fred Element, open an element and look for a display field labeled "UUID".

Theme Settings

Themes can have settings that are used to configure the theme. These settings are stored in the "Settings" section of the Theme. The settings are stored as a JSON object and can be accessed in the theme's twig templates using the theme_setting object. For example, if you have a setting named logo, you can access it in a template like this:

Theme settings are saved in the system settings and can be accessed outside of fred using the theme's Setting Prefix. For example, if the theme's setting prefix is my_theme, you can access the setting logo in a chunk like this:

Theme settings can use any of the setting types described in the option groups documentation.

Format

The theme settings are formatted as a JSON array. Here is an example of a theme setting:

[
  {
    "group": "Look and Feel",
    "settings": [
      {
        "name": "site_color",
        "type": "colorswatch",
        "options": [
          "lightcoral",
          "red",
          "black"
        ]
      },
      {
        "name": "site_logo",
        "type": "image"
      }
    ]
  }
]

One additional option that is specific to Theme Settings is that each setting can have a "global": false flag. This flag will cause the setting to save to the context it is used in, rather than the system settings. This is useful for multi-context sites where you want to have different settings for different contexts.

Elements

A Theme Builder will automatically include all Element Categories attached to the Theme with all their Elements. All Option Sets and RTE Configs attached to the Theme will be also included.

Blueprints

A Theme Builder will automatically include public Blueprint Categories attached to the THeme with all their public Blueprints.

Templates and TVs

A Theme Builder will include all MODX Templates assigned to the Theme. Any TVs assigned to those MODX Templates will also be included.

Extras

Extras are MODX packages required for your theme to be fully functional. User will need to install all of the listed extras, before he can proceed with installing your Theme. Fred itself will always be a dependency and is included by default.

Assets

Theme-specific assets like CSS/SASS/SCSS, images, JS and other similar files are packed into each theme in the assets/theme/{{your-theme-name}} directory.

License, Changelog and Readme Files

These files show when you are installing the Extra from the MODX Package Manager.

The Fred Manager Extra (aka, 3rd-party Component or 3PC) allows you share your themes with colleagues or to submit it to the MODX Extras repository:

Click on the Themes tab.
Find the Theme you’d like to share/publish.
Right-click on its name and choose the Build theme option.
Fill in the details and choose one of the two export options at the bottom.

A MODX Installer-ready theme will be saved to your core/packages/ directory as {{theme-name}}.transport.zip file that you can distribute. You can also choose to build and download, which will also save a copy to your downloads directory on your local computer.

Last modified: 22 October 2024