Menu

Upgrade Major Versions of Adaptive.js

Follow the steps in this migration guide to switch between major versions of Adaptive.js.

When you migrate your Adaptive.js version, you gain access to:

An update to a minor version point release of Adaptive.js (for example, from 1.0.0 to 1.3.0) involves an update to your package.json file and a short reinstallation. By contrast, a major version upgrade (for example, from 0.3.x to 1.0.0) usually introduces changes that break your code. These major upgrades require you to also change your project code.

Upgrade to Adaptive.js v2.0 Follow the steps in the Upgrade to Adaptive.js v2.0 tutorial in the Adaptive.js v2.0 documentation.


Migrating from 0.3.x to 1.0.0

An update of Adaptive.js from version 0.3.x to 1.0.0 introduces some breaking changes. The most significant change is aimed at normalizing the definition of the adaptivejs/selectorEngine selector engine to the $ selector engine.

The adaptivejs/selectorEngine name provided a generic name for either jQuery or Zepto, whichever selector engine you chose for the project. This naming convention did not immediately convey what was being referenced. We removed the adaptivejs/selectorEngine name for clarity. Now when you reference a selector engine in your views and UI scripts, use the $ selector engine which is more consistent and understandable.

To migrate your current project from version 0.3.x to 1.0.0, follow these steps.


1. Upgrade your project from Adaptive.js 0.3.x to Adaptive.js 1.0.0

1. Launch an editor app. 2. From the root project folder, open the package.json file. 3. Change the adaptivejs version number to 1.0.0.

When you are finished, your code looks like the following snippet:

{
    "name": "your-site",
    "siteUrl": "http://www.your-site.com",
    "version": "0.0.1",
    "dependencies": {
        "adaptivejs": "1.0.0",
        "connect": "2.3.4",
        "grunt": "0.4.2",
        "grunt-concurrent": "0.4.3",
        "mocha": "1.14.0",
        "chai": "1.9.0",
        "grunt-contrib-sass": "0.7.3",
        "grunt-autoprefixer": "0.8.1",
        "nightwatch": "0.5.7",
        "nightwatch-commands": "0.0.10",
        "grunt-contrib-jshint": "0.10.0",
        "jshint": "2.5.0",
        "grunt-jscs-checker": "0.4.1",
        "mobify-code-style": "0.0.3"
  }
}

4. Open a new Terminal (Mac) or Command Prompt (Windows).

5. To change to your project directory, enter the following command on the command line :

cd path/to/project/directory

6. To update the project dependencies, enter the following command on the command line:

npm update

2. Update files in the adaptation directory

1. In the editor, from the adaptation folder, open the config.js file.

Version 1.0.0 has significantly simplified the adaptation/config.js file, which is the file used by require.js to build the adaptive.js script.

Compare and contrast the following two default adaptation/config.js files between version 0.3.x and 1.0.0:

0.3.x

require.config({
    'wrap': true,
    'baseUrl': '.',
    'keepBuildDir': true,
    'paths': {
        'adaptivejs': '../node_modules/adaptivejs/src',
        'buildConfig': '../build/buildConfig',
        'dust': '../node_modules/adaptivejs/lib/dust-requirejs',
        'dust-custom': '../node_modules/adaptivejs/lib/dustPatch',
        'dust-core': '../bower_components/dustjs-linkedin/dist/dust-core',
        'dust-full': '../bower_components/dustjs-linkedin/dist/dust-full',
        'translator': 'i18n/translator',
        'includes': 'views/includes',
        'libs': '../bower_components',
        'package': '../package.json',
        'resizeImages': '../bower_components/imageresize/resizeImages',
        'selectorLibrary': '../vendor/zepto',
    },
    'shim': {
        'dust-core': {
            'exports': 'dust'
        },
        'dust-full': {
            'exports': 'dust'
        },
        'selectorLibrary': {
            'exports': '$'
        }
    },
    // this ensures that dust-full does not get included in the build
    'stubModules': ['dust'],
    'exclude': ['dust-full']
});

1.0.0

require.config({
    'baseUrl': '.',
    'keepBuildDir': true,
    'paths': {
        'buildConfig': '../build/buildConfig',
        'translator': 'i18n/translator',
        'includes': 'views/includes',
        'libs': '../bower_components',
        'package': '../package.json',
        'resizeImages': '../bower_components/imageresize/resizeImages',
        'baseSelectorLibrary': '../vendor/zepto',
    },
    'shim': {
        'baseSelectorLibrary': {
            'exports': '$'
        }
    }
});

The most notable change here is the renaming of the selectorLibrary variable to the baseSelectorLibrary variable. Additionally, we abstracted away most of the other path and shim definitions which build behind the scenes.

2. In your editor app, in the config.js file, remove the configuration options that were in version 0.3.x.

At minimum, include the configuration options in 1.0.0. Change the selectorLibrary variable to be the baseSelectorLibrary variable.

3. From the adaptation folde, open the router.js file.

4. Replace the adaptivejs/selectorEngine reference to the $ convention.

Compare and contrast the two versions of the router.js file listing:

0.3.x

define([
    'adaptivejs/selectorEngine',
    'adaptivejs/router',
    'views/home'
],
function($, Router, Home) {
    var router = new Router();

    router
        .add(Router.selectorMatch('body.home'), Home)
        .add(Router.urlMatch('/foo'), Home)
        .add(Router.jsMatch(function() {return true;}), Home);

    return router;
});

1.0.0.

define([
    '$',
    'adaptivejs/router',
    'views/home'
],
function($, Router, Home) {
    var router = new Router();

    router
        .add(Router.selectorMatch('body.home'), Home)
        .add(Router.urlMatch('/foo'), Home)
        .add(Router.jsMatch(function() {return true;}), Home);

    return router;
});

4. From the adaptation/views folder, open all of your view JavaScript files. 5. Replace all of the adaptivejs/selectorEngine references with the $ reference.

Compare and contrast a sample listing of the base.js file between Adaptive.js versions:

0.3.x

define([
    'adaptivejs/selectorEngine',
    'resizeImages',
    'adaptivejs/utils',
    'adaptivejs/defaults',
    'includes/_header',
    'includes/_footer',
    'dust!templates/base',
    'settings'
],
function($, ResizeImages, Utils, Defaults, header, footer, template, Settings) {
    /* ... */
});

1.0.0.

define([
    '$',
    'resizeImages',
    'adaptivejs/utils',
    'adaptivejs/defaults',
    'includes/_header',
    'includes/_footer',
    'dust!templates/base',
    'settings'
],
function($, ResizeImages, Utils, Defaults, header, footer, template, Settings) {
    /* ... */
});

6. From the adaptation/views/includes folder, open all of your view includes JavaScript files. 7. Replace all of the adaptivejs/selectorEngine references with the $ reference.

Importance of the Selector Engine The additional reordering of the $ selector engine to the top of the define statements reinforces the importance of that library. This also changes the order of the parameters in the define callback.


3. Update the Files in the assets Directory

1. From the assets/js/ui, open the config.js file.

Compare and contrast the config.js files across the two Adaptive.js versions:

0.3.x

require.config({
    'paths': {
        // Paths needed to compile dust templates.
        'external': '../../../node_modules/adaptivejs/lib/external-requirejs',
        'dust': '../../../node_modules/adaptivejs/lib/dust-requirejs',
        'dust-full': '../../../bower_components/dustjs-linkedin/dist/dust-full',
        // Since dust is included in the adaptation, we remove them from the
        // UI build
        'dust-custom': 'empty:',
        'dust-core': 'empty:',

        'devicejs': '../../../bower_components/devicejs/lib/device.min'
    },
    'shim': {
        'dust-core': {
            'exports': 'dust'
        },
        'dust-full': {
            'exports': 'dust'
        }
    },
    // this ensures that dust-full does not get included in the build
    'stubModules': ['dust'],
    'exclude': ['dust-full']
});

1.0.0.

require.config({
    'paths': {
        'devicejs': '../../../bower_components/devicejs/lib/device.min'
    }
});

2. From the assets/js/ui/view-scripts, open all of your view scripts. 3. Change all of the external!adaptivejs/selectorEngine references to the $ selector engine.

Compare and contrast a sample assets/js/ui/view-scripts/home.js home view script between the two versions of Adaptive.js:

0.3.x

define([
    'external!adaptivejs/selectorEngine'
],
function($) {
    var homeUI = function() {
        // Add any scripts you would like to run on the home page only here
    };

    return homeUI;
});

1.0.0

define([
    '$'
],
function($) {
    var homeUI = function() {
        // Add any scripts you would like to run on the home page only here
    };

    return homeUI;
});

4. Update files in the tests directory

1. From the tests/runner directory, open the config.js file.

This is a static file.

2. Replace the code from the old version to the new version by copying and pasting the following config.js file listing:

0.3.x

require.config({
    baseUrl: '../../',
    paths: {
        'adaptivejs': 'node_modules/adaptivejs/src',
        'buildConfig': 'build/buildConfig',
        'chai': 'node_modules/chai/chai',
        'devSettings': '../devSettings',
        'documentFactory': 'node_modules/adaptivejs/lib/documentFactory',
        'dust': 'node_modules/adaptivejs/lib/dust-requirejs',
        'dust-custom': 'node_modules/adaptivejs/lib/dustPatch',
        'dust-core': '../bower_components/dustjs-linkedin/dist/dust-core',
        'dust-full': '../bower_components/dustjs-linkedin/dist/dust-full',
        'fixtures': 'tests/fixtures',
        'includes': 'adaptation/views/includes',
        'json': '../node_modules/adaptivejs/bower_components/requirejs-plugins/src/json',
        'mobifyjs': 'node_modules/adaptivejs/node_modules/mobifyjs/src',
        'mobifyjs/utils': 'node_modules/adaptivejs/node_modules/mobifyjs-utils/utils',
        'mocha': 'node_modules/mocha/mocha',
        'package': '../package.json',
        'resizeImages': '../bower_components/imageresize/resizeImages',
        'router': 'adaptation/router',
        'selectorLibrary': 'vendor/zepto',
        'settings': '../node_modules/adaptivejs/lib/settings',
        'templates': 'adaptation/templates',
        'text': '../node_modules/adaptivejs/bower_components/requirejs-plugins/lib/text',
        'views': 'adaptation/views',
        'viewMocker': 'node_modules/adaptivejs/lib/viewMocker',
        'utils': 'adaptation/utils'

    },
    'shim': {
        'mocha': {
            init: function() {
                this.mocha.setup('bdd');
                return this.mocha;
            }
        },
        'dust-core': {
            'exports': 'dust'
        },
        'dust-full': {
            'exports': 'dust'
        },
        'selectorLibrary': {
            'exports': '$'
        }
    }
});

1.0.0.

require.config({
    baseUrl: '../../',
    paths: {
        'adaptivejs': 'node_modules/adaptivejs/src',
        'buildConfig': 'build/buildConfig',
        'chai': 'node_modules/chai/chai',
        'devSettings': 'adaptation/devSettings',
        'documentFactory': 'node_modules/adaptivejs/lib/documentFactory',
        'dust': 'node_modules/adaptivejs/lib/dust-requirejs',
        'dust-custom': 'node_modules/adaptivejs/lib/dustPatch',
        'dust-core': '../bower_components/dustjs-linkedin/dist/dust-core',
        'dust-full': '../bower_components/dustjs-linkedin/dist/dust-full',
        'fixtures': 'tests/fixtures',
        'includes': 'adaptation/views/includes',
        'json': '../node_modules/adaptivejs/bower_components/requirejs-plugins/src/json',
        'mobifyjs': 'node_modules/adaptivejs/node_modules/mobifyjs/src',
        'mobifyjs/utils': 'node_modules/adaptivejs/node_modules/mobifyjs-utils/utils',
        'mocha': 'node_modules/mocha/mocha',
        'package': '../package.json',
        'resizeImages': '../bower_components/imageresize/resizeImages',
        'router': 'adaptation/router',
        'baseSelectorLibrary': 'vendor/zepto',
        '$': '../node_modules/adaptivejs/src/selectorLibrary',
        'settings': '../node_modules/adaptivejs/lib/settings',
        'templates': 'adaptation/templates',
        'text': '../node_modules/adaptivejs/bower_components/requirejs-plugins/lib/text',
        'views': 'adaptation/views',
        'viewMocker': 'node_modules/adaptivejs/lib/viewMocker',
        'utils': 'adaptation/utils'

    },
    'shim': {
        'mocha': {
            init: function() {
                this.mocha.setup('bdd');
                return this.mocha;
            }
        },
        'dust-core': {
            'exports': 'dust'
        },
        'dust-full': {
            'exports': 'dust'
        },
        'baseSelectorLibrary': {
            'exports': '$'
        }
    }
});

5. Test your Upgraded Project

Once you complete the previous steps, test your project.

grunt preview

Ensure that there are no errors during the build process.

Edit in GitHub