Add a New File to a Theme

This topic applies to

Applies to

SuiteCommerce Web Stores

When you customize a theme, you can also create new HTML, Sass, or asset files to meet your needs. This procedure includes editing a manifest file to ensure that your new file compiles at activation.

Note

To reference assets within your code, use the HTML and Sass Helpers provided. See Asset Best Practices for more information.


To create a new file for a theme:

  1. Create your new HTML, Sass, or asset file in the correct location, as required.

    File Type

    Location Within Workspace/<THEME_DIRECTORY>/

    HTML

    Modules/<MODULE>/Templates

    Sass

    Modules/BaseSassStyles/Sass/reference-theme

    Assets

    assets

  2. Create each file as required. See Best Practices for Creating Themes for details.

    Important

    To avoid file name collisions, do not create any new files or folders that share the same name, even if they reside in different locations.


  3. Save this file in the correct location within your directory structure.

    For example, you want to add a new Sass file titled _newSass.scss. As a best practice, save this file in the following location:

    Workspace/<THEME_DIRECTORY>/Modules/BaseSassStyles/Sass/reference-theme/_newSass.scss
  4. Open the theme’s manifest.json file.

    For example:

    Workspace/<THEME_DIRECTORY>/manifest.json
  5. Include your new file in the appropriate location as required:

    • If adding a template, list the file by application. Include the .tpl file in the files array of the appropriate application object (Shopping, MyAccount, or Checkout). When declaring your new file, include the path to the correct module. The order of your declaration does not matter.

      For example:

      //...
      "templates": {
         "application": {
            "shopping": {
               "files": [
                  //...
               ]
            }
         }
      //...
    • If adding a Sass file, list the .scss file in the files array of the sass object. You set up the Sass entry point in a later step. When declaring your new file, include the path to the correct module. Add this line in a location that makes the most semantic sense within the Sass hierarchy. For example:

      //...
      "sass": {
         "entry_points": {
            "shopping": "Modules/Shopping/shopping.scss",
            "myaccount": "Modules/MyAccount/myaccount.scss",
            "checkout": "Modules/Checkout/checkout.scss"
         }
         "files": [
            //...
         ]
      }
      //...
    • If adding an asset, add your asset as part of the files array of the img, font-awesome, or font object, as appropriate. When declaring your new file, include the path to the correct folder (img/, font-awesome/, or font/). The order of your declaration does not matter. For example:

      //...
      "assets": {
         "img": {
            "files": [
               //...
            ]
         }
         "font-awesome": {
            "files": [
               //...
            ]
         }
      }
      //...

    This ensures that the compiler includes your customizations. In this example, you are adding a Sass file. Therefore, you add newSass.scss as a dependency to the files array of the sass object.

    Your manifest file might look similar to the following example:

    "sass": {
       "entry_points": {
          "shopping": "Modules/Shopping/shopping.scss",
          "myaccount": "Modules/MyAccount/myaccount.scss",
          "checkout": "Modules/Checkout/checkout.scss"
       }
       "files": [
          //...
          "Modules/BaseSassStyles@x.y.z/Sass/reference-theme/_newSass.scss",
          //...
  6. Save the manifest.json file.

  7. If your new file is an asset or template, you have no further action required. However, if your new file is a Sass file, follow these additional steps:

    1. Identify the application or applications impacted by your new Sass file.

    2. Edit the application entry point file to include the same dependency you introduced in the manifest file.

      Application Impacted

      Application Entry Point

      Shopping

      Modules/Shopping/shopping.scss

      My Account

      Modules/MyAccount/myaccount.scss

      Checkout

      Modules/Checkout/checkout.scss

      In this example, the Cart module impacts the Shopping application. Therefore, you open the Shopping entry point file and include the dependency. Your Shopping.scss file should look similar to the following example:

      //...
      @import "../BaseSassStyles@x.y.z/Sass/reference-theme/newSass";   
      //...

      Just as you did in the manifest.json file, place this file in such a manner that makes semantic sense within the Sass hierarchy you are customizing.

    3. Save the application Sass file.

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.