close

Filter

loading table of contents...

Frontend Developer Manual / Version 2310

Table Of Contents

4.2 Theme Structure

A theme is a package which consists of a theme config, a webpack configuration and various web resources located in its src folder. Example 4.3, “ Filesystem structure of a theme ” shows the filesystem structure of a theme:

 themes/
└── [$example-theme]/      // name of theme,
    │                         for example "foo" and suffix "-theme"
    ├── node_modules/      // installed node dependencies managed
    │                         by the package manager
    ├── src/               // all source files, add subfolders for all types
    │   │                     like sass, js, fonts or images
    │   ├── fonts/
    │   │   └── example.woff
    │   ├── img/
    │   │   ├── example.png
    │   │   └── logo.svg
    │   ├── js/
    │   │   ├── index.js
    │   │   ├── [$example-theme].js
    │   │   └── preview.js
    │   ├── l10n/
    │   │   ├── [$example-theme]_de.properties
    │   │   └── [$example-theme]_en.properties
    │   ├── sass/
    │   │   ├── partials/
    │   │   ├── variables/
    │   │   ├── [$example-theme].scss
    │   │   ├── _partials.scss
    │   │   ├── _variables.scss
    │   │   └── preview.scss
    │   ├── settings/
    │   │   ├── [$example-theme].settings.json
    │   │   └── Preview.settings.json
    │   └── templates/
    ├── .prettierignore    // path configuration for prettier
    ├── .prettierrc        // config for prettier
    ├── package.json       // config for node module dependencies
    ├── theme.config.json  // theme definition config, mandatory
    │                         for importing themes!
    └── webpack.config.js  // config for webpack

Example 4.3.  Filesystem structure of a theme


The theme config is a JSON file named theme.config.json located in the root directory of the theme package. It contains general information like the name and a description of the theme but also path references to all its web resources (JavaScript, CSS files, Templates, ...). Example 4.4, “ Theme config example ” shows the typical structure of a theme configuration. You can find a reference here: Section 6.2, “Theme Config”.

{
  "name": "example-theme",
  "description": "The is an minimal example theme.",
  "thumbnail": "src/img/theme-example.png",

  "scripts": [
    {
      "type": "webpack",
      "src": "src/sass/example.js"
    },
    {
      "type": "copy",
      "src": "src/vendor/example.js"
    },
    {
      "type": "externalLink",
      "src": "https://cdn.example.org/external.js"
    }
  ],
  "styles": [
    {
      "type": "webpack",
      "src": "src/sass/example.scss"
    },
    {
      "type": "copy",
      "src": "src/css/example.css",
      "target": "css/example.css"
    },
    {
      "type": "externalLink",
      "src": "https://cdn.example.org/external.css"
    }
  ],
  "l10n": {
    "bundleNames": [
      "Example"
    ]
  }
}

Example 4.4.  Theme config example


Every theme requires a webpack configuration in order to be build via pnpm build. The theme creator (see Section 5.1, “Creating a New Theme”) will create a default configuration in the webpack.config.js which makes use of @coremedia/theme-utils to apply our default configuration.

Before giving more detailed information about the structure of the web resources it is important to note that Webpack is used to bundle a theme for deployment. It performs tasks like transpilation (ES6 -> ES2015), compilation (SCSS -> CSS), bundling (ES6 modules -> CommonJS modules) and minification before the theme is uploaded to the CoreMedia repository. Because of this the source file structure of a theme is not kept and one needs to distinct between the theme's Source File Structure and its Bundled File Structure. More information about the tasks can be found in the corresponding chapters for SASS and JavaScript. For further details about the deployment check Section 5.4.12, “Client Code Delivery” in Blueprint Developer Manual .

All Source Files, except for the templates and the theme's main entry points, can be arranged arbitrarily in directories. However, in CoreMedia themes these resources are arranged by their particular types. CoreMedia uses the following typical style for web-safe file names:

  • File names should all be lower case

  • Nouns should be used in singular

  • Words should be separated by dashes

Templates are located in the src/templates directory of the theme module. Inside this directory templates are structured in packages, corresponding to the content beans. The order of the elements also specifies the order the JAR files are processed by the CAE. See Section 5.4.10, “Dynamic Templating” in Blueprint Developer Manual for details.

The term is based on https://webpack.js.org/concepts/entry-points/ and describes the entry points of the different language layers. CoreMedia themes have two main entry points:

  • src/js/index.js is the main entry point for JavaScript.

  • src/sass/$theme-name.scss is the main entry point for SCSS.

Starting from an entry point you can import all other required files.

All templates coming from bricks and themes are bundled into a templates/$theme-name-templates.jar archive, while templates from the theme overwrite those from bricks.

The JavaScript will be bundled into js/$theme-name.js while the SCSS will be bundled into a CSS file css/$theme-name.css.

Web resources will automatically be bundled if they are referenced in the JavaScript or in the SCSS regardless of their location. For convenience all static web resources of a theme under src/css, src/fonts, src/img, src/images and src/vendor will be copied to the corresponding location in the theme's target folder. However, CoreMedia strongly encourages to always reference the static web resources in one of the entry points as it guarantees that the web resource is bundled properly and the link is properly transformed to the Bundled File Structure which may differ from the Source File Structure.

Bundled web resources will be bundled by their type:

  • svg, png and gif files are placed under img keeping their original filename.

  • woff, woff2, ttf and eot files are placed under fonts keeping their original filename.

  • swf files are placed under swf keeping their original filename.

To add more file types to the layout you need to specify an additional file-loader.

Themes imported into the Content Server are stored in a folder named Themes/<ThemeName> by default. The content is stored in the following content types:

  • CSS files in content of type CSS

  • JavaScript files in content of type JavaScript

  • FreeMarker Templates as JAR archives in blob properties in content of type Template Set

  • Resource bundles in content of type Resource Bundle

  • All other supported web resources in content of type Technical Image

Select the theme as the associated theme for the page content of your site (see Figure 5.2, “Associated Theme”).

Search Results

Table Of Contents
warning

Your Internet Explorer is no longer supported.

Please use Mozilla Firefox, Google Chrome, or Microsoft Edge.