Add a Child View to a Composite View

This topic applies to

Applies to

SuiteCommerce Advanced

 

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. For more information about TypeScript, see TypeScript.


Important

Making changes to core JavaScript and TypeScript 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 a JavaScript or TypeScript source file, you should create a custom module that uses 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.

      • If implementing 2019.2 and later, create this directory in the Advanced directory. For example: SC_19.2_Live/Advanced/extensions

      • If implementing 2019.1 and earlier, create this directory in the Modules directory. For example: Modules/extensions

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

    • If implementing 2019.2 or later, name this file HeaderExtension.ts.

    • If implementing 2019.1 or earlier, name this file HeaderExtension.js.

  3. Define your custom module and dependencies by adding the following code to this file.

    This code defines the dependencies required by your custom module. If implementing SuiteCommerce 2019.1 or earlier, 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.

    JavaScript example:

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

    TypeScript example:

    ///<amd-module name="HeaderExtension"/> /// <reference path="../../../Commons/Utilities/JavaScript/GlobalDeclarations.d.ts" /> import * as _ from 'underscore'; import HeaderView = require('../../Header/JavaScript/Header.View'); import GlobalViewsMessagesView = require ('../../GlobalViews.Messages.View'); //Additional code goes here.;
  4. Add the mountToApp method to Header.Extension.js (or Header.Extension.ts) 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 to the Templates directory of your custom module.

      • If implementing 2019.2 and later, copy the header.tpl file from the Advanced/Header/Templates directory.

      • If implementing 2019.1 and earlier, copy the header.tpl file from the Modules/suitecommerce/Header/Templates directory.

    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.

      • If implementing 2019.2 and later:

        { "gulp": { "javascript": [ "JavaScript/*" ] , "templates": [ "Templates/*" ] }, "overrides": { "../Header/Templates/header.tpl": "Templates/header.tpl" } }
      • If implementing 2019.1 and earlier:

        { "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. This file is located in a different location, depending on your implementation:

    • If implementing 2019.2 and later, the distro.json file is located in the Advanced directory of the SCA source code. For example: SC_19.2_Live/Advanced/distro.json

    • If implementing 2019.1 and earlier, the distro.json file is 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.

    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. For more information about TypeScript, see TypeScript.


    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.