Override a Template File
Making changes to core JavaScript source files or changing vital functionality of the application can make migrating to future releases difficult. Before making changes to SuiteCommerce Advanced (SCA), see Best Practices for Customizing SCA.
This example describes how to override a template file if you are on the Kilimanjaro release of SCA or earlier. If implementing the Aconcagua release of SCA or later, the best practice is to use themes and extensions to customize your website. See Develop Themes and Develop Extensions for more information.
When customizing SCA, you may need to change the HTML code of the application. To add, remove, or change the HTML, you must customize the template file for the module that corresponds to the feature you want to change. To customize a template, you must use the override method provided by the SCA developer tools. Because there is no mechanism for overriding or extending a specific part of a template, you must override the entire file.
This example describes how to override a template file to add additional text to the product description page. You can use this example as a guide when customizing your own templates.
To override a template:
-
Create a directory to store your template. Where you place this directory depends on your implementation.
-
If implementing 2019.2 and later, create this directory within the SCA source code root directory. Examples:
SC_20.1/extensions
,SC_19.2_Live/extensions
. -
If implementing 2019.1 and earlier, create this directory within the Modules directory. For example:
Modules/extensions
.
-
In the
extensions
directory, create a subdirectory calledItemDetailsExtension@1.0.0
.When creating a new custom module, the module name must be unique. You must not have duplicate module names, even if those modules reside in different folders.
-
In the
ItemDetailsExtension@1.0.0
directory, create a subdirectory calledTemplates
. -
If required, create another subdirectory called
Sass
.
You should create a directory structure similar to that described in Organize Source Code for Custom Modules.
-
-
Copy the original template file to your custom directory. The string
x.y.z
corresponds to the version of the ItemDetails module in your version of SCA.-
If implementing 2019.2 and later, copy the
item_detail.tpl
file from/ItemDetails@x.y.z/Templates
to theTemplates
directory of your custom application module.
-
If implementing 2019.1 and earlier, copy the
item_detail.tpl
file fromModules/suite_commerce/ItemDetails@x.y.z/Templates
to theTemplates
directory of your custom application module.
-
-
Create the
ns.package.json
file.You must create this file in the
ItemDetailsExtension@1.0.0
directory. -
Add the required code to the
ns.package.json
file.-
If implementing 2019.2 and later, the contents of your
ns.package.json
file should be similar to:{ "gulp": { "templates": [ "Templates/*" ] , "sass": [ "Sass/**/*.scss" ] }, "overrides": { "Advanced/ItemDetails@x.y.z/Templates/item_details.tpl": "Templates/item_details.tpl" } }
-
If implementing 2019.1 and earlier, the contents of your
ns.package.json
file should be similar to:{ "gulp": { "templates": [ "Templates/*" ] , "sass": [ "Sass/**/*.scss" ] }, "overrides": { "suitecommerce/ItemDetails@x.y.z/Templates/item_details.tpl": "Templates/item_details.tpl" } }
Note:You must replace the string
x.y.z
in the preceding code samples with the version of the ItemDetails module in your version of SCA. SutieCommerce 2019.2 and later do not include the @x.y.z directory name suffix.The first section of the preceding code samples defines the required objects used by gulp to include your customized template and Sass files when combining the application.
The second section contains the override directive, which maps the original file in the SCA source distribution directory to your custom template file. This mapping tells the gulp.js combiner to override a specific file.
-
-
Edit your custom template.
This procedure shows the basic steps required to modify a template. However, you can fully customize your templates as required. See Commerce Sass Style Definitions for more information.
-
Open the
item_details.tpl
file that you copied in a previous step. -
In your editor, search for the string Add to Cart.
This string defines the label for the add to cart button.
-
Replace this string with the string ‘Add to Your Cart.'
-
-
Create a custom Sass file, if required.
See Extend a Sass File for more information.
-
Update the
distro.json
file.You must add your custom module to the
distro.json
file to ensure that the gulp tasks include your custom template. If you are customizing Sass files, you must also add a reference to them in the appropriate location in thedistro.json
file. See Extend a Sass File for more information.In the following code samples, the
ItemDetailsExtension
module is added at the beginning of the list of modules. However, you can add the module anywhere in themodules
object. If a module contains only customized template or Sass files, the order of precedence in this list does not matter.-
If implementing 2019.2 and later, add an entry for the new module in the list of modules in the
modules
object as shown in the following sample:{ "name": "SuiteCommerce Advanced Live", "version": "2.0", "isSCA": true, "buildToolsVersion": "Live", "folders": { "thirdPartyModules": "../../third_parties", "distribution": "../LocalDistribution", "deploy": "../DeployDistribution" }, "modules": { "../extensions/ItemDetailsExtension": "1.0.0", "../Commons/Address", "../Commons/AjaxRequestsKiller", ...
-
If implementing 2019.1 and earlier, add an entry for the new module in the list of modules in the
modules
object as shown in the following sample:{ "name": "SuiteCommerce Advanced Mont Blanc", "version": "2.0", "buildToolsVersion": "1.1.0", "folders": { "modules": "Modules", "suitecommerceModules": "Modules/suitecommerce", "thirdPartyModules": "Modules/third_parties", "distribution": "LocalDistribution", "deploy": "DeployDistribution" }, "modules": { "extensions/ItemDetailsExtension": "1.0.0", "suitecommerce/Account": "2.1.0", ...
-
-
View your changes.
If you are running a local server, you can view your changes by reloading your website. See Test SCA Customizations on a Local Server for more information.
If you are viewing your site in NetSuite, you can deploy your changes using the developer tools. See Deploy SCA Customizations to NetSuite for more information.
When viewing your changes, you should see new button label and the item details and item image should be reversed.
Related Topics
- Example SCA Customizations
- Create a Custom Module
- Modify JSON Configuration Files
- Extend Frontend Configuration Files
- Configure Facet Fields
- Extend the Backend Configuration File
- Add a Child View to a Composite View
- Extend a Sass File
- Add a Sticky Button
- Customizing the Loading Icon
- Adding a Custom Web Font
- Extending Font Awesome
- Displaying Device-Specific Carousel Images