Managing Theme Assets
An asset is an image or font that is not managed by a NetSuite account but still is part of a theme or extension. An example of an asset is a carousel image, an icon, or a new font. This can be either a pre-existing asset or one that you introduce as part of a new theme.
When you run the gulp theme:fetch command:
-
Assets for the active theme download to your Workspace/<THEME_DIRECTORY>/assets folder. This is the location where you manage all of your assets (new and pre-existing).
-
Assets for any active extensions download to your Workspace/Extras/Extensions/<EXTENSION_DIRECTORY>/assets folder. Do not move, delete, edit, or add files in this location.
When you activate your theme, all assets are placed in specific locations in your NetSuite File Cabinet based on parameters you specify when you deployed your theme (vendor name, theme name, and theme version). Later, when you activate a newer version of the same theme, your assets are now located in a different location in your File Cabinet. Your code must adapt to the change in the path. If you use absolute paths, the asset links break.
Do not use absolute paths when referring to assets in your code customzations and overrides. Asset files are managed in different locations in NetSuite based on the theme’s vendor, extension name, version, and so on. As a best practice, always use the HTML and Sass helpers when referencing assets to ensure that you maintain dynamic paths without unnecessary code changes.
To maintain dynamic paths to your assets, regardless of the vendor, theme, version, and so on, use the following helpers:
Example:
Using the theme developer tools, you deploy a new theme (MyTheme1, Version: 1.0.0). You then activate that theme for a specific site and domain. The compiler places all assets in your NetSuite File Cabinet. The exact location is specific to the SSP application, vendor, extension, and version that you specified when you deployed your theme.
This location might be similar to the following representation:
Later, you decide to update your theme, giving it a new version, 2.0.0. When you activate your latest version, the compiler places all assets into a new location:
HTML Helpers
The following Handlebars.js helpers provide a means to maintain dynamic paths to your assets when customizing HTML templates.
getExtensionAssetsPath(default_value)
Use this HTML template helper:
-
To access pre-existing assets included with an active extension
-
In your extension overrides (templates)
The default_value argument is the relative path to the asset.
Example Syntax in a Template File:
The following is an example of how to use this helper in an HTML template:
<img src="{{ getExtensionAssetsPath 'img/logo.png' }}">
Example Result:
This helper returns the active extension’s asset path (where <FULL_PATH> is the SSP Application base path):
<FULL_PATH>/extensions/<VENDOR>/<EXTENSION>/<VERSION>/img/logo.png
getExtensionAssetsPathWithDefault(config_value, default_value)
Use this HTML template helper:
-
To access pre-existing assets included with an active extension
-
In your extension overrides (templates)
-
When you expect that the asset has a configured path in NetSuite, but want to provide a default path if the configuration does not exist.
The first argument (config_value) is the path as configured in NetSuite. In cases where the asset is not configured, you provide a fallback path (default_value) to be retrieved from the extension’s assets.
Example Syntax in a Template File:
The following is an example of how to use this helper in an HTML template:
<img src="{{getExtensionAssetsPathWithDefault logo_path 'img/logo.png' }}" >
Example Result:
This helper returns the active extension’s asset path. If the first argument is defined, this helper returns the path as configured in NetSuite:
<MY_PATH>/img/other_logo.png
If the first argument is undefined, this helper uses the second argument to return the correct path of the active extension:
<FULL_PATH>/extensions/<VENDOR>/<EXTENSION>/<VERSION>/img/logo.png
getThemeAssetsPath(default_value)
Use this HTML template helper:
-
To access new and pre-existing assets included in your theme directory
-
In your extension overrides (templates)
-
In your theme customizations (templates)
Using this helper, default_value is the relative path to the asset.
Example Syntax in Template File:
<img src="{{ getThemeAssetsPath 'img/logo.png' }}" >
Example Result:
This helper returns the active theme’s asset path (where <FULL_PATH> is the SSP Application base path):
<FULL_PATH>/extensions/<VENDOR>/<THEME_NAME>/<VERSION>/img/logo.png
getThemeAssetsPathWithDefault(config_value, default_value)
Use this HTML template helper:
-
To access new and pre-existing assets included in your theme directory
-
In your extension overrides (templates)
-
In your theme customizations (templates)
-
When you expect that the asset has a configured path in NetSuite, but want to provide a default path if the configuration does not exist.
Using this helper, config_value is the path as configured in NetSuite. In cases where the asset is not configured, you provide a fallback path (default_value) to be retrieved from the extension’s assets.
Example Syntax in Template File:
<img src="{{ getThemeAssetsPathWithDefault logo_path 'img/logo.png' }}" >
Example Result:
This helper returns the active theme’s asset path. If the first argument is defined, this helper returns the path as configured in NetSuite:
<MY_PATH>/img/other_logo.png
If the first argument is undefined, this helper uses the second argument to return the correct path of the active theme:
<FULL_PATH>/extensions/<VENDOR>/<THEME_NAME>/<VERSION>/img/logo.png
Sass Helpers
The following helpers provide a means to maintain dynamic paths to your assets when customizing Sass files:
getExtensionAssetsPath($asset)
Use this Sass helper:
-
To access pre-existing assets included with an active extension
-
In your extension overrides (Sass)
Example Syntax in a Sass File:
body {
background-image: url(getExtensionAssetsPath('img/background-image.png'));
}
Example Result:
This helper returns the active extension’s asset path.
<FULL_PATH>/extensions/<VENDOR>/<EXTENSION>/<VERSION>/img/logo.png
getThemeAssetsPath($asset)
Use this Sass helper:
-
To access new and pre-existing assets included in your theme directory
-
In your extension overrides (Sass)
-
In your theme customizations (Sass)
Example Syntax in a Sass File:
body {
background-image: url(getThemeAssetsPath('font-awesome'));
}
Example Result:
This helper returns the active theme’s asset path.
<FULL_PATH>/extensions/<VENDOR>/<THEME_NAME>/<VERSION>/font-awesome