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:
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:
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:
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:
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.
prototype function, you can extend a specific property, object, or method without having to extend or override an entire model or view.
See Add a Child View to a Composite View for an example of how to implement prototyping.
Customize the Configuration Manifest
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.
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
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:
Create a custom module and any required files and subdirectories.
Use JSON Schema V4 to declare any new properties and metadata to appear in the manifest.
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.
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.
Create a custom module.
Include the JSON configuration file as a dependency.
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
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
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.
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:
This results in the following CSS:
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:
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.