Override a Template File

This topic applies to

Applies to

SuiteCommerce Advanced

View a Related Video

Important

Making changes to core JavaScript source files or changing any vital functionality of the application can make migrating to future releases difficult. Before making changes to SuiteCommerce Advanced (SCA), see Best Practices for Customizing SuiteCommerce Advanced.


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 developer tools. Since 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:

  1. Create the directory structure to store your customized template.

    1. Create a directory called extensions within the Modules directory.

    2. In the extensions directory, create a subdirectory called ItemDetailsExtension@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.

    3. In the ItemDetailsExtension@1.0.0 directory, create a subdirectory called Templates.

    4. If required, create another subdirectory called Sass.

    In general, when creating custom modules, you should create a directory structure similar to that described in the procedure above. See Organize Source Code for Custom Modules for more information.

  2. Copy the original template file to your custom directory.

    Copy the item_detail.tpl file from Modules/suite_commerce/ItemDetails@x.y.z/Templates to the Templates directory of your custom application module. The string x.y.z corresponds to the version of ItemDetails module in your version of SCA.

  3. Create the ns.package.json file.

    You must create this file in the ItemDetailsExtension@1.0.0 directory.

  4. Add the required code to the ns.package.json file.

    The contents of your ns.package.json file should be similar to the following:

    {
       "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 above example with the version of the ItemDetails module in your version of SCA.


    The first section of this example 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. In this example, this mapping tells the gulp.js combiner to override a specific file.

  5. 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 Design Architecture for more information.

    1. Open the item_details.tpl file you copied above.

    2. In your editor, search for the string Add to Cart.

      This string defines the label for the add to cart button.

    3. Replace this string with the string ’Add to Your Cart.'

  6. Create a custom Sass file, if required.

    See Extend a Sass File for more information.

  7. 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 the distro.json file. See Extend a Sass File for more information.

    • Add an entry for the new module in the list of modules in the modules object as shown below:

      {
          "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",
                    ...
      
      

      In this example, the ItemDetailsExtension module is added at the beginning of the list of modules. However, you can add the module anywhere in the modules object. If a module contains only customized template or Sass files, the order of precedence in this list does not matter.

  8. View your changes.

    If you are running a local server, you can view your changes by reloading your website. See SCA 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 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.