Best Practices for Customizing SCA

Important:

You should use the SCA developer tools only if you are customizing the Kilimanjaro release of SuiteCommerce Advanced (SCA) or earlier. If you are implementing the Aconcagua Release of SCA or later, the best practice is to use themes and extensions to customize your site unless your customization requires access to objects not available using the Extensibility API.

Follow these best practices when customizing or extending SuiteCommerce Advanced (SCA) with the SCA developer tools. These best practices help ensure that you can upgrade to more recent versions of SCA, even when you have changed or added features to the application. Following these best practices enables you to install new SCA versions to take advantage of current features and issue fixes.

Note:

The module source files for SuiteCommerce Advanced 2019.1 and earlier are JavaScript files with .js filename extensions. The module source files for SuiteCommerce Advanced 2019.2 and later are TypeScript files with .ts filename extensions. These implementations require experience working with TypeScript. For more information about TypeScript, see TypeScript.

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
Extend JavaScript
Customize the Configuration Manifest
Extend JavaScript Configuration Files
Override Template Files
Extend Style Sheets
Override Language Files, Images, and Resource Files

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.

If implementing 2020.1 and later, create a directory named extensions within the SC_<version> directory. Place all of your customizations in the extensions directory. For example:
```
              SC_20.1
      Advanced
      Backend
      Commons
      extensions
      gulp
   ... 

            
```
If implementing 2019.2, create a directory named extensions within the SC_<version>_Live directory. Place all of your customizations in the extensions directory. For example:
```
              SC_19.2_Live
      Advanced
      Backend
      Commons
      extensions
      gulp
   ... 

            
```

If implementing 2019.1 and earlier, place all customizations in an extensions directory within the Modules directory. For example:

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

In these example hierarchies, 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

NetSuite recommends that you use this convention 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.

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 issue 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 releases of SCA, see Extend JavaScript Configuration Files.

SCA uses the configurationManifest.json file 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 about 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 properties and their associated metadata

Create a New Property

When creating a new property, you must create a custom module and include your changes in JSON format using JSON Schema V4. You use this custom file to create new properties and add metadata to establish 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 new properties 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 method lets 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 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 about 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:

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 detailed information about 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 SCA 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 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

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 about 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.