Add a Child View to a Composite View

This topic applies to

Applies to

SuiteCommerce Advanced

Important

Making changes to core JavaScript source files or changing any vital functionality of the application can make migrating to future releases difficult. Before making changes to SuiteCommerce Advanced (SCA), see Best Practices for Customizing SuiteCommerce Advanced.


Adding a child view to a parent view is a common way of extending the functionality of SCA. For example, you can easily add a message to a page by adding a GlobalViews.Message.View view as a child view. Adding a child view requires making two types of changes to the SCA source code:

  • Extend the childViews object of a view. Since this requires a change to the JavaScript, you should create a custom module that uses JavaScript prototyping to add the child view.

  • Override the template file. In addition to adding the view to the childViews object, you must also edit the HTML template to implement the child view in a page.

Note

Since a template file can only be overridden once, you may want to define the override in a different custom module created specifically for template overrides when making your own customizations. See Override a Template File for more information.


To extend the childViews object of a view:

  1. Create the directory structure for your custom module.

    1. Create a directory called extensions within the Modules directory.

    2. In the extensions directory, create a subdirectory called HeaderExtension@1.0.0.

    3. In the HeaderExtension directory, create a subdirectory called JavaScript.

    4. Also in the HeaderExtension directory, create another subdirectory called Templates.

    In general, when performing your own customizations you should create a directory structure similar to the above procedure. See Organize Source Code for Custom Modules for more information.

  2. Create a new JavaScript file called HeaderExtension.js.

  3. Define your custom module and dependencies by adding the following code to HeaderExtension.js:

    define('HeaderExtension'
    ,   [  
            'underscore'
        ,   'Header.View'
        ,   'GlobalViews.Message.View'
        ]
    ,   function (
            _
        ,   HeaderView
        ,   GlobalViewsMessageView
        )
    {
       'use strict';
    
          //Additional code goes here.
    
    });

    This code defines the dependencies required by your custom module. See Asynchronous Module Definitions (AMD) and RequireJS for information on defining dependencies within a module. This module includes the following views as dependencies:

    • Header.View – is required to extend the childViews object.

    • GlobalViews.Message.View – is required to add a message view to the application header.

  4. Add the mountToApp method to Header.Extension.js as shown in the following:

    return  {
    
          mountToApp: function (application)
      {
    
        HeaderView.prototype.childViews.HeaderExtension = function()
        {
           return new GlobalViewsMessageView({
              message: 'Hello World! - This is an Example of a GlobalMessageView!'
                ,   type: 'success'
                       ,   closable: true
                  });            
        }
      }
    }
    

    This code performs the following:

    • Specifies a return statement that returns the mountToApp method. This method is required to load a module into the application.

    • Extends the childViews object of the Header.View module using JavaScript prototyping.

  5. Copy the original template file to your custom module.

    1. Copy the header.tpl file from the Modules/suite_commerce/Header/Templates directory to the Templates directory of your custom module.

    2. Edit the custom template file by adding the following HTML code:

      <div data-view="HeaderExtension"</div>

      Add the HTML code at a place in the template where it will be displayed in the Header view. For example, you can add it directly above the <div class="header-menu-cart"> tag.

  6. Create the ns.package.json file

    1. Create a file called ns.package.json in the HeaderExtension directory.

    2. Add the following to the ns.package.json file:

      {
            "gulp": {
               "javascript": [
                  "JavaScript/*"
               ]
            ,   "templates": [
                  "Templates/*"
                ]
           },
                  "overrides": {
                     "suitecommerce/Header@1.1.0/Templates/header.tpl": "Templates/header.tpl"
            }
      }
  7. Add an entry for your module to the distro.json file located in the root directory of the SCA source code.

    You must add your custom view to the javascript object within the distro.json file. Your code should look similar to the following:

    "javascript": [
       {
             "entryPoint": "SC.Shopping.Starter",
          "exportFile": "shopping.js",
          "dependencies": [
                "Header.Extension.View",
             "Backbone.View.Plugins",
             "jQuery.html",
             "ItemDetails",
                      ...
    

    In this example, we are only customizing a single file, so we only add the Header.Extension module to the javascript object. In cases where you are customizing or overriding an entire application module, you may need to add the application module name here.

  8. View your changes.

    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.