Skip to main content
The Oro application back-office is a single-page application (SPA) combining server-rendered content via the Twig templating engine and client-rendered content with Underscore.js. You can customize it with themes, override SCSS styles, Twig and Underscore.js templates, and extend parts of a page with placeholders.

Templates (Twig)

Override Twig templates to change how back-office pages render. Includes guidance on finding templates with Twig Inspector.

Placeholders

Add ordered sets of blocks (templates or actions) to any part of the back-office UI without modifying the original templates.

Stylesheets (SCSS)

Register and build custom SCSS files for back-office themes.

Back-Office Themes

Create application-specific or reusable themes by defining CSS/SCSS files and theme properties.

​
Templates (Twig)

OroPlatform uses the Twig templating engine to render back-office content. To find the template responsible for a specific element, use the Twig Inspector, which activates through the Symfony Profiler and opens the corresponding template in your IDE on click. To override a template, create a file at the same path under templates/bundles/. For example, to override Grid/widget/widget.html.twig from OroDataGridBundle: 
templates/bundles/OroDataGridBundle/Grid/widget/widget.html.twig
For client-rendered content, Oro uses Underscore.js templates. See JS Templates for details.

​
Placeholders

Placeholders allow you to combine an ordered set of blocks (templates or actions) and render them in different parts of Twig templates — without modifying the originals.

​
Render a placeholder

{% placeholder <placeholder_name> %}
Pass additional data to all child items using with: 
{% placeholder <placeholder_name> with {'form' : form} %}

​
Declare placeholders in YAML

Define placeholders and their items in Resource/oro/placeholders.yml: 
placeholders:
    items:
     <item_name>:
        template: <template>           # path to TWIG template
     <another_item_name>:
        action: <action>               # controller action

    placeholders:
      <placeholder_name>:
        items:
          <item_name>:
            order: 100
          <another_item_name>:
            order: 200

​
Override placeholder items

Override placeholder configuration at the application level in config/config.yml: 
oro_ui:
    placeholders:
        <placeholder_name>:
            items:
                <item_name>:
                    remove: true   # remove item from placeholder
        <another_placeholder_name>:
            items:
                <item_name>:
                    order: 200     # change item order

​
Stylesheets (SCSS)

SCSS files for the back-office should be stored in Resources/public/css/ of a bundle and registered in Resources/config/oro/assets.yml. 
# src/Acme/Bundle/DemoBundle/Resources/config/oro/assets.yml
css:
    inputs:
        - 'bundles/acmedemo/css/colors.scss'
        - 'bundles/acmedemo/css/top-menu.scss'
        - 'bundles/acmedemo/css/popups.scss'
        - 'bundles/acmedemo/css/product-view-page.scss'
All inputs are merged and compiled to public/css/oro.css by default.

​
Separate output file

To keep your CSS code in its own compiled file, define a new entry point: 
# src/Acme/Bundle/DemoBundle/Resources/config/oro/assets.yml
acme_styles:
    inputs:
        - 'bundles/acmedemo/css/colors.scss'
        - 'bundles/acmedemo/css/top-menu.scss'
    output: 'css/acme.css'
Then register a placeholder to include it in the page <head>: 
# Resources/config/oro/placeholders.yml
placeholders:
    placeholders:
        head_style:
            items:
                acme_css:
                    order: 150
    items:
        acme_css:
            template: "@AcmeDemo/acme_css.html.twig"

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

​
Import from node_modules

Prepend the import path with ~ to tell Webpack it is not a relative path: 
css:
    inputs:
        - '~prismjs/themes/prism-coy.css'

​
Development tips

Build only the theme you are currently working on to speed up the process: 
php bin/console oro:assets:build admin.oro
Use watch mode to rebuild automatically on file changes: 
php bin/console oro:assets:build --watch

​
Back-Office Themes

A back-office theme is a set of CSS and/or SCSS files that customizes the look of OroPlatform.

​
Theme properties

PropertyRequiredDescription
nameyesA unique theme identifier
labelnoDisplay name in the theme management UI
stylesyesList of CSS/SCSS files that define the theme
iconnoFavicon for the theme
logonoLogo shown in the management UI
screenshotnoScreenshot shown in the management UI
rtl_supportnoEnables RTL support and *.rtl.css file generation

​
Application-specific theme

Define a theme directly in config/config.yml: 
# 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

​
Reusable theme

To create a theme reusable across applications, define it in Resources/public/themes/<theme-name>/settings.yml: 
# src/Acme/Bundle/DemoBundle/Resources/public/themes/acme-theme/settings.yml
styles:
    - bundles/acmedemo/themes/acme-theme/css/main.css
    - bundles/acmedemo/themes/acme-theme/css/ie.css
label: Acme Demo Theme
icon: bundles/acmedemo/themes/acme-theme/images/favicon.ico
logo: bundles/acmedemo/themes/acme-theme/images/logo.png
screenshot: bundles/acmedemo/themes/acme-theme/images/screenshot.png
Activate it in any application: 
# config/config.yml
oro_theme:
    active_theme: acme-theme
Use php bin/console oro:theme:list to list all available themes and see which one is active.

​
Override an existing theme

Theme configuration files are merged during container compilation. To override an existing theme, create a settings.yml in the Resources/public/themes/<theme-name> directory of your bundle with only the values you want to change: 
# src/Acme/Bundle/DemoBundle/Resources/public/oro/
label: Custom Oro Theme
icon: images/custom_favicon.ico
When overriding themes from third-party bundles, ensure your bundle is registered after the bundle whose theme you are overriding.
After any theme changes, clear the cache and dump assets: 
php bin/console cache:clear
php bin/console assets:install --symlink
php bin/console oro:assets:build

Build docs developers (and LLMs) love

Get started for freeTalk to us