Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
140 lines (102 sloc) 4.02 KB

OroThemeBundle

OroThemeBundle provides the basic theme support with the ability to change the original UI applying the extra CSS/SCSS files that are grouped into themes.

Basic statements

  • Bundle can provide CSS and templates that are required for it's UI;
  • UI of bundles (css and templates markup) should be "themable", it means that CSS and UI components of bundle should be affectable by theme to change look and feel of application (at least colors and icons);
  • A theme is a set of CSS/SCSS files that will be included at the end of all CSS files to cascade styles and change look and feel;

Theme Properties

Each theme can have next properties:

  • name required Unique name of the theme.

  • label optional This will be displayed in theme management UI.

  • styles required The list of CSS and SCSS files that represent a theme.

  • icon optional Standard "favicon.ico" file for this theme.

  • logo optional Logo that will be displayed in the UI.

  • screenshot optional This be displayed in theme management UI.

Adding a theme using config.yml

To add a theme you can use config.yml file.

# add to config.yml next string to use mytheme theme
oro_theme:
    active_theme: mytheme
    themes:
        mytheme:
            styles:
                - mytheme/css/main.css
                - mytheme/css/ie.css
            label: My Theme
            icon: mytheme/images/favicon.ico
            logo: mytheme/images/logo.png
            screenshot: /mytheme/images/screenshot.png

Make sure that your root public sites directory (generally a "web" directory in symfony) contains mytheme directory with all used files.

Adding a theme using a bundle

Theme could be added in any bundle, place a file in Resources/public/themes/<theme_name>/settings.yml path inside of bundle. This file contains same configuration like in config.yml:

styles:
    - bundles/mybundle/themes/mytheme/css/main.css
    - bundles/mybundle/themes/mytheme/css/ie.css
label: My Theme
icon: bundles/mybundle/themes/mytheme/images/favicon.ico
logo: bundles/mybundle/themes/mytheme/images/logo.png
screenshot: bundles/mybundle/themes/mytheme/images/screenshot.png

Overriding a theme

All themes settings are collected and merged at compile time of DI container. Bundle could override others bundle theme by placing a file with theme Resources/public/themes/<theme_name>/settings.yml in settings.yml path.

Loading styles of theme

When application has active theme it's styles append to the end of the list of all CSS assets of bundles. Theme's styles will override existing bundles styles to change look and feel of application.

To set active theme add next settings to config.yml

oro_theme:
    active_theme: <theme_name>

After this change was made next commends should be executed:

bin/console cache:clear
bin/console assets:install --symlink
bin/console oro:assets:build

Debugging theme styles

Each theme is appended to the list of CSS assets in group "theme". So, if you want to debug theme's styles, you should use next configuration in config.yml:

oro_assetic:
    css_debug: [theme]
    # css_debug_all: true # if you want to debug all CSS assets

When you are making changes to theme's CSS don't forget to run next commands:

bin/console cache:clear # if you have changed some theme's setting, including adding/removing CSS/SCSS styles files.
bin/console assets:install # if you have changed themes files, you can use --symlink parameter, in this case you should install it only once
bin/console oro:assets:build

Getting list of all available themes

There is a command oro:theme:list for this purpose. Here is an example output of this command:

List of available themes:
oro (active)
 - label: Oro Theme
 - icon: bundles/oroui/themes/oro/favicon.ico
 - styles: bundles/oroui/themes/oro/style.css
demo (active)
 - label: Demo Theme
 - logo: bundles/oroui/themes/demo/images/logo.png
 - icon: bundles/oroui/themes/demo/images/favicon.ico
 - styles: bundles/oroui/themes/demo/css/main.scss
You can’t perform that action at this time.