General Best Practices

When developing customizations for your Commerce websites, follow the best practices outlined in these sections:

• Use Configuration Instead of Customization

• Use the Extensibility API Whenever Possible

• Use the SuiteCommerce Implementations of BackboneJS Modules

• Do Not Extend Extensions

• Working with Core Modules

• Get Configuration Values with the Environment Component

• Specify a Target Version for Extensions

Use Configuration Instead of Customization

Before starting development work on an extension, consider whether SuiteCommerce already offers what you want to achieve with a custom extension. Instead of creating an extension, you may be able to configure your NetSuite account and the built-in features of the SuiteCommerce application. By configuring instead of customizing, you may benefit from a faster implementation time, tried and tested code, and continued support of the feature or functionality. Some of the ways in which you can configure SuiteCommerce include:

• Enabling and configuring built–in SuiteCommerce features such as personalized catalog views, commerce categories, and checkout flows.

• Changing settings on the configuration record and the website setup record to modify the look and feel of the website or the backend functionality.

• Using Site Management Tools (SMT) to configure the features and extensions that are enabled in the NetSuite account.

For more information, see Configure Instead of Customize.

Use the Extensibility API Whenever Possible

Extensions in both SuiteCommerce and SuiteCommerce Advanced have access to the extensibility API. The extensibility API provides a stable layer between your custom extension and the core code of the SuiteCommerce application. The components in the extensibility API have methods and properties that are documented in the API reference and are managed by Oracle NetSuite to ensure maximum compatibility and consistency across SuiteCommerce sites and versions.

Although SuiteCommerce Advanced gives you access to the SuiteCommerce source code, you should still use the extensibility API whenever possible. Because SuiteCommerce Advanced is an unmanaged bundle (it is not upgraded automatically by Oracle NetSuite at the time of each release), you may not have access to all components and their methods and events. Check the extensibility API reference for information about the components that are available in each release.

Extensibility API Components

Components in the extensibility API contain methods and events that enable an extension to interact with the website, as well as the underlying SuiteCommerce environment and configuration. Some components are general components that provide the foundation of an extension such as SCView or SCModel, whereas other components let you perform actions in a specific context. For example, you can use the PDP (product details page) component to get the stock information of an item. You can also listen for certain events such as when an option is selected or a quantity is changed on the page (see Work with Events in an Extension for more information).

Most components in the extensibility API typically provide:

• Methods – Getter and setter methods let you fetch and save data.

• Events – Many components provide ‘before’ and ‘after’ cancelable events that let you interrupt an action depending on the logic or criteria of your extension. For example, you could validate a promo code before it is applied to items in the cart.

The following example shows how the on method is used to listen for the beforeQuantityChange cancelable event. When a website visitor changes the quantity of an item on the PDP, the beforeQuantityChange event is fired. As one of the parameters to on, you specify a handler that is called when the event occurs. In this case, the handler checks if the quantity is a number and displays a browser alert if isNumber() returns false. A return value of false prevents the quantity from being changed.

              var pdp = container.getComponent('PDP');

pdp.on('beforeQuantityChange', function() {
  if (!_.isNumber(newquantity)) {
    alert('That is not a valid quantity.');
    return false;
  }
}); 

            

Use the SuiteCommerce Implementations of BackboneJS Modules

The Backbone.js library is one of the core technologies on which a SuiteCommerce website relies. The extensibility API contains several components, however, that are intended to replace the usage of the Backbone modules. The SuiteCommerce components provide classes, methods, and events that are specifically designed for SuiteCommerce websites. More information about each component is available in the extensibility API reference.

Component Usage	Available Since	Core Backbone Module
SCModel– SCModel lets you define a model for your extension.	SuiteCommerce 2020.1	Backbone.Model
SCView– Use SCView to define a view that renders content on a part of the website.	SuiteCommerce 2020.2	Backbone.View
SCFormView – SCFormView provides functions to validate form data, save form data, and display error messages related to form input.	SuiteCommerce 2020.2	Backbone.FormView
SCCollection – Use SCCollection to hold a set of models.	SuiteCommerce 2020.1	Backbone.Collection
SCCollectionView – SCCollectionView lets you display a collection (list) of items, usually in a grid pattern.	SuiteCommerce 2020.2	Backbone.CollectionView

Do Not Extend Extensions

You should avoid extending extensions created by Oracle NetSuite or other third-parties. You should also avoid extending the extensibility API components. Reasons to not extend extensions include:

• By extending an extension, you are effectively depending on an environment where a site administrator can disable any extension at any time in the NetSuite account.

• The developer of an extension may change its behavior, methods, or return values without warning. If your extension relies on the behavior or methods in another extension, your extension may stop working.

If you do want to extend an extension, however, you could consider the following approaches:

• If you own the extension you want to extend, consider creating an API within the extension code that can be called by the new extension.

• If you do not own the extension, consider creating an adapter for it and then let the new extension communicate with it through the adapter.

Working with Core Modules

When developing extensions for SuiteCommerce websites, you should avoid involving core modules to ensure your extensions function as expected when new versions of the SuiteCommerce bundle are pushed to your account. Read the following guidelines to learn more about practices to avoid.

Note:

For SuiteCommerce Advanced (SCA) sites, you have more flexibility when it comes to working with SCA core modules in your extensions. However, the following guidelines apply to SCA sites, too, if you want to minimize the issues you may encounter when you migrate to a new SCA version or when you apply your extension to another website.

When working with core modules in your extensions, follow these guidelines:

• Do not include a core module in a require() or define() statement.

• Do not extend (extend()) a core module to add or overwrite a method or property.

• Do not wrap (_.wrap()) a core module’s method to change its output.

• Do not modify a core module or object’s prototype. For example, you should:

  • Use addChildView() to add a child view rather than SomeView.prototype.childViews.MyChildView.

  • Use addToViewContextDefinnition() to add a new property to a view’s context object, rather than SomeView.prototype.getContext.MyNewProperty.

The following guidelines apply to working with core modules in any production code:

• To access a core module or object’s private method, use application.getLayout(). Do not use application._layoutInstance.

• Do not access the SC global variable.

• Do not edit core modules directly; use overrides instead.

Get Configuration Values with the Environment Component

Use the Environment component to get configuration values of the website instead of the SC.Configuration module or the SC global variable. For example, to determine the current add to cart behavior of the website, you should get the addToCartBehavior configuration value.

            var env = container.getComponent('Environment');
var addToCartBehavior = env.getConfig('addToCartBehavior'); 

          

Specify a Target Version for Extensions

You should specify version compatibility in your extension to ensure that it can only be installed and activated on a compatible SuiteCommerce website. If the extension is not compatible with the website, it is hidden on the Activate Themes and Extensions page in the NetSuite account. To specify version compatibility, use the target_version key in the extension manifest file.

            "target_version": {
  "SCA": ">=21.2.0",
  "SCS": ">=21.2.0"
} 

          

See Edit the Extension Manifest for more information about manifest metadata.

When creating an extension for SuiteCommerce Advanced, you should also check the extensibility API to determine if a component or method is available in a particular version of SCA. In addition, when you instantiate a component, you can verify that it is available by checking its return value. If a component is not available, its return value is null.

            var userProfile = container.getComponent('UserProfile');

if (userProfile) {
  // Component is available
} 

          

Related Topics

Best Practices for Developing Commerce Extensions

Use Custom Handlebars Helpers

Use Multiple Modules in an Extension

General Notices