Override Active Extension Files

This topic applies to

Applies to

SuiteCommerce Web Stores

When creating a theme, you can customize the HTML and Sass of any active extensions for a domain and deploy them with your theme customizations.

When you run the gulp theme:fetch command, you download the theme Sass, HTML, and asset files. You also download all extension-related HTML and Sass files. The developer tools place these in the appropriate folder within the Workspace/Extras/extension directory.

This section explains how to use the Override method to customize HTML and Sass files related to extensions.

Important

Extension-related files placed in the Extras directory are provided as a reference only. Never edit these files directly. Instead, use the Override method described in this section.


Example

You activate a theme for your domain. You also activate an extension for the same domain. You create your theme to include a new color variable. You want the extension that is active with your theme to use this same variable. However, the extension’s Sass does not include the new variable. You must customize the extension’s Sass files to include this color variable using the Override method. This ensure that the active extension includes your Sass variable, without actually changing the extension’s code. Instead, you override it.

All of your theme customizations and extension overrides are maintained as part of your theme. Therefore, when you later activate your theme and the extension for your domain, the active extension includes your new color variable. This does not change the extension. Instead, this change belongs to the theme.

The Override Method

To customize extension-related HTML and Sass files, you must use the Override method. This involves placing copies of source HTML and Sass from your Extras directory into your theme directory and making your customizations there. When you deploy your changes, the theme development tools detect the new files and initiate an override within the manifest.

Note

When you downloaded an extension’s HTML and Sass files, the theme developer tools placed them in your Extras/Extensions directory, sorted by extension. These are for reference only. At the same time, the developer tools created an identical directory structure in your theme’s Overrides directory.


Important

You cannot override asset files. To introduce new assets for your template customizations or extension overrides, add them as you would for any new files within the template directory, then reference the assets using the HTML and Sass Helpers. See Add a New File to a Theme. See Asset Best Practices for details on using helpers.


To customize an extension using the Override method:

  1. Locate the source file you want to override.

    For example, you want to override the _Pub-Extend-Error.scss file of the Published Extension 1 extension. Therefore, the file you want to override is in the following location:

    Workspace/Extras/Extensions/PublishedExtension1/Modules/PubExtendModule@1.0.0/Sass/ _Pub-Extend-Error.scss
  2. Copy the source file to your operating system’s clip board.

  3. Paste a copy of the file in the corresponding location within the theme’s Overrides directory.

    For example:

    Workspace/<THEME_DIRECTORY>/Overrides/Modules/PubExtendModule@1.0.0/Sass/_Pub-Extend-Error.scss

    Important

    Do not rename these files. These files must share the same name for the Override method to function correctly.


  4. Open your new file in your Overrides directory.

  5. Follow best practices to customize your new file. See Best Practices for Creating Themes for important details on customizing these files.

  6. Repeat this procedure for all extension-related files you intend to customize.

When you are ready, use the theme developer tools to test or deploy your theme. See Theme Developer Tools for procedures on how to use these tools.