Fetch Active Theme Files

This topic applies to

Applies to

SuiteCommerce Web Stores

To create a theme, you first download files for the currently active theme to use as the baseline for your own custom theme. You can download files of any published theme or any previously deployed custom theme.

When you run the gulp theme:fetch command, the theme developer tools download all editable theme-related files for the active theme and place them in your theme workspace. If you have any active extensions when you run the gulp theme:fetch command, the Sass, HTML, and assets of those extension download to your local environment as well. These are provided should you need to make changes to the extensions to match your new theme.

Warning

When you fetch a theme, the developer tools download the active theme’s development files to your theme directory. This action overwrites any theme files currently stored in your local workspace. This can result in loss of development files if you are not careful. To ensure that you do not lose any work under development, do not run the gulp theme:fetch command until you have deployed your work to NetSuite. To develop two or more themes simultaneously, you must extract the theme developer tools into separate workspaces, one for each theme.


Important

You must at least have a theme activated for a domain before continuing with this procedure. If this is your first theme, activate the SuiteCommerce Base Theme to use as your baseline. This theme includes many best practices for creating a theme. See Install Your SuiteCommerce Application for a list of required SuiteApps and corresponding Bundle IDs.


To fetch the active theme and extension files:

  1. Open a command line or terminal.

  2. Access the top-level theme development directory you created when you downloaded the developer tools.

  3. Enter the following command:

    gulp theme:fetch
  4. When prompted, enter the following information:

    • NetSuite Email – Enter the email address associated with your NetSuite account.

    • NetSuite Password – Enter your account password.

      Note

      The developer tools do not support emails or passwords containing special characters such as + and %.


    • Choose Your Target Account and Role – Select the NetSuite account where your SuiteCommerce application is installed. You must specify the correct role with required permissions for connecting to NetSuite.

      Important

      You must log in using the SCDeployer role to access your NetSuite account. Failure to use this role may result in an error. See Developer Tools Roles and Permissions for instructions on setting up this role.


    • Choose Your Website – Select your website that includes the domain you are customizing.

    • Choose Your Domain – Select your domain with the active themes and extensions you want to download.

Your next step is to develop your theme. See Themes for details.

What Happens When You Fetch an Active Theme?

When you run the gulp theme:fetch command, the theme developer tools:

  • Create the Workspace directory in your theme development directory. If the Workspace directory already exists, the developer tools clear its contents before downloading. This action overwrites any files currently stored in your local workspace with the files being fetched.

  • Download all theme-related HTML and Sass files for the active theme and store them in your workspace by module within a directory specific to the theme. For example, Workspace/<THEME_DIRECTORY>/Modules. The theme directory is intuitively named to match the name of the active theme.

  • Download all theme-related assets to Workspace/<THEME_DIRECTORY>/assets.

  • Download all theme-related skin preset files to Workspace/<THEME_DIRECTORY>/Skins.

  • Validate that all files declared in the theme’s manifest.json have been downloaded correctly. If any problems occurred, the developer tools list all missing files and direct you to execute the gulp theme:fetch command again.

If the chosen domain includes any active extensions when you fetch the active theme, the developer tools:

  • Download all extension-related HTML and Sass files for the active extensions and store them in your workspace by module within directories specific to each active extension. For example, Workspace/Extras/Extensions/<EXTENSION_DIRECTORY>/Modules. The extension directories are intuitively named to match the name of each active extension.

  • Download all extension-related assets to ../Workspace/Extras/Extensions/<EXTENSION_DIRECTORY>/assets.

  • If you are downloading a theme that includes previously deployed overrides, the developer tools download these into ../Workspace/<THEME_DIRECTORY>/Overrides.

When you fetch the active theme, you are basically downloading the HTML, Sass, and assets files for the active theme to use as a baseline for your own theme development. Because a published theme is protected by copyright, you cannot overwrite any files for that theme. You can, however, use an existing theme as a baseline for your own, which you later deploy as a unique theme. The SuiteCommerce Base Theme SuiteApp provides a good starting point for building your own theme.

Note

Although you cannot overwrite a published theme, you can make any development changes to your own themes.


When you fetch a theme for a domain, the developer tools download the HTML, Sass, and asset files for the active theme plus any HTML, Sass, and asset files of any extensions active at the time you run the gulp theme:fetch command. The local server needs these files to compile your theme when testing locally. You also have the opportunity to override the HTML and Sass for the active extensions with custom changes or add new assets. Any overrides you declare affect the domain once activated. Be aware that this only affects your domain. You are not overwriting any published extension’s code.

Example:

Your domain has an active theme, SuiteCommerceBaseTheme, and an active extension, PublishedExtension1. Your Vendor name is ACME. You run the gulp theme:fetch command and specify your domain.

In this example, your Workspace directory structure should look similar to following:

Workspace/
      Extras/
         Extensions/
            ACME/
               PublishedExtension1/
                  assets/
                  Modules/
                  manifest.json
               application_manifest.json
      SuiteCommerceBaseTheme/
         assets/
         Modules/
         Overrides/
         Skins/
         manifest.json

When the gulp processes are complete your theme developer environment should look similar to the following:

File Types

Workspace Subdirectory

Theme-related HTML and Sass files

../SuiteCommerceBaseTheme/Modules/

Theme-related asset files

../SuiteCommerceBaseTheme/assets/

Theme-related skin presets

../SuiteCommerceBaseTheme/Skins/

Extension-related HTML and Sass source files (sorted by module)

../Extras/Extensions/ACME/PublishedExtension1/Modules/

Extension-related asset files

../Extras/Extensions/ACME/PublishedExtension1/assets/

Pre-existing extension overrides

../SuiteCommerceBaseTheme/Overrides/