Using JavaScript in a Stencil Theme

Bundling and Minification

A small web application, such as a theme, can include rich user interactions that depend on many small JavaScript and CSS modules. If we were to embed each of the JavaScript modules in a template file with a separate <script> tag, the shopper’s browser would need to make separate HTTP requests to retrieve each module.

In some cases, it would take longer to set up the HTTP request than to download the small JavaScript module, leading to slower load times. On mobile devices, slow load times can be especially frustrating.

Bundling

To solve this problem Stencil, like other modern front-end frameworks, bundles all the JavaScript modules into a single file, allowing the shopper’s browser to make only a single HTTP request. After the browser has downloaded the bundle of JavaScript modules the browser caches them, speeding up the rest of the shopper’s session.

Minification

Beyond reducing the number of HTTP calls required to fetch all the required JavaScript modules, we can reduce the size of the individual JavaScript modules through minification. JavaScript minification removes white space and comments, shortens variable and function names, removes dead code, and more. The goal in all cases is to reduce the amount of bandwidth necessary to transmit the JavaScript module to the browser.

Options for Developers

When you add JavaScript to a theme, use one of the following techniques, so that Stencil will automatically bundle and minify your modules.

• Using npm: Add third-party JavaScript modules to your theme with npm where possible
• Place modules in assets/js/: For a JavaScript module that is not distributed via npm, add this module to your theme by creating a subdirectory within assets/js/ that contains your module
• Theme-specific JavaScript modules: Stencil themes include their own custom JavaScript modules for most page types. You can alter these page-type-specific modules by editing the files in assets/js/theme/.js*

These techniques are outlined in detail in the next sections.

Using npm

Many third-party JavaScript components are distributed with npm. When you use the npm command-line utility to add a JavaScript component to your theme, Stencil will automatically bundle and minify the component.

To enable this bundling and minification, run each module’s npm install command from the root directory of your theme (only for the module you want to add).

Taking over from npm

The npm package manager facilitates the management of third-party JavaScript components by placing each JavaScript component in the correct directories.

However, as a developer you will still need to edit your theme files to wire up the JavaScript component to expose it on your storefront.

Page types and JavaScript API

Stencil themes include an API for running JavaScript on a per-page basis. To properly write JavaScript for your theme, you will have the following page types available to you:

• account_orderstatus
• account_order
• account_addressbook
• shippingaddressform
• account_new_return
• add-wishlist
• account_recentitems
• account_downloaditem
• editaccount
• account_inbox
• account_saved_return
• account_returns
• account_paymentmethods
• account_addpaymentmethod
• account_editpaymentmethod
• login
• createaccount_thanks
• createaccount
• getnewpassword
• forgotpassword
• blog
• blog_post
• brand
• brands
• cart
• checkout
• category
• compare
• page_contact_form
• error
• 404
• giftcertificates
• giftcertificates_balance
• giftcertificates_redeem
• default
• page
• product
• amp_product_options
• search
• rss
• sitemap
• newsletter_subscribe
• wishlist
• wishlists

For further information, you can view a list of all the page types identified by app.js in Cornerstone.

These page types correspond to the pages within your theme. Each page type maps to an ES6 module that extends the base PageManager abstract class.

Example:

export default class Blog extends PageManager {
    constructor() {
        //Setup code goes here – attach to internals, and use internals as you would 'this'
    }
}

Note that the class name (“Blog”) is arbitrary. Mapping in the pageClasses object in assets/js/app.js is what determines which PageManager subclass will load on that page type.

Placing Modules in assets/js/

Developers can freely create subdirectories within assets/js/, to contain new JavaScript modules. The constraint is that all JavaScript files in each module must use the .js file extension.

In some advanced cases, it is possible to use other file types if you reconfigure webpack to transpile them. The blog below demonstrates how to reconfigure webpack to transpile .jsx files so that you can implement React code directly in the theme.

