Skip over navigation
Documentation

Customizing the Application Layout

You can customize the OroPlatform layout in different ways:

Custom SCSS Files

Creating and Embedding Custom Stylesheets

Using your own SCSS file is pretty simple. Just save it in the, for example, Resources/public/css/ directory of your bundle and add it to the assets.yml configuration file:

1
2
3
4
# src/Acme/NewBundle/Resources/config/oro/assets.yml
css:
    inputs:
        - 'bundles/acmenew/css/styles.scss'

Now, you need to clear the cache and install the new stylesheets by running the assets:install command:

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

In this example, all four SCSS files from your bundle as well as all the other files from the Oro Platform and from third-party bundles will be merged and dumped in the public/css/oro.css file.

If you want to keep your CSS code separately, you can dump all your SCSS files to another compiled file. To do that, you have to use different assets group in your assets.yml

1
2
3
4
5
6
# src/Acme/NewBundle/Resources/config/oro/assets.yml
acme_styles:
    inputs:
      - 'bundles/acmenew/css/styles.scss'
      - 'bundles/acmenew/css/another-styles.scss'
    output: 'css/acme.css'

Use the corresponding placeholder to put compiled CSS file to the head of your document

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# src/Acme/Bundle/NewBundle/Resources/config/oro/placeholders.yml
placeholders:
    placeholders:
        head_style:
            items:
                acme_css:
                    order: 150

    items:
        acme_css:
            template: AcmeNewBundle::acme_css.html.twig

and finally, add the template for rendering style tag

1
2
# src/Acme/Bundle/NewBundle/Resources/views/acme_css.html.twig
<link rel="stylesheet" media="all" href="{{ asset('css/acme.css') }}" />

Warning

You can also put your code in CSS files which will be compiled together with SCSS files. But keep in mind that the CSS loader is deprecated by node-sass npm module, and it will stop working after the module update.

Development tips

The application uses a Webpack tool for assets building. It supports a quite useful feature of mapping compiled CSS to SCSS sources. So in browser’s web inspector (e.g., Google Chrome), you can see which SCSS code styling an element directly.

The assets building takes some time. So better build only the theme that is currently required. To speed up the process, simply add a theme name after the build command.

$ php bin/console oro:assets:build admin.oro

Also, you can use the watch mode to rebuild assets automatically after some SCSS file is changed. Just add the --watch (or -w) option to the build command.

$ php bin/console oro:assets:build --watch

Refer to Asset Commands for more information.

Application Themes

A theme is a set of CSS and/or SCSS files that customize the look and feel of OroPlatform. The theme has the following properties:

Property Required Description
name yes A unique name
label no A string that is displayed in the theme management UI.
styles yes The list of CSS and SCSS files that define the theme.
icon no The theme’s favicon.
logo no A logo that is shown in the theme management UI.
screenshot no A screenshot of the theme to be shown in the management UI.

You can create themes in two different ways:

Alternatively, you can customize an existing theme instead of creating a new one from scratch.

Application-specific Themes

Customizing the layout of your Platform application is as easy as defining your custom theme in your application’s configuration using the oro_theme option:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# config/config.yml
oro_theme:
    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
    active_theme: mytheme

First, you create a theme named mytheme with the My Theme label that uses two CSS files main.css and ie.css. Secondly, select the theme to be used by setting its name as the value of the active_theme option.

Reusable Themes

In addition to customizing your own application, you can also provide a theme that can be reused in different applications. To achieve this, simply specify the theme’s options in the settings.yml file that is located in the Resources/public/themes/<theme-name> directory of your bundle:

1
2
3
4
5
6
7
8
# src/Acme/DemoBundle/Resources/public/themes/acme-theme/settings.yml
styles:
    - bundles/acmebundle/themes/acme-theme/css/main.css
    - bundles/acmebundle/themes/acme-theme/css/ie.css
label: Acme Demo Theme
icon: bundles/acmebundle/themes/acme-theme/images/favicon.ico
logo: bundles/acmebundle/themes/acme-theme/images/logo.png
screenshot: bundles/acmebundle/themes/acme-theme/images/screenshot.png

To use the theme in any application, enable it in the application configuration:

1
2
3
# config/config.yml
oro_theme:
    active_theme: acme-theme

Tip

You can use the oro:theme:list command to get a list of all available themes. Its output looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
List of available themes:
acme-theme (active)
 - label: Acme Demo Theme
 - logo: bundles/acmebundle/themes/acme-theme/images/logo.png
 - icon: bundles/acmebundle/themes/acme-theme/images/favicon.ico
 - screenshot: bundles/acmebundle/themes/acme-theme/images/screenshot.png
 - styles:
     - bundles/acmebundle/themes/acme-theme/css/main.css
     - bundles/acmebundle/themes/acme-theme/css/ie.css
demo:
 - label: Demo Theme
 - logo: bundles/oroui/themes/demo/images/favicon.ico
 - styles:
     - bundles/oroui/themes/demo/css/scss/main.scss
     - bundles/oroui/themes/demo/css/style.css
mytheme
 - label: My Theme
 - logo: mytheme/images/logo.png
 - icon: mytheme/images/favicon.ico
 - screenshot: mytheme/images/screenshot.png
 - styles:
     - mytheme/css/main.css
     - mytheme/css/ie.css
oro
 - label: Oro Theme
 - icon: bundles/oroui/themes/oro/images/favicon.ico
 - styles: bundles/oroui/themes/oro/css/style.css

Finally, clear the cache and dump all assets:

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

Overriding a Theme

The configuration files of all available themes are merged when the service container is being compiled. Since the merge process does override values if they are defined in more than one file, you can make use of it when you need to customize an existing theme.

For example, imagine that you want to use the Oro theme from the OroUIBundle, but you want to use a custom label and favicon for it. The definition of the Oro theme as defined in the bundle looks like this:

1
2
3
4
label: Oro Theme
icon: bundles/oroui/themes/oro/images/favicon.ico
styles:
    - bundles/oroui/themes/oro/css/style.css

So, place the settings.yml file in the Resources/public/themes/oro directory of your bundle and define the values you want to change:

1
2
3
# src/Acme/DemoBundle/Resources/public/oro/
label: Custom Oro Theme
icon: images/custom_favicon.ico

Caution

If you override themes from third-party bundles, you have to make sure that your bundle is registered after the bundle it is overriding themes from:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
// src/AppKernel.php
// ...

class AppKernel extends OroKernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new ThirdParty\Bundle\ThirdPartyBundle(),
            // ...
            new Acme\DemoBundle\AcmeDemoBundle(),
            // ...
        );

        // ...
    }

    // ...
}
Browse maintained versions:3.12.62.32.01.12
Back to top

You will be redirected to [title]. Would you like to continue?

Yes No