ocLazyLoad

Load modules on demand (lazy load) in AngularJS

Angular Core Dependency: >=1.2.0

Module License: MIT

Added by: Sam Deering

GitHub

Repository

ocombe/oclazyload

Stats

Stars: 2414

Watchers: 2414

Forks: 445

Module Description

ocLazyLoad Build Status

Load modules on demand (lazy load) in AngularJS

Table of contents

  1. Key features
  2. Usage
  3. Service
  4. Directive
  5. Dependency injection
  6. Configuration
  7. Router usage
  8. Other function
  9. Contribute
  10. FAQ

Key features

  • Dependencies are automatically loaded
  • Debugger friendly (no eval code)
  • The ability to mix normal boot and load on demand
  • Load via the service or the directive
  • Use the embedded async loader or use your own (requireJS, ...)
  • Load js (angular or not) / css / templates files
  • Compatible with AngularJS 1.2.x/1.3.x/1.4.x

Usage

  • Put ocLazyLoad.js into your project

  • Add the module oc.lazyLoad to your application (you can install it with bower install oclazyload or npm install oclazyload)

  • Load on demand: With $ocLazyLoad you can load angular modules, but if you want to load any component (controllers / services / filters / ...) without defining a new module it's entirely possible (just make sure that you define this component within an existing module).

There are multiple ways to use $ocLazyLoad to load your files, just choose the one that you prefer.

More examples / tutorials / articles

You can find three basic examples in the example folder. If you need more, check out these links:

Service

You can include $ocLazyLoad and use the function load which returns a promise. It supports a single dependency or multiple dependencies (array).

Load one or more modules & components with one file:

$ocLazyLoad.load('testModule.js');

Load one or more modules & components with multiple files:

$ocLazyLoad.load(['testModule.js', 'testModuleCtrl.js', 'testModuleService.js']);

Load one or more modules with multiple files and specify a type where necessary: Note: When using the requireJS style formatting (with js! at the beginning for example), do not specify a file extension. Use one or the other.

$ocLazyLoad.load([
   'testModule.js',
   {type: 'css', path: 'testModuleCtrl'},
   {type: 'html', path: 'testModuleCtrl.html'},
   {type: 'js', path: 'testModuleCtrl'},
   'js!testModuleService',
   'less!testModuleLessFile'
]);

You can load external libs (not angular):

$ocLazyLoad.load(['testModule.js', 'bower_components/bootstrap/dist/js/bootstrap.js', 'anotherModule.js']);

You can also load css and template files:

$ocLazyLoad.load([
    'bower_components/bootstrap/dist/js/bootstrap.js',
    'bower_components/bootstrap/dist/css/bootstrap.css',
    'partials/template1.html'
]);

If you want to load templates, the template file should be an html file with regular script templates. It looks like this:

<script type="text/ng-template" id="/tpl.html">
  Content of the template.
</script>

You can put more than one template script in your template file, just make sure that you use different ids:

<script type="text/ng-template" id="/tpl1.html">
  Content of the first template.
</script>

<script type="text/ng-template" id="/tpl2.html">
  Content of the second template.
</script>

