You are here: Best Practices > JavaScript and jQuery > Upgrading the JavaScript Framework to v2

Upgrading the JavaScript Framework to v2


The JavaScript Framework is designed to allow customization of BigMachines applications in a way that is fast, unobtrusive, centralized, and easy to maintain. It is based around asynchronously loaded modules, and uses the RequireJS library to facilitate the loading of these files. It simplifies the code loading process, reduces the number of required files, and makes the latest version of RequireJS available for use.

Version 2 centralizes the logic for loading JavaScript by parsing a page and looking for identifying characteristics. All an engineer has to do is identify a page that they want to load, and then the framework will take care of the rest. The Framework Upgrade Kit is attached to this article.

Version 1 of the framework required code to be written in HTML attributes in Config and Commerce, and also called for a Util library to load code. Version 2, on the other hand, limits the writing of code to two places:

  1. The Header/Footer - a simple script tag to include the bm-framework.js file
  2. The File Manager “javascript” folder - the single source of all javascript files.

There is also a file that can be loaded into the Homepage Alternate JavaScript file. The purpose of this file is to improve performance when loading code on the homepage, and it is entirely optional.


These instructions apply to upgrading Version 1 of the Framework to Version 2. To install a fresh version of the framework, see the JavaScript Framework Starter Guide.

  1. Upload New Files.
    1. The framework upgrade file is available here and includes the following files:
  2. Upload these file into the javascript folder in the file manager (lower case, no spaces). allplugins-require.js and return_to_quote_button.js will both replace existing files.
    1. After you upload these files, the existing framework will be nullified, and all existing scripts will no longer be loaded.*
  3. Navigate from Admin Home Page > Styles and Templates > Header and Footer
  4. Modify the header to include the following line:

    <script type="text/javascript" src="$BASE_PATH$/javascript/bm-framework.js"></script>

  5. Modify bm-framework.js. At the top of you the bm-framework file, you'll find a short configuration section:


    * This is the setup section of the BigMachines JavaScript Framework.

    * Set "active" to true for any pages that you want to customize with Javascript

    * Then write your code in the corresponding file in the File Manager


    * For instance, if I set homepage:true then the code in homepage.js will be loaded

    * when I view the BigMachines homepage.


    setup.pages = {

    homepage: {



    commerce: {


    } // and so on...

    // [...]

  6. Per the instructions in the comment, set the “active” flag to true for every section of the site that you wish to load code. The framework will take care of the rest.
  7. Remove References to the Old Framework.
    1. The previous two steps are enough to get Version 2 of the framework up and running, while disabling all the functionality from Version 1. The next step is to remove the now-dormant code left over from Version 1 of the framework.
  8. Upgrade the HTML file.To this end, the upgrade HTML file will be an aid in identifying locations on the site that still reference the old framework.
  9. Click on it's link in the file manager. This will open a self-contained tool designed to crawl the BigMachines site and identify instances of the old framework.
    1. When you click “Run all Tests,” the tool will do it's work. Any issues will show up in red or yellow; follow the “Related URL” link to see what failed for a given test.
      Some tests have dependencies - ie, the config tests won't run until the Header/Footer tests have passed. If you want to ignore these dependencies, click the “Fake It” link next to the list of dependencies in the test you would like to run.
  10. The upgrade.html tool will assist in identifying a number of common locations of the old framework, including Homepage Alt JS.
  11. The homepage alternate JavaScript file (found under Admin > Home Page > XSL Templates ) had a mandatory function written in for version 1. It looked like this:


    * BigMachines standard JS Module loading

    * Michael Wheeler 02/01/2011


    * Builds a script tag referencing allplugins-require.js in the file manager, and appends the tag to the header.


    (function() {

    function include_homepage_js() {


    * Assumes that the sitename in $BASE_PATH$ is also

    * the Host Name of the company


    var sitename = _BM_HOST_COMPANY;


    if(sitename !== undefined) {

    var script_tag = document.createElement("script");









  12. This section of code can be removed entirely. You can replace it with the following code, which is simply used to assist the framework in identifying the homepage a few milliseconds faster:


    * BigMachines framework parameter

    * This optional parameter helps the javascript framework to identify this page


    window["framework/homepage"] = true;

  13. This file is available in the attachment found on this page, named “HomepageAltJs.js”.
  14. Require _javascript BML Util Library.
    1. Version 1 of the Framework used a BML Library to add JavaScript references to config and commerce. To completely remove the old framework from a site, you will need to delete this Util Library, as well as any code that references it. Notice that Version 2 of the framework does not depend on any HTML attributes - you can entirely remove any HTML/Read Only attributes that exist in order to load the old framework files.
  15. You can remove any references to allplugins-require.js from the header and footer of the site.
  16. You may also find a few references to allplugins-require.js in the default value for the HTML/Read Only Attributes in config. Any of these attributes can also be removed entirely from the site.
  17. Test It!
    1. Remember to walk through the relevant sections of the site and make sure that your code is loading properly. Use Firebug or other Developer tools to verify that the code is loading and running as expected



Related Topics Link IconSee Also