Magento 2 Frontend Certification

Theme development workflow

1. Enable developer mode: bin/magento deploy:mode:set developer

2. Create basic theme files within the /app/design/frontend/<Your_Vendor>/<your_theme> directory:

   1. theme.xml

   2. registration.php

   3. (optionally) composer.json

3. Apply the theme

   1. In the Admin Panel, go to CONTENT > Design > Configuration

   2. Find the record corresponding to your store view and click Edit.

   3. In the Applied Theme drop-down, select your newly created theme.

   4. Click Save Configuration.

4. Choose LESS compilation mode

   1. Grunt (recommended)

   2. client-side compilation

   3. server-side compilation (default)

   4. custom preprocessor

Page caching, when to clean cache and/or static files

• Caching is one of the most effective ways to improve website performance

  • The Adobe Commerce and Magento Open Source page cache library contains a simple PHP reverse proxy that enables full page caching out of the box. A reverse proxy acts as an intermediary between visitors and your application and can reduce the load on your server.

• Cacheable and uncacheable are terms we use to indicate whether or not a page should be cached at all. (By default, all pages are cacheable except the checkout pages.) If ANY block in a layout is designated as uncacheable, the entire page is uncacheable.

  • To create an uncacheable page, mark any block on that page as uncacheable in the layout using cacheable="false" attribute. BUT doing thhas an adverse affect on performance.

• Certain changes in styles require cleaning previously pre-processed and published static view files. Do this after any changes in server-side compilation mode.

• Changes in layout and templates requires cleaning cache.

• Clean Cache:

  • To clean cache, run: bin/magento cache:clean <type> <type>

  • To view the status of the cache, run: bin/magento cache:status

• Clear Static Files

  • Run grunt clean <theme> or manually clear the following directories:

    • var/view_preprocessed directory: rm -r var/view_preprocessed/*

    • manually clear the pub/static directory except pub/static/.htaccess: rm -r pub/static/*/*

• Public and private content

  • Public content is stored server side in your reverse proxy cache storage (e.g., file system, database, Redis, or Varnish) and is available to multiple customers. Examples of public content include header, footer, and category listing.

  • Private content is stored client side (e.g., browser) and is specific to an individual customer. Examples of private content include wishlist, shopping cart, customer name, and address. You should limit stored private content to a small portion of the page's total content.

• The following cache types mostly have impact on frontend development process:

  Cache type "friendly" name	Cache type code name	Description
  Layout	layout	Compiled page layouts (that is, the layout components from all components). Clean or flush this cache type after modifying layout files.
  Block HTML output	block_html	HTML page fragments per block. Clean or flush this cache type after modifying the view layer.
  Page cache	full_page	Generated HTML pages. If necessary, the application cleans up this cache automatically, but third-party developers can put any data in any segment of the cache. Clean or flush this cache type after modifying code level that affects HTML output. It's recommended to keep this cache enabled because caching HTML improves performance significantly.
  Translations	translate	Merged translations from all modules.

Install a third-party storefront theme

• Prerequisite: set your application to the developer or default mode.

• If a theme is just a set of files, for example an archive, add the theme manually.

  • Make sure that the directory structure you are copying is <VendorName>/<theme>. And all the theme files are in the <theme> directory.

  • Copy this directory to the app/design/frontend directory.

• If a theme is a Composer package, install it using Composer.

  • create a development git branch

  • Using the Composer name and version, add the extension to the require section of the composer.json file: composer require <extension-name>:<version> --no-update

  • update the projects directory: composer update

  • Add, commit, and push code changes

    • When installing an extension, you must include the composer.lock file when you push code changes to the remote environment. The composer install command reads the composer.lock file to enable the defined dependencies in the remote environment.

  • verify module is installed: bin/magento module:status <extension-name>

• To make sure the theme is registered, in the Admin navigate to Content > Design > Themes. If a theme is registered, it is displayed in the list of available themes.

• Composer-based themes are loaded from external sources and cannot be modified directly, whereas local themes are part of the project source code and therefore can be edited directly.

