Important
You are browsing the documentation for version 4.2 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.
See our Release Process documentation for more information on the currently supported and upcoming releases.
Quick Start¶
This tutorial describes how to create OroCommerce storefront theme with basic styles and layout customizations. To create back-office themes, follow the Back-Office Theme Customization
Prerequisites¶
OroCommerce is a Symfony-based application where all codes are organized in bundles. To create a theme, you need to create a bundle first. We recommend to create a new empty bundle for the new theme, but you can also create a theme in one of the existing bundles.
Create a Theme¶
First, create a theme folder in Resources/views/layouts/
. For example DemoBundle/Resources/views/layouts/first_theme/
, where first_theme
is the theme name.
The theme definition should be placed in theme.yml
in a theme folder, for example:
#DemoBundle/Resources/views/layouts/first_theme/theme.yml
label: First Theme
parent: default
groups: [ commerce ]
See the theme definition topic for more details.
Activate the Theme¶
Now, you can activate the storefront theme from the back-office.
To set a default storefront theme on the code level, add the following
configuration to the config/config.yml
file in your application:
#config/config.yml
oro_layout:
active_theme: first_theme
Add Stylesheets with SCSS¶
Create SCSS files with custom styles in
Resources/public/
folder in a bundle.Run
bin/console assets:install --symlink
to symlink SCSS files from bundles topublic/bundles/
folder in your application.Create the
assets.yml
file in a themeconfig/
folder and register all the new SCSS files in it.#DemoBundle/Resources/views/layouts/first_theme/config/assets.yml styles: inputs: - bundles/demo/scss/logo.scss - bundles/demo/scss/settings/_colors.scss output: css/styles.css
Run the
bin/console oro:assets:build first_theme --watch
command to process and combine SCSS files infirst_theme
.You can use SCSS source maps to find styles definition in a Browser and Oro Frontend Stylebook to check how updated styles affect the UI elements.
Change Existing Pages Structure¶
The structure of all pages in OroCommerce storefront are defined by the Layout.
To see the current page structure, open website in a dev
environment, and in a Symfony Profiler, click the Layout icon:
To change the page structure, we need to modify the layout.
Layout is a tree representation of the page where each tree item is a layout block. To define and modify the layout tree, use actions organized into layout update Yaml files:
@add
@addTree
@remove
@move
etc.
Let’s add a slogan block just after the logo for all the existing pages:
#DemoBundle/Resources/views/layouts/first_theme/slogan.yml
layout:
actions:
- '@add':
parentId: middle_bar_logo
id: slogan
blockType: text
options:
text: Website Slogan!
And change the structure of a product display page. Remove images, move block with title and SKU to another place and add a css class to the SKU attribute. To apply layout updates to a single page, we need to place them in a folder with the route name inside a theme. For a product display page, the route name is oro_product_frontend_product_view:
#DemoBundle/Resources/views/layouts/first_theme/oro_product_frontend_product_view/product.yml
layout:
actions:
- '@move':
id: product_view_primary_container
parentId: page_title_container
- '@remove':
id: product_view_primary_wrapper
- '@setOption':
id: product_view_attribute_group_general_attribute_text_sku
optionName: attr.class
optionValue: page-title
Change the HTML¶
Each layout block is rendered with a Twig block. Twig blocks are organized into block theme twig files.
For example, product_view_attribute_group_general_attribute_text_sku
block from the previous section is rendered as follows:
{#ProductBundle/Resources/views/layouts/blank/oro_product_frontend_product_view/layout.html.twig #}
{% block _product_view_attribute_group_general_attribute_text_sku_widget %}
{% set attr = layout_attr_defaults(attr, {
'~class': ' sku'
}) %}
<p {{ block('block_attributes') }}>
{{ 'oro.product.frontend.index.item'|trans }} <span class="sku__code" itemprop="sku">{{ entity.sku|oro_html_strip_tags }}</span>
</p>
{% endblock %}
To find out which Twig block is used for rendering a certain element on a page, you can use Twig Inspector. Activate it from a Symfony Profiler, click the Twig Inspector icon and then click the element you want to inspect on the page. The template will be automatically opened in an IDE.
To override the template, we need to create a block theme twig file in the same location in our bundle and apply it with the @setBlockTheme
layout action. Let’s change the label of an SKU attribute to the default one.
{#DemoBundle/Resources/views/layouts/blank/oro_product_frontend_product_view/sku.html.twig #}
{% block _product_view_attribute_group_general_attribute_text_sku_widget %}
{% set attr = layout_attr_defaults(attr, {
'~class': ' sku'
}) %}
<p {{ block('block_attributes') }}>
- {{ 'oro.product.frontend.index.item'|trans }} <span class="sku__code" itemprop="sku">{{ entity.sku|oro_html_strip_tags }}</span>
+ {{ label|trans }}: <span class="sku__code" itemprop="sku">{{ entity.sku|oro_html_strip_tags }}</span>
</p>
{% endblock %}
#DemoBundle/Resources/views/layouts/first_theme/oro_product_frontend_product_view/product.yml
layout:
actions:
- '@setBlockTheme':
themes: sku.html.twig
# ...