Override Active Extension Files
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 add 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.
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 ensures that the active extension includes your Sass variable, without 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 files 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.
When you download an extension’s HTML and Sass files, the theme developer tools place them in your Extras/Extensions directory, sorted by extension. These are for reference only. At the same time, the developer tools create an identical directory structure in your theme’s Overrides directory.
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. For more information, see Add a New File to a Theme and Managing Theme Assets.
To customize an extension using the override method:
-
Locate the source file you want to override.
For example, if you want to override a file named _Pub-Extend-Error.scss in Published Extension 1, 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 -
Copy the source file to your operating system’s clipboard.
-
Paste a copy of the file in the corresponding location within the theme’s Overrides directory. For example:
Workspace/Theme/Overrides/Modules/PubExtendModule@1.0.0/Sass/_Pub-Extend-Error.scssImportant:Do not rename these files. These files must have the same name for the override method to function correctly.
-
Open your new file in your Overrides directory.
-
Follow best practices to customize your new file. See Best Practices for Creating Themes for important details on customizing these files.
-
Repeat this procedure for all extension-related files you need to customize.
When you are ready, use the theme developer tools to test or deploy your theme. See Test and Deploy Your Theme for procedures on how to use these tools.