• Themes loaded through Composer are located in the vendor/ directory and can be stored anywhere in root.

• When the application starts up, Composer executes each file included in the autoload.files section. registration.php then registers itself as a theme.

Uninstall a storefront theme

• Prerequisites:

  • Set your application to the developer or default mode.

  • Make sure that the theme is not applied on the storefront. To do this, in the Admin panel navigate to Content > Design > Configuration and make sure that your custom theme is not applied for any store view.

  • Make sure that the theme is not defined as a parent for any registered theme. To do this, in the Admin panel, navigate to Content > Design > Themes. Make sure that your theme is not mentioned in the Parent Theme column. If it is mentioned, you need to uninstall the child theme first.

• Uninstall a manually added theme

  • Navigate to the vendor directory where the theme was installed. This directory should be: <installation dir>/app/design/frontend/<VendorName>.

  • Remove the theme directory.

  • Remove the theme record from database. If you are using MySQL, run the following command to do this: mysql -u <user> -p -e "delete from <dbname>.theme where theme_path ='<Vendor>/<theme>' AND area ='frontend' limit 1"

• Uninstall a theme package

  • Composer-based installations

    • bin/magento theme:uninstall

  • Git-based installations

    • remove it from the list of dependencies in composer.json file and run composer update

    • uninstall it using CLI command for composer-based installation

Create an Admin theme

Steps to create a custom theme for the Magento Admin panel:

1. Prerequisites: Ensure your application is set to developer mode, affecting static file caching.

2. Create a Theme Directory: In the app/design/adminhtml directory, create a new folder for your theme.

3. Add theme.xml: Include the theme.xml file, specifying the theme's name and its parent theme (recommended: Magento/backend).

   1. 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 Admin page for your changes to be saved in the database.

4. Add registration.php: Create the registration.php file to register the theme in Magento.

5. Optional Composer.json: Add a composer.json file for further customization.

6. Change Logo: Optionally, customize the theme's logo.

1. Create a new XML file in the theme named app/design/adminhtml/<Vendor>/<theme>/Magento_Backend/layout/admin_login.xml

2. Add the following sample code to the new file.

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="admin-login" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceBlock name="logo">
            <arguments>
                <argument name="logo_image_src" xsi:type="string">images/custom-logo.svg</argument>
                <argument name="logo_width" xsi:type="number">150</argument> <!-- Add custom logo width -->
                <argument name="logo_height" xsi:type="number">80</argument> <!-- Add custom logo height -->
            </arguments>
        </referenceBlock>
    </body>
 </page>

1. Add your custom logo to the app/design/adminhtml/<Vendor>/<theme>/web/images/ directory.

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

Apply an Admin theme

Steps for applying a custom theme to the Magento Admin interface:

1. Prerequisites:

   1. Set your application to developer mode

   2. create a custom Admin theme

2. add a custom module that loads after the Magento_Theme module

   1. in <your_custom_module_dir>/etc/module.xml

      <module name="%YourVendor_YourModule%" setup_version="2.0.1"> <!-- Example: "Magento_Backend" -->
         <sequence>
            <module name="Magento_Theme"/>
            <module name="Magento_Enterprise"/> <!-- For Enterprise versions only -->
         </sequence>
      </module>
      

3. Applying the Theme: In your module's di.xml file, specify the custom Admin theme by adding it to the theme array.

   1. In <your_module_dir>/etc/di.xml add the following (replace the placeholders with the vendor name and theme code of your Admin theme):

      <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
      
          <!-- Admin theme. Start -->
          <type name="Magento\Theme\Model\View\Design">
              <arguments>
                   <argument name="themes" xsi:type="array">
                       <item name="adminhtml" xsi:type="string">%Your_vendor_dir%/%your_theme_code%</item> <!-- Example: "Magento/backend" -->
                   </argument>
               </arguments>
          </type>
          <!-- Admin theme. End -->
      </config>
      