Create Custom BigCommerce Templates with React in Stencil

As a Solution Architect at BigCommerce, I meet clients and agencies who want to incorporate React into their Stencil theme. Maybe you want to utilize your existing component library, or React is just your preferred front-end framework.

Read More

Theme-Specific JavaScript Modules

In your theme’s assets/js/theme/ subdirectory, you will find a tree of JavaScript files.

Each file is a JavaScript module. Some modules are for specific page types. Others are common modules that can be used in other modules. Still, others are global modules that are available on every page.

Mapping Page Types to JavaScript Modules

To find the mapping from page types to modules in assets/js/theme/, examine the pageClasses object in the file:assets/js/app.js.

Each =>import(…) function within this class maps a page type to the entry module for that page type. For example, when the cart page type is loaded in the browser the JavaScript module at assets/theme/js/cart.js will be loaded.

Mapping example in app.js

Below is an excerpt of mappings from the Cornerstone base theme’s assets/js/app.js.

import Global from './theme/global';
const getAccount = () => import('./theme/account');
const getLogin = () => import('./theme/auth');
const noop = null;
const pageClasses = {
    account_orderstatus: getAccount,
    account_order: getAccount,
    account_addressbook: getAccount,
    shippingaddressform: getAccount,
    account_new_return: getAccount,
    'add-wishlist': () => import('./theme/wishlist'),
    account_recentitems: getAccount,
    account_downloaditem: getAccount,
    editaccount: getAccount,
    account_inbox: getAccount,
    account_saved_return: getAccount,
    account_returns: getAccount,
    account_paymentmethods: getAccount,
    account_addpaymentmethod: getAccount,
    account_editpaymentmethod: getAccount,
    login: getLogin,
    createaccount_thanks: getLogin,
    createaccount: getLogin,
    getnewpassword: getLogin,
    forgotpassword: getLogin,
    blog: noop,
    blog_post: noop,
    brand: () => import('./theme/brand'),
    brands: noop,
    cart: () => import('./theme/cart'),
    category: () => import('./theme/category'),
    compare: () => import('./theme/compare'),
    page_contact_form: () => import('./theme/contact-us'),
    error: noop,
    404: noop,
    giftcertificates: () => import('./theme/gift-certificate'),
    giftcertificates_balance: () => import('./theme/gift-certificate'),
    giftcertificates_redeem: () => import('./theme/gift-certificate'),
    default: noop,
    page: noop,
    product: () => import('./theme/product'),
    amp_product_options: () => import('./theme/product'),
    search: () => import('./theme/search'),
    rss: noop,
    sitemap: noop,
    newsletter_subscribe: noop,
    wishlist: () => import('./theme/wishlist'),
    wishlists: () => import('./theme/wishlist'),
};

Mapping example in cart.js

Inside the cart module (assets/js/theme/cart.js) other modules are imported, and custom JavaScript methods for the cart module are created for the Cart class.

Below is an excerpt from Cornerstone’s assets/js/theme/cart.js file. See the full code here.

import PageManager from './page-manager';
import _ from 'lodash';
import giftCertCheck from './common/gift-certificate-validator';
import utils from '@bigcommerce/stencil-utils';
import ShippingEstimator from './cart/shipping-estimator';
import { defaultModal } from './global/modal';
import swal from './global/sweet-alert';
export default class Cart extends PageManager {
    onReady() {
        this.$cartContent = $('[data-cart-content]');
        this.$cartMessages = $('[data-cart-status]');
        this.$cartTotals = $('[data-cart-totals]');
        this.$overlay = $('[data-cart] .loadingOverlay')
            .hide(); // Hide loading overlay until cart content is ready
        this.bindEvents();
    }
		cartUpdate($target) {
        const itemId = $target.data('cartItemid');
        const $el = $(`#qty-${itemId}`);
        const oldQty = parseInt($el.val(), 10);
        const maxQty = parseInt($el.data('quantityMax'), 10);
        const minQty = parseInt($el.data('quantityMin'), 10);
        const minError = $el.data('quantityMinError');
        const maxError = $el.data('quantityMaxError');
        const newQty = $target.data('action') === 'inc' ? oldQty + 1 : oldQty - 1;
        // Does not quality for min/max quantity
        if (newQty < minQty) {
            return swal({
                text: minError,
                type: 'error',
            });
        } else if (maxQty > 0 && newQty > maxQty) {
            return swal({
                text: maxError,
                type: 'error',
            });
        }

Mapping Custom Templates to JavaScript Modules

If you add custom page templates to your theme, you can edit the same assets/js/app.js file to map each custom template to an appropriate JavaScript module.

In order to successfully map your custom module to a custom template file, that file must do the following:

1. Inject the custom template
2. Load webpack
3. Load the main theme bundle
4. Load stencilBootstrap

In the following example, we will map a custom JavaScript file, assets/js/theme/custom.js to a custom product page file templates/pages/custom/product/customProd.html.

import PageManager from "./page-manager";
export default class Custom extends PageManager {
    onReady(){
        alert("Hello world!");
    }
}

This is a basic module that creates a class called Custom which extends the PageManager class.

The sample code below is the custom template that would live somewhere in templates/pages/custom/product/*.

{{~inject 'template' template}}
<h2>Hello World!</h2>
<body>
Some custom content!
<body>
<script>window.__webpack_public_path__ = "{{cdn 'assets/dist/'}}";</script>
<script src="{{cdn 'assets/dist/theme-bundle.main.js'}}"></script>
<script>window.stencilBootstrap("{{page_type}}", {{jsContext}}).load();</script>

It is a good idea to pull in {{>layout/base}} to your custom template file because of these requirements.

Finally, use the customClasses function in assets/js/app.js to map the custom page file to your custom template. Your app.js file should look like this:

const customClasses = {
    'pages/custom/product/customProd': () => import('./theme/custom'), // Mac/Linux
    'pages\\custom\\product\\customProd': () => import('./theme/custom'), // Windows
};
/**
 * This function gets added to the global window and then called
 * on page load with the current template loaded and JS Context passed in
 * @param pageType String
 * @param contextJSON
 * @returns {*}
 */
window.stencilBootstrap = function stencilBootstrap(pageType, contextJSON = null, loadGlobal = true) {
    const context = JSON.parse(contextJSON || '{}');
    return {
        load() {
            $(() => {
                // Load globals
                if (loadGlobal) {
                    Global.load(context);
                }
                const importPromises = [];
                // Find the appropriate page loader based on pageType
                const pageClassImporter = pageClasses[pageType];
                if (typeof pageClassImporter === 'function') {
                    importPromises.push(pageClassImporter());
                }
                // See if there is a page class default for a custom template
                const customTemplateImporter = customClasses[context.template];
                if (typeof customTemplateImporter === 'function') {
                    importPromises.push(customTemplateImporter());
                }
                // Wait for imports to resolve, then call load() on them
                Promise.all(importPromises).then(imports => {
                    imports.forEach(imported => {
                        imported.default.load(context);
                    });
                });
            });
        },
    };
};

Summary

To review, the basics of using JavaScript in your Stencil theme are:

• Stencil automatically bundles and minifies JavaScript modules to optimize page performance
• To insert custom JavaScript on a particular page in your theme, edit the JavaScript module that corresponds to the page’s type
• To add files from third-party JavaScript modules to a theme, use npm where possible
• To add JavaScript modules not distributed via npm, you can create new subdirectories within assets/js/
• Theme-Specific JavaScript modules are provided in the theme’s assets/js/theme/ subdirectory
• To find the mapping between modules in assets/js/theme/ and page types, examine the PageClasses object contained in assets/js/app.js
• You can map JavaScript modules to custom page templates by editing the assets/js/app.js file