Theme Asset Management in SuiteCommerce Customizations

To effectively manage theme assets in SuiteCommerce, it's crucial to understand how assets are categorized and accessed within your custom themes. Assets, such as images and fonts, that are not directly managed by a NetSuite account but are part of a theme or extension can be organized and referenced dynamically to prevent issues with path changes when the theme is updated.

Asset Management in SuiteCommerce

An asset, in the context of SuiteCommerce, can be any media element that contributes to the visual style of your site. This includes carousel images, icons, or fonts. When deploying themes, assets are downloaded to specific directories based on whether they are part of the active theme or an active extension:

• Active theme assets are located in Workspace/<THEME_DIRECTORY>/assets.
• Active extensions' assets are located in Workspace/Extras/Extensions/<EXTENSION_DIRECTORY>/assets.
  Important: Do not modify, move, or delete any files in the Extras directory, as these are essential for functionality.

When a theme is activated, assets are placed in defined locations within the NetSuite File Cabinet. If the theme is updated, assets will be moved to a new location. Therefore, it’s essential to avoid using absolute paths for asset links in custom code, as these links may break with updates.

Best Practices for Asset Referencing

To facilitate dynamic path referencing without the need for constant code adjustments, utilize the HTML and Sass helpers provided by SuiteCommerce. These helpers ensure that your asset paths remain consistent, regardless of version changes:

HTML Helpers

The following Handlebars.js helpers assist in accessing asset paths:

• getExtensionAssetsPath(default_value): Access pre-existing assets from active extensions.
• getExtensionAssetsPathWithDefault(config_value, default_value): Retrieve a configured path, with a fallback to a default if necessary.
• getThemeAssetsPath(default_value): Access new and pre-existing assets in your theme.
• getThemeAssetsPathWithDefault(config_value, default_value): Similar to the above, but provides a fallback path.

Example Syntax Using HTML Helper:

To use the getExtensionAssetsPath helper in an HTML template, write:

<img src="{{ getExtensionAssetsPath 'img/logo.png' }}">

Example Result: This returns the actual asset path:

<FULL_PATH>/extensions/<VENDOR>/<EXTENSION>/<VERSION>/img/logo.png

Sass Helpers

For those customizing Sass files, the following helpers provide similar functionality:

• getExtensionAssetsPath($asset): Accesses previously included assets in an active extension.
• getThemeAssetsPath($asset): Accesses assets included in your theme directory.

Example Syntax Using Sass Helper:

body {
   background-image: url(getExtensionAssetsPath('img/background-image.png'));
}

Key Considerations

• Always use dynamic helper functions when referencing assets to ensure that paths remain accurate and functional even after theme updates.
• Limit the complexity of your file structure and avoid absolute paths to prevent breaking changes.
• Familiarize yourself with the themes and extensions structure in your Workspaces, following best practices to ensure smooth theme deployment and maintenance.

Maintaining dynamic paths through asset helpers minimizes coding errors and maximizes efficiency in SuiteCommerce customizations.

Source: This article is based on Oracle's official NetSuite documentation.