4. Run Commands: Execute the bin/magento setup:upgrade command to update the components.

   1. If prompted, also run bin/magento setup:di:compile. Then run bin/magento cache:clean to clear the cache.

5. View Theme: Finally, open the Admin panel to see the applied theme.

Create a storefront theme

How to build a custom storefront theme for Magento:

1. Prerequisites: It's recommended not to modify default themes for compatibility and ease of updates. Set your application to developer mode for theme development.

2. Steps:

   • Create a theme directory under app/design/frontend/<Vendor>/<Theme>.

   • Add a theme.xml file for theme declaration, specifying the name and optional parent 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 Admin page for your changes to be saved in the database.

   • Optionally, create a etc/view.xml file and add a composer.json file.

     • a composer.json file allows you to distribute your theme as a package

     • 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.

   • Add a registration.php to register the theme.

   • Set up directories for CSS, JS, images, and fonts.

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

     • 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 the <theme_dir>/web/images directory, it is automatically recognized as the 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 will need to declare it.

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

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

3. Configuration: After creating the theme, configure it in the Admin panel to apply it.

Troubleshooting: When your theme changes are not visible even after clearing the cache, try redeploying your static files using the bin/magento setup:static-content:deploy command, or add the -f argument to force deploy static content in any deployment mode in case you are not in production mode.

Apply and configure a storefront theme

Steps involved in applying a custom storefront theme:

Prerequisites: set application to developer mode

1. Apply Theme in Admin Panel:

   • Go to the Magento Admin panel under Content > Design > Configuration.

   • Select the store view you want to apply the theme to and choose your custom theme from the Applied Theme dropdown menu.

   • save configuration, clear cache, and reload storefront

2. Configuration: Add a design exception

   1. Design exceptions enable you to specify an alternative theme for particular user-agents, instead of creating a separate store views for them. To add a design exception:

      1. In Admin, go to Content > Design > Configuration

      2. In the configuration record corresponding to your store view, click Edit.

      3. On the Design Rule tab, click Add New User Agent Rule.

      4. In the Search String box specify the user-agent using either normal strings or regular expressions (PCRE). In the Theme Name drop-down list select the theme to be used for matching agent.

      5. Clear cache

3. Configuration: Add a theme-independent logo

   1. You might want to set a permanent store logo that displays on the storefront no matter what theme is applied. To add a permanent theme-independent logo:

      1. In Admin, go to Content > Design > Configuration

      2. In the configuration record corresponding to your store view, click Edit.

      3. Expand the Header tab.

      4. In the Logo Image field browse to the logo file saved in your file system.

      5. Upload the file. Allowed file types include .png, .gif, .jpg, and .jpeg. To add an .svg logo, see Declaring theme logo.

      6. Optionally, specify the desired width, height, and the alternative text for the logo in the corresponding fields.

      7. Click Save Configuration or Save and Continue.

      8. If caching is enabled, clear the cache.

      9. To see your changes applied, reload the storefront pages.

4. Troubleshooting: If the changes you configure in the Admin are not applied after you clear the cache and reload the page, delete all files in the pub/static/frontend and var/view_preprocessed directories, then reload the pages. You can delete the files manually or run the grunt clean:<theme_name> command in CLI

Locate templates, layouts, and styles

Templates:

• Enable template hints in admin

  • Click Stores > Settings > Configuration > ADVANCED > Developer.

  • In the Scope: dropdown in the upper-left corner select the view for which you want the template hints.

  • In the Debug tab, set Template Path Hints for storefront to Yes. To enable path hints for Admin set Template Path Hints for Admin to Yes.

  • To save the changes, click Save Config in the upper-right corner.

• Enable template hints with command line

  • bin/magento dev:template-hints:enable

  • clear cache

  • If you enabled hints for storefront with URL Param, reload the page with the param ?templatehints=magento

Layouts:

• The process of locating and working with layout files in Magento involves the following steps:

  1. Identify the Module: Determine which module the template for the element you're interested in belongs to. Layout files are saved per module.

  2. Search for Layout Files: Look for layout files in the following locations:

     • In current theme: <current_theme_dir>/<Namespace>_<Module>/layout/

     • In parent theme: <parent_theme(s)_dir>/<Namespace>_<Module>/layout/

     • In a module’s FE: <module_dir>/view/frontend/layout/

     • In a module: <module_dir>/view/base/layout/

  3. Example Process:

     • For a mini shopping cart in the Blank theme, determine the template path (app/code/Magento/Checkout/view/frontend/templates/cart/minicart.phtml) using template hints.

     • Then, search the fallback locations:

       • First, check the theme layout directory (app/design/frontend/Magento/blank/Magento_Checkout/layout/) but find no matching layout file.

       • Check the parent theme (if applicable), and then search the module’s layout directory (app/code/Magento/Checkout/view/frontend/layout/).

       • Finally, you find the layout file responsible for the mini cart: default.xml.

  4. Customize Layout: Once the layout file is identified, you can create your own layout file in the theme directory to override or extend content.

  This method of working with layout files ensures you can properly locate and customize the frontend layout as needed.

Styles

• To locate a CSS rule for a specific element, follow these steps:

  1. Identify the Element's Template: Find the template for the page containing the element, or use browser debugging tools to locate the class name.

  2. Search for the Class: Once you have the class name, search through the theme and module styles directories to locate the .less or .css file defining it. Follow this fallback search order:

     • Theme styles: <current_theme_dir>/web/css/

     • Module theme styles: <current_theme_dir>/<Namespace>_<Module>/web/css/

     • Parent theme styles: <parent_theme_dir>/web/css/

     • Parent theme module styles: <parent_theme_dir>/<Namespace>_<Module>/web/css/

     • Module frontend area styles: <module_dir>/view/frontend/web/css/

     • Module base area styles: <module_dir>/view/base/web/css/

  3. Example Process:

     • For the mini shopping cart in the Blank theme, the minicart-wrapper class is identified in the template (app/code/Magento/Checkout/view/frontend/templates/cart/minicart.phtml).

     • Search for "minicart-wrapper":

       • First, check the app/design/frontend/Magento/blank/web/css/ directory (no results).

       • Then, check app/design/frontend/Magento/blank/Magento_Checkout/web/css/, where the class is defined in _minicart.less.

  4. Override CSS: After finding the defining file, you can override the class definition in your own custom .css or .less files.

  This approach helps in locating and customizing CSS rules for specific elements in Magento.

Theme structure

Location

• Storefront themes are conventionally located under app/design/frontend/<Vendor>/

• built-in themes can be located under vendor/magento/theme-frontend-<theme_code> when a instance is deployed from the Composer repository.

Components:

• /<Vendor>_<Module>/web/css/ : Module-specific styles (.css and/or .less files). General styles for the module are in the _module.less file, and styles for widgets are in _widgets.less

• media directory contains a theme preview (a screenshot of your theme).

• /web/css/source: This directory contains theme LESS configuration files that invoke mixins for global elements from the UI library, and theme.less file which overrides the default variables values.

• /web/css/source/lib: View files that override the UI library files stored in lib/web/css/source/lib

app/design/frontend/
├── <Vendor>_<Module>/
│   ├── web/
│   │   ├── css/
│   │   │   ├── source/
│   │   │   ├──_module.less
│   │   │   ├──_widget.less
│   ├── layout/
│   │   ├── override/
│   │        ├── base/
│   │        ├── <parent theme>/
│   ├── templates/
├── etc/
├── i18n/
├── media/
├── web/
│   ├── css/
│   │   ├── source/
│   │       ├── lib/
│   │       ├── theme.less
│   ├── fonts/
│   ├── images/
│   ├── js/
├── composer.json
├── registration.php
├── theme.xml

Files:

• Static files: A set of theme files that are returned by the server to a browser as is, without any processing, are called the static files of a theme

  • media/ and web/ directories (css directory except the "source" sub-directory)

• Dynamic view files: View files that are processed or executed by the server in order to provide result to the client. These are: .less files, templates, and layouts