There are two ways to define config options for the load function. You can use a second optional parameter that will define configs for all the modules that you will load, or you can define optional parameters to each module. For example, these are equivalent (except that the first two files won't be cached in the first example):

$ocLazyLoad.load([{
  files: ['testModule.js', 'bower_components/bootstrap/dist/js/bootstrap.js'],
  cache: false
},{
  files: ['anotherModule.js'],
  cache: true
}]);

And

$ocLazyLoad.load(
  ['testModule.js', 'bower_components/bootstrap/dist/js/bootstrap.js', 'anotherModule.js'],
  {cache: false}
);

If you load a template with the native template loader, you can use any parameter from the $http service (check: https://docs.angularjs.org/api/ng/service/$http#usage).

$ocLazyLoad.load(
    ['partials/template1.html', 'partials/template2.html'],
    {cache: false, timeout: 5000}
);

The existing parameters that you can use are cache, reconfig, rerun, serie and insertBefore. The parameter cache: false works for all native loaders (all requests are cached by default):

$ocLazyLoad.load({
    cache: false,
    files: ['testModule.js', 'bower_components/bootstrap/dist/js/bootstrap.js']
});

By default, if you reload a module, the config block won't be invoked again (because often it will lead to unexpected results). But if you really need to execute the config function again, use the parameter reconfig: true:

$ocLazyLoad.load({
    reconfig: true,
    files: ['testModule.js', 'bower_components/bootstrap/dist/js/bootstrap.js']
});

The same problem might happen with run blocks, use rerun: true to rerun the run blocks:

$ocLazyLoad.load({
    rerun: true,
    files: ['testModule.js', 'bower_components/bootstrap/dist/js/bootstrap.js']
});

By default the native loaders will load your files in parallel. If you need to load your files in serie, you can use serie: true:

$ocLazyLoad.load({
    serie: true,
    files: [
        'bower_components/angular-strap/dist/angular-strap.js',
        'bower_components/angular-strap/dist/angular-strap.tpl.js'
    ]
});

The files, by default, will be inserted before the last child of the head element. You can override this by using insertBefore: 'cssSelector' (it uses jQuery if available, or document.querySelector otherwise):

$ocLazyLoad.load({
    insertBefore: '#load_css_before',
    files: ['bower_components/bootstrap/dist/css/bootstrap.css']
});

Directive

The directive usage is very similar to the service. The main interest here is that the content will be included and compiled once your modules have been loaded. This means that you can use directives that will be lazy loaded inside the oc-lazy-load directive.

Use the same parameters as a service:

<div oc-lazy-load="{['js/testModule.js', 'partials/lazyLoadTemplate.html']}">
    // Use a directive from TestModule
    <test-directive></test-directive>
</div>

You can use variables to store parameters:

$scope.lazyLoadParams = [
    'js/testModule.js',
    'partials/lazyLoadTemplate.html'
];
<div oc-lazy-load="lazyLoadParams"></div>

Bonus: Use dependency injection

As a convenience you can also load dependencies by placing a module definition in the dependency injection block of your module. This will only work for lazy loaded modules:

angular.module('MyModule', ['pascalprecht.translate', {
  '/components/TestModule/TestModule.js',
  [
    '/components/bootstrap/css/bootstrap.css',
    '/components/bootstrap/js/bootstrap.js'
  ]
]);

Configuration

You can configure the service provider $ocLazyLoadProvider in the config function of your application:

angular.module('app').config(['$ocLazyLoadProvider', function($ocLazyLoadProvider) {
    $ocLazyLoadProvider.config({
        ...
    });
}]);

The options are:

  • debug: $ocLazyLoad returns a promise that can be rejected if there is an error. If you set debug to true, $ocLazyLoad will also log all errors to the console.

    $ocLazyLoadProvider.config({
        debug: true
    });
    
  • events: $ocLazyLoad can broadcast an event when you load a module, a component and a file (js/css/template). It is disabled by default, set events to true to activate it. The events are ocLazyLoad.moduleLoaded, ocLazyLoad.moduleReloaded, ocLazyLoad.componentLoaded, ocLazyLoad.fileLoaded.

    $ocLazyLoadProvider.config({
        events: true
    });
    
    $scope.$on('ocLazyLoad.moduleLoaded', function(e, module) {
        console.log('module loaded', module);
    });
    
  • modules: predefine the configuration of your modules for a later use. You will have to specify the name of the module here so that we can find the reference later.

    $ocLazyLoadProvider.config({
        modules: [{
            name: 'TestModule',
            files: ['js/TestModule.js']
        }]
    });
    
    $ocLazyLoad.load('TestModule');
    

Works well with your router

$ocLazyLoad works well with routers and especially ui-router. Since it returns a promise, use the resolve property to make sure that your components are loaded before the view is resolved:

$stateProvider.state('index', {
    url: "/", // root route
    views: {
        "lazyLoadView": {
            controller: 'AppCtrl', // This view will use AppCtrl loaded below in the resolve
            templateUrl: 'partials/main.html'
        }
    },
    resolve: { // Any property in resolve should return a promise and is executed before the view is loaded
        loadMyCtrl: ['$ocLazyLoad', function($ocLazyLoad) {
            // you can lazy load files for an existing module
             return $ocLazyLoad.load('js/AppCtrl.js');
        }]
    }
});

If you have nested views, make sure to include the resolve from the parent to load your components in the right order:

$stateProvider.state('parent', {
    url: "/",
    resolve: {
        loadMyService: ['$ocLazyLoad', function($ocLazyLoad) {
             return $ocLazyLoad.load('js/ServiceTest.js');
        }]
    }
})
.state('parent.child', {
    resolve: {
        test: ['loadMyService', '$ServiceTest', function(loadMyService, $ServiceTest) {
            // you can use your service
            $ServiceTest.doSomething();
        }]
    }
});

It also works for sibling resolves:

$stateProvider.state('index', {
    url: "/",
    resolve: {
        loadMyService: ['$ocLazyLoad', function($ocLazyLoad) {
             return $ocLazyLoad.load('js/ServiceTest.js');
        }],
        test: ['loadMyService', '$serviceTest', function(loadMyService, $serviceTest) {
            // you can use your service
            $serviceTest.doSomething();
        }]
    }
});

Of course, if you want to use the loaded files immediately, you don't need to define two resolves, you can also use the injector (it works anywhere, not just in the router):

$stateProvider.state('index', {
  url: "/",
  resolve: {
    loadMyService: ['$ocLazyLoad', '$injector', function($ocLazyLoad, $injector) {
      return $ocLazyLoad.load('js/ServiceTest.js').then(function() {
        var $serviceTest = $injector.get("$serviceTest");
        $serviceTest.doSomething();
      });
    }]
  }
});

Other functions

$ocLazyLoad provides a few other functions that might help you in a few specific cases:

  • setModuleConfig(moduleConfig): Lets you define a module config object

  • getModuleConfig(moduleName): Lets you get a module config object

  • getModules(): Returns the list of loaded modules

  • isLoaded('moduleName' or [modulesNames]): Lets you check if a module (or a list of modules) has been loaded into Angular or not

  • inject('moduleName' or [modulesNames]): if you load your files on your own (with RequireJS, SystemJS or else), you can call inject manually but you will have to provide the names of the modules that you are loading (unless you used toggleWatch before and after loading the files

  • toggleWatch(boolean): let ocLazyLoad know that it should monitor angular.module for new modules. Probably only useful if you use inject on your own. Don't forget to toggle it off after or it might lead to unexpected results

Contribute

If you want to get started and the docs are not enough, see the examples in the 'examples' folder!

If you want to contribute, it would be really awesome to add some tests, or more examples :)

FAQ

Do you have a plunkr I could use to open an issue ?

Yes, You can fork this one: http://plnkr.co/edit/n4DG0bbC14Mm1uccBptd?p=preview

Module stats last updated: 2017-03-25 15:00:01

Disclaimer: Some data on this page may have been gathered from the authors GitHub respository. If you see any mistakes or outdated information please let us know. Thanks!