Best Practices for Customizing SuiteCommerce Advanced

This topic applies to

Applies to

SuiteCommerce Advanced

NetSuite recommends following these best practices when customizing or extending SuiteCommerce Advanced (SCA). These best practices are designed to provide an easier path for migration when you have changed or added features to the application. Following these best practices enables you to install new versions of a bundle more quickly to take advantage of new features and issue fixes.

Different types of files and resources in SCA have different recommended best practices. These are described in the following sections:

Organize Source Code for Custom Modules

Before making changes to SCA, you must decide on the conventions you want to use to organize your custom modules. NetSuite recommends placing all of your customizations in a directory structure that is outside of the Modules/suite_commerce directory structure. For example, you may use a directory structure similar to the following:

SuiteCommerce Advanced
      ...
      Modules
         extensions
         suitecommerce
         third_parties
      ...

In this example hierarchy, your custom modules are stored in the extensions directory. Within your custom directory, name your modules using a version naming convention such as:

module_name@x.y.z

This convention corresponds to the SEMVER (Semantic Versioning) schema. NetSuite recommends that you use this schema when organizing your modules. For example, if you were creating a new module, your module may be named: MyCustomModule@1.0.0

This naming convention should also apply when extending an existing module. For example, if you are customizing the Case module, your custom module may be named: CaseExtension@1.0.0.

See http://semver.org for more information on the SEMVER schema.

Another consideration when determining how to organize your customization source code is to determine how to organize template overrides. As mentioned in Override Template Files, you must override the entire template file, and each template file can only be overridden once. However, the view that uses the template file may be extended in multiple modules. Therefore, you may want to have a convention where template overrides are always performed in their own custom module. The module containing the template override could then be used by other modules that extend the functionality of the view.

Extend JavaScript

When customizing a property, object, or method within JavaScript, you should use the JavaScript prototype object. By calling the JavaScript prototype function, you can extend a specific property, object, or method without having to extend or override an entire model or view.

The primary advantage of using the JavaScript prototype method is that it improves the chances that your customizations continue to work when migrating to a newer version of SCA. When using JavaScript prototypes, the original version of the method or property, is still present along with your customizations. If a new version of SCA contains any issues fixes or enhanced features that are related to that method or property, both the new functionality and your changes are still in place.

See Add a Child View to a Composite View for an example of how to implement prototyping.

For best results, do not use the override feature of the developer tools when customizing JavaScript files. When overriding a file, all the functionality of a method or property is replaced. When a new version of SCA is installed, any fixes and enhancements are overridden. This can cause problems in both the core SCA functionality and in your customizations.

Customize the Configuration Manifest

This section applies to Vinson implementations of SCA and later. For details on how to configure properties using pre-Vinson release of SCA or later, see Extend JavaScript Configuration Files.

SCA uses the configurationManifest.json to build the SuiteCommerce Configuration record’s user interface and display configurable properties. You can customize the metadata stored in the individual JSON files used to generate this manifest. For example, you can create custom modules to introduce new properties to the manifest or customize existing JSON files to change default values, modify the appearance or location of a property in the user interface, or change property options, etc.

Important

Never alter or delete the configurationManifest.json file. To make changes to property metadata, customize the individual JSON files only. When you deploy your site using the developer tools, these individual files and customizations concatenate into and update the configurationManifest.json file. For detailed information on how JSON configuration files affect the configurationManifest.json and the SuiteCommerce Configuration record, see Configure Properties.


You have two options for customizing the configurationManifest.json file:

  • Create a new property using a custom module

  • Customize existing property metada

Create a New Property

When creating a new property, you must create a custom module and include your changes in JSON format using the JSON Schema V4. You use this custom file to create new properties and any metadata determining their location and behavior in the SuiteCommerce Configuration record.

The following steps are required to create a new property:

  1. Create a custom module and any required files and subdirectories.

  2. Use JSON Schema V4 to declare any new properties and metadata to appear in the manifest.

  3. Deploy your changes to NetSuite.

See Create JSON Configuration Files for details.

Customize Existing Properties

To customize existing properties and their associated metadata, you must customize the individual source JSON configuration files using the Configuration Modification method. This allows any module to push changes to properties defined in the Configuration subdirectory of other modules. You can use this method to modify any existing JSON configuration file and add, replace, or remove metadata associated with any existing property. You can do so over any elements within in one JSON configuration file or organize changes across multiple custom modules. See Modify JSON Configuration Files for specific information and examples of the Configuration Modification method.

Extend JavaScript Configuration Files

This section applies to pre-Vinson implementations of SCA only. For details on how to configure properties using Vinson release of SCA or later, see Configure Properties.

SCA uses multiple configuration files to define configuration properties in pre-Vinson implementations of SCA. These properties are defined within JavaScript files as objects and properties. See Configure Properties for specific information on the configuration differences between implementations and the properties they define.

In general, you must modify the configuration files to change configuration properties of a module or to include new custom module dependencies within the application. When customizing configuration files, you must create a custom module that redefines the configuration properties you want to change. However, unlike other custom modules, you do not need to use the JavaScript prototype method to extend configuration properties. In general, the following steps are required to customize configuration files:

  1. Create a custom module.

  2. Include the JSON configuration file as a dependency.

  3. Redefine the configuration properties.

See Extend Frontend Configuration Files and Extend the Backend Configuration File for more specific information on how to perform these steps.

In situations where a configuration file defines an object containing properties, you should only redefine the specific property you want to change. You should avoid redefining the entire object. This helps ensure that there are no conflicts between your customizations and newer versions of SCA. For example, a newer version of SuiteCommerce Advance may add additional properties that would be overwritten if you redefine the entire object.

Before customizing configuration files, you should create a convention for customizing configuration files that makes sense for your development environment. For example, you may want to create a custom module for each configuration file. In this scenario, you extend all configuration properties of the SC.MyAccount.Configuration module within a single custom module.

In some situations, you may want to define a custom module for each individual configuration property you override. In this scenario, for example, you may have a module called PaymentWizardCustomConfiguration@1.0.0 where you define an override for the payment wizard configuration object of the SC.MyAccount.Configuration module.

Override Template Files

View a Related Video

When extending a template file, you must use the file override method provided by the developer tools. The primary reason for this requirement is that you cannot extend specific parts of a template. This means that all changes you make to a template file must be made in the same custom file that you create. See Override a Template File for an example of how to use the override method.

When making changes to a template, you must be aware of the properties and objects that are returned by the getContext() method of the template's view. The getContext() method can be seen as a contract that ensures that when migrating to a new version of SCA the same data is available to the template in the new version. For compatibility with previous versions, a new release of SCA includes the same properties and objects returned by the getContext() method.

New properties or objects may be included in new versions of SCA, but the existing properties and objects continue to available. This helps ensures that your template customizations work after migration because they will have access to the same data as the previous version.

If you need to expose your own properties or objects to the template, add them to the getContext() method by extending that method using the best practices outlined in Extend JavaScript.

Extend Style Sheets

SCA uses the Sass scripting language, which is transformed into CSS when you use the developer tools to compile and deploy the application. Sass files have a built-in mechanism for extending style definitions, by using the @extend keyword. This keyword enables you to add the styles of one selector to another one. This enables you to extend only a specific part of a style definition. See Design Hierarchy for information on working with Sass in SCA.

To extend a Sass file, you should create a custom module containing a Sass file. This file should only contain the style elements you want to extend as well as any new style elements you define.

Nesting

Although not a design pattern, keep the following in mind when reading and customizing Sass. SCA uses the ampersand symbol (&) as a nesting technique for classes. This can be handy to simplify your Sass.

For example, use the following Sass:

.my-class {
   &.my-other-class {}
}

This results in the following CSS:

.my-class.my-other-class {}
Developing Sass in a Local Environment

When you run the gulp local command, the Sass preprocessor compiles the CSS for your local site, certain naming conventions affect the various application style sheet files (shopping.css, myaccount.css, and checkout.css). Using the source map, the browser understands and relates your classes to the DOM with the classes defined at the file level during development. This means that, when using the browser developer tools in a local environment, you can easily search for classes the same way you would at the file level during development.

Override Language Files, Images, and Resource Files

When extending the following resources, you must use the file override method provided by the developer tools:

  • Languages files

  • Images

  • Resource files

The primary reason for this requirement is that these resources can only be customized at the file level. Each of these resources can only be overridden once. Therefore, make all changes to these resources within the same file.

Related Topics