Create a new storefront theme

What's in this topic

This topic discusses how to create the files that make up a theme, how to add a logo to a theme, and how to size images.

A new theme you create is not applied for your store automatically. You need to apply it manually in the Admin panel. This procedure is described in the Apply and configure a theme in Admin topic.

Prerequisites

  1. For the sake of compatibility, upgradability, and easy maintenance, do not modify the out of the box Magento themes. To customize the design of your Magento store, create a new custom theme.
  2. Set your Magento application to the developer mode. The application mode influences the way static files are cached by Magento. The recommendations about theme development we provide in this chapter are developer/default-mode specific.

Create a storefront theme: walkthrough

The high-level steps required to add a new theme in the Magento system are the following:

  1. Create a directory for the theme under app/design/frontend/<your_vendor_name>/<your_theme_name>.
  2. Add a declaration file theme.xml and optionally create etc directory and create a file named view.xml to the theme directory.
  3. Add a composer.json file.
  4. Add registration.php.
  5. Create directories for CSS, JavaScript, images, and fonts.
  6. Configure your theme in the Admin panel.

Recommended reading

Create a theme directory

To create the directory for your theme:

  1. Go to <your Magento install dir>/app/design/frontend.

  2. Create a new directory named according to your vendor name: /app/design/frontend/<Vendor>.

  3. Under the vendor directory, create a directory named according to your theme.

app/design/frontend/
├── <Vendor>/
│   │   ├──...<theme>/
│   │   │   ├── ...
│   │   │   ├── ...

The folder name conventionally matches naming used in the theme’s code: any alphanumeric set of characters, as the vendor sees fit, is acceptable. This convention is merely a recommendation, so nothing prevents naming this directory in another way.

Declare your theme

After you create a directory for your theme, you must create theme.xml containing at least the theme name and the parent theme name (if the theme inherits from one). Optionally you can specify where the theme preview image is stored.

  1. Add or copy from an existing theme.xml to your theme directory app/design/frontend/<Vendor>/<theme>

  2. Configure it using the following example:

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
     <title>New theme</title> <!-- your theme's name -->
     <parent>Magento/blank</parent> <!-- the parent theme, in case your theme inherits from an existing theme -->
     <media>
         <preview_image>media/preview.jpg</preview_image> <!-- the path to your theme's preview image -->
     </media>
</theme>

If you do not have a preview image for your theme, remove the <media> node:

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
     <title>New theme</title> <!-- your theme's name -->
     <parent>Magento/blank</parent> <!-- the parent theme, in case your theme inherits from an existing theme -->
</theme>

If you change the theme title or parent theme information in theme.xml after a theme was already registered, you need to open or reload any Magento Admin page for your changes to be saved in the database.

Make your theme a Composer package

Magento default themes are distributed as Composer packages.

To distribute your theme as a package, add a composer.json file to the theme directory and register the package on a packaging server. A default public packaging server is https://packagist.org/.

composer.json provides theme dependency information. Refer to a current theme.xml file for the correct dependancies and their versions. If your parent theme is something other than Magento/blank, you may need additional modules in the "require" section.

Example of a theme composer.json:

{
    "name": "magento/theme-frontend-luma",
    "description": "N/A",
    "require": {
        "php": "~5.5.0|~5.6.0|~7.0.0",
        "magento/theme-frontend-blank": "100.0.*",
        "magento/framework": "100.0.*"
    },
    "type": "magento2-theme",
    "version": "100.0.1",
    "license": [
        "OSL-3.0",
        "AFL-3.0"
    ],
    "autoload": {
        "files": [
            "registration.php"
        ]
    }
}

You can find details about the Composer integration in the Magento system in Composer integration.

Add registration.php

To register your theme in the system, in your theme directory add a registration.php file with the following content:

<?php
/**
 * Copyright © 2015 Magento. All rights reserved.
 * See COPYING.txt for license details.
 */
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::THEME,
    'frontend/<Vendor>/<theme>',
    __DIR__
);

Where <Vendor> is your vendor name, <theme> is the theme code.

For illustration, see the registration.php file of the Magento Luma theme.

Configure images

Product image sizes and other properties used on the storefront are configured in a view.xml configuration file. It is required for a theme, but is optional if exists in the parent theme.

If the product image sizes of your theme differ from those of the parent theme, or if your theme does not inherit from any theme, add view.xml using the following steps:

  1. Log in to your Magento server as a user with permissions to create directories and files in the Magento installation directory. (Typically, this is the the Magento file system owner.)

  2. Create the etc directory in your theme folder

  3. Copy view.xml from the etc directory of an existing theme (for example, from the Blank theme) to your theme’s etc directory.

  4. Configure all storefront product image sizes in view.xml. For example, you can make the category grid view product images square by specifying a size of 250 x 250 pixels, here is how the corresponding configuration would look like:

...
    <image id="category_page_grid" type="small_image">
        <width>250</width>
        <height>250</height>
    </image>
...

For details about images configuration in view.xml, see the Configure images properties for a theme topic.

Create directories for static files

Your theme will likely contain several types of static files: styles, fonts, JavaScript and images. Each type should be stored in a separate sub-directory of web in your theme folder:

app/design/<area>/<Vendor>/<theme>/
├── web/
│ ├── css/
│ │ ├── source/ 
│ ├── fonts/
│ ├── images/
│ ├── js/

In the .../<theme>/web/images you store the general theme related static files. For example, a theme logo is stored in ...<theme>/web/images. It is likely that your theme will also contain module-specific files, which are stored in the corresponding sub-directories, like .../<theme>/<Namespace_Module>/web/css and similar. Managing the module-specific theme files is discussed in the following sections of this Guide.

During theme development, when you change any files stored here, you need to clear pub/static and var/view_preprocessed directories, and then reload the pages. Otherwise the old versions of files are displayed on the storefront.

Your theme directory structure now

At this point your theme file structure looks as follows:

app/design/frontend/<Vendor>/
├── <theme>/
│   ├── etc/
│   │   ├── view.xml
│   ├── web/
│   │   ├── images
│   │   │   ├── logo.svg
│   ├── registration.php
│   ├── theme.xml
│   ├── composer.json

In the Magento application, the default format and name of a logo image is logo.svg. When you put a logo.svg image in the conventional location, which is <theme_dir>/web/images directory, it is automatically recognized as theme logo. It is displayed in your store page header once the theme is applied.

In your custom theme, you can use a logo file with a different name and format, but you might need to declare it.

The necessity of declaration depends on whether your theme has a parent theme and its logo image. The following cases are possible:

  • Your theme does not have a parent theme:
    • if your logo image name and format is default, logo.svg, there is no need to declare it;
    • if your logo image name or format is not default, you need to declare it in layout.
  • Your theme has a parent theme:
    • if your theme logo image has the same name and format as the parent's theme logo, there is no need to declare it;
    • if your logo image has different name or format, declare it in layout.

Declaring theme logo

To declare a theme logo, add an extending <theme_dir>/Magento_Theme/layout/default.xml layout.

For example, if your logo file is my_logo.png sized 300x300px, you need to declare it as follows:

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceBlock name="logo">
            <arguments>
                <argument name="logo_file" xsi:type="string">images/my_logo.png</argument>
                <argument name="logo_img_width" xsi:type="number">300</argument>
                <argument name="logo_img_height" xsi:type="number">300</argument>
            </arguments>
        </referenceBlock>
    </body>
</page>

Declaring the logo size is optional.

To learn more about theme layouts, refer to the Layout section of this guide.

Some trouble

Some time, clear cache isn’t enough to saw change, you can try magento setup:static-content:deploy en_US (adapt language with your own need) to generate assetic.

What’s next

Theme registration

Once you open the Magento Admin (or reload any Magento Admin page) having added the theme files to the files system, your theme gets registered and added to the database.

Applying a theme

For information on how to apply the theme for the storefront, see the Apply and configure a theme in Admin topic.

See also

Edit this page on GitHub
Give us feedback

相关主题：

Magento电商 github source