Create a Custom Module

This topic applies to

Applies to

SuiteCommerce Advanced

SuiteCommerce Advanced (SCA) is designed so that you can extend it by creating new modules to add functionality specific to your web store. When creating a new module, be aware of the following requirements:

  • The top level directory of your module should have a directory of the format: module_name@x.y.z where module_name is the name of the module and x.y.z is the version number. See Organize Source Code for Custom Modules

  • The directory containing your custom module must be in the Modules directory. Modules shipped with SCA are stored in two sub-directories, suitecommerce and third_parties. NetSuite recommends creating a third sub-directory to store all custom module code. Examples in this document name this directory extension, as in Modules/extension/. However, you can name this directory any intuitive name as required.

  • Your new modules directory must have an ns.package.json file to define all of the module dependencies required by the developer tools. For more information, see Core SuiteCommerce Advanced Developer Tools for more information.

  • The module name must be unique. You cannot have duplicate module names, even when they reside in different folders.

  • You must update the distro.json file to ensure that your custom module is loaded into the application.

To add a custom module:

  1. Create a custom module within your custom directory with the format of ModuleName@version.

    For example, Modules/extensions/MyCustomModule@1.0.0.

    Important

    You cannot use existing module names, even when those modules reside in different folders.


  2. Create the subdirectories within the module.

    The exact subdirectory structure depends on the requirements of your module and your implementation of SCA. NetSuite recommends that you use the same directory structure as existing application modules. Typically, you will need JavaScript, Sass, SuiteScript, and Templates subdirectories.

  3. Create the necessary files for your module.

    This is where all of your modules logic is contained. At a minimum, you will need something like the following:

    Note

    This procedure does not include examples of backend models or services files which are often necessary for backend integration with NetSuite.


    • An entry point JavaScript file – this file acts as an entry point to the module and must return an object containing the mountToApp property that receives the application as a parameter.

      //MyNewModule.js define('MyNewModule' , [ 'MyNewModule.Router' ] , function ( Router ) { 'use strict'; return { mountToApp: function (application) { // Initializes the router return new Router(application); } }; });
    • A router – this file extends the Backbone router to map URL patterns to the views defined within the module.

      //MyNewModule.Router.js define('MyNewModule.Router' , [ 'MyNewModule.View' , 'Backbone' ] , function ( MyNewModuleView , Backbone ) { 'use strict'; //@class Address.Router @extend Backbone.Router return Backbone.Router.extend({ routes: { 'my-new-module': 'MyNewModuleRouter' } , initialize: function (application) { this.application = application; } // list myNewRouter output , MyNewModuleRouter: function () { var view = new MyNewModuleView({ application: this.application }) view.showContent(); } }); });
    • A view – this view is called from the router. Often, a view contains a getContext function that describes all of the variables that are passed from the view to the template.

      //MyNewModule.View.js define( 'MyNewModule.View' , [ 'my_new_module.tpl' , 'Backbone' , 'jQuery' ] , function ( MyNewModuleTemplate , Backbone , jQuery ) { 'use strict'; //@class Address.List.View List profile's addresses @extend Backbone.View return Backbone.View.extend({ template: MyNewModuleTemplate , events: { 'click [data-action="test"]': 'testAction' } , testAction: function () { alert("This is a test action") } , getContext: function () { return { //@property {String} myNewModuleContextVar myNewModuleContextVar: 'myVariable' }; } }); });
    • A template file – this file contains the markup used in combination with the views. Note that the SCA implementation leverages the Handlebars templating engine.

      <h2>This is my template file for my new module. It takes variables, {{myNewModuleContextVar}}, passed from the View.</h2>

      Important

      Template file names must be unique. You cannot have duplicate template file names even when they belong to different modules.


  4. If your custom module contains any configurable properties, you must include a Configuration subdirectory and place your Configuration Modifications here. See Modify JSON Configuration Files for details.

    Note

    This step only applies to Vinson implementations of SCA and later.


  5. Create a new ns.package.json file within the Modules directory.

    This file must contain entries for all of the directories required by the module. Use the following example as a template:

    { "gulp": { "javascript": [ "JavaScript/*.js" ] , "templates": [ "Templates/*.tpl" ] , "ssp-libraries": [ "SuiteScript/*.js" ] , "services.new": [ "SuiteScript/*.Service.ss" ] , "sass": [ "Sass/**/*.scss" ] } }
  6. Update the distro.json file in the root directory of the SCA source code.

    Update this file with the following two changes:

    • Add an entry for the new module in the modules object:

      { "name": "SuiteCommerce Advanced 1.0.0", "version": "1.0.0", "modules": { "suitecommerce/Account": "1.0.0", "extensions/myNewModule": "1.0.0", "suitecommerce/AjaxRequestsKiller": "1.0.0", "suitecommerce/ApplicationSkeleton": "1.0.0", ... }
    • Define any application dependencies in the javascript object.

      For example, if the module is required in the Shop Flow application, add the module to the SC.Shopping.Starter entrypoint.

      "javascript": [ { "entryPoint": "SC.Shopping.Starter", "exportFile": "shopping.js", "dependencies": [ "Backbone.View.Plugins", "jQuery.html", "ItemDetails", "myNewModule", ... "UrlHelper", "CMSadapter" ],
  7. View your changes.

    After creating your new module, you can test it by viewing your changes in the application. If you are running a local server, you can view your changes by reloading your website. See SCA on a Local Server for more information.

    If you are viewing your site in NetSuite, you can deploy your changes using the developer tools. See Deploy to NetSuite for more information.