Whenever you inject a component using the component binding or a custom element, Knockout fetches that component’s template and viewmodel using one or more component loaders. The job of a component loader is to asynchronously supply a template/viewmodel pair for any given component name.
The built-in default component loader, ko.components.defaultLoader, is based around a central “registry” of component definitions. It relies on you explicitly registering a configuration for each component before you can use that component.
Learn more about configuring and registering components with the default loader
The following functions read and write the default component loader’s registry:
The following functions work across the complete list of registered component loaders (not only the default loader):
Also, since ko.components.defaultLoader is a component loader, it implements the following standard component loader functions. You can invoke these directly, e.g., as part of your implementation of a custom loader:
For documentation on these standard component loader functions, see implementing a custom component loader.
You might want to implement a custom component loader if you want to use naming conventions, rather than explicit registration, to load components. Or, if you want to use a third-party “loader” library to fetch component viewmodels or templates from external locations.
A custom component loader is simply an object whose properties are any combination of the following functions:
Define this if: you want to supply configurations programmatically based on names, e.g., to implement a naming convention.
If declared, Knockout will call this function to obtain a configuration object for each component being instantiated.
Define this if: you want to take control over how component configurations are interpreted, e.g., if you do not want to use the standard viewModel/template pair format.
If declared, Knockout will call this function to convert a componentConfig object into a viewmodel/template pair.
To supply a viewmodel/template pair, call callback(result), where result is an object with the following properties:
If you do not want your loader to supply a viewmodel/template pair for the given parameters, then call callback(null). Knockout will then consult any other registered loaders in sequence, until one supplies a non-null value.
Define this if: you want to use custom logic to supply DOM nodes for a given template configuration (e.g., using an ajax request to fetch a template by URL).
The default component loader will call this function on any registered loaders that declare it, to convert the template part of a component configuration into an array of DOM nodes. The nodes are then cached and cloned for each instance of the component.
The templateConfig value is simply the template property from any componentConfig object. For example, it may contain "some markup" or {element:"someId"} or a custom format such as {loadFromUrl:"someUrl.html"}.
To supply an array of DOM nodes, call callback(domNodeArray).
If you do not want your loader to supply a template for the given parameters (e.g., because it does not recognize the configuration format), call callback(null). Knockout will then consult any other registered loaders in sequence, until one supplies a non-null value.
Define this if: you want to use custom logic to supply a viewmodel factory for a given viewmodel configuration (e.g., integrating with a third-party module loader or dependency injection system).
The default component loader will call this function on any registered loaders that declare it, to convert the viewModel part of a component configuration into a createViewModel factory function. The function is then cached and called for each new instance of the component that needs a viewmodel.
The viewModelConfig value is simply the viewModel property from any componentConfig object. For example, it may be a constructor function, or a custom format such as {myViewModelType:'Something',options:{}}.
To supply a createViewModel function, call callback(yourCreateViewModelFunction). The createViewModel function must accept parameters (params, componentInfo) and must synchronously return a new viewmodel instance each time it is called.
If you do not want your loader to supply a createViewModel function for the given parameters (e.g., because it does not recognize the configuration format), call callback(null). Knockout will then consult any other registered loaders in sequence, until one supplies a non-null value.
Knockout allows you to use multiple component loaders simultaneously. This is useful so that, for example, you can plug in loaders that implement different mechanisms (e.g., one might fetch templates from a backend server according to a naming convention; another might set up viewmodels using a dependency injection system) and have them work together.
So, ko.components.loaders is an array containing all the loaders currently enabled. By default, this array contains just one item: ko.components.defaultLoader. To add additional loaders, simply insert them into the ko.components.loaders array.
If you want your custom loader to take precedence over the default loader (so it gets the first opportunity to supply configuration/values), then add it to the beginning of the array. If you want the default loader to take precedence (so your custom loader is only called for components not explicitly registered), then add it to the end of the array.
Example:
// Adds myLowPriorityLoader to the end of the loaders array. // It runs after other loaders, only if none of them returned a value. ko.components.loaders.push(myLowPriorityLoader); // Adds myHighPriorityLoader to the beginning of the loaders array. // It runs before other loaders, getting the first chance to return values. ko.components.loaders.unshift(myHighPriorityLoader)
If required, you can remove ko.components.defaultLoader from the loaders array altogether.
The first time Knockout needs to construct a component with a given name, it:
When the default loader’s loadComponent runs, it simultaneously:
Custom loaders can plug into any part of this process, so you can take control over supplying configurations, interpreting configurations, supplying DOM nodes, or supplying viewmodel factory functions. By putting custom loaders into a chosen order inside ko.components.loaders, you can control the priority order of different loading strategies.
To implement a naming convention, your custom component loader only needs to implement getConfig. For example:
var namingConventionLoader = {
getConfig: function(name, callback) {
// 1. Viewmodels are classes corresponding to the component name.
// e.g., my-component maps to MyApp.MyComponentViewModel
// 2. Templates are in elements whose ID is the component name
// plus '-template'.
var viewModelConfig = MyApp[toPascalCase(name) + 'ViewModel'],
templateConfig = { element: name + '-template' };
callback({ viewModel: viewModelConfig, template: templateConfig });
}
};
function toPascalCase(dasherized) {
return dasherized.replace(/(^|-)([a-z])/g, function (g, m1, m2) { return m2.toUpperCase(); });
}
// Register it. Make it take priority over the default loader.
ko.components.loaders.unshift(namingConventionLoader);
Now this is registered, you can reference components with any name (without preregistering them), e.g.:
<div data-bind="component: 'my-component'"></div>
<!-- Declare template -->
<template id='my-component-template'>Hello World!</template>
<script>
// Declare viewmodel
window.MyApp = window.MyApp || {};
MyApp.MyComponentViewModel = function(params) {
// ...
}
</script>
If your custom loader implements loadTemplate and/or loadViewModel, then you can plug in custom code to the loading process. You can also use these functions to interpret custom configuration formats.
For example, you might want to enable configuration formats like the following:
ko.components.register('my-component', {
template: { fromUrl: 'file.html', maxCacheAge: 1234 },
viewModel: { viaLoader: '/path/myvm.js' }
});
… and you can do so using custom loaders.
The following custom loader will take care of loading templates configured with a fromUrl value:
var templateFromUrlLoader = {
loadTemplate: function(name, templateConfig, callback) {
if (templateConfig.fromUrl) {
// Uses jQuery's ajax facility to load the markup from a file
var fullUrl = '/templates/' + templateConfig.fromUrl + '?cacheAge=' + templateConfig.maxCacheAge;
$.get(fullUrl, function(markupString) {
// We need an array of DOM nodes, not a string.
// We can use the default loader to convert to the
// required format.
ko.components.defaultLoader.loadTemplate(name, markupString, callback);
});
} else {
// Unrecognized config format. Let another loader handle it.
callback(null);
}
}
};
// Register it
ko.components.loaders.unshift(templateFromUrlLoader);
… and the following custom loader will take care of loading viewmodels configured with a viaLoader value:
var viewModelCustomLoader = {
loadViewModel: function(name, viewModelConfig, callback) {
if (viewModelConfig.viaLoader) {
// You could use arbitrary logic, e.g., a third-party
// code loader, to asynchronously supply the constructor.
// For this example, just use a hard-coded constructor function.
var viewModelConstructor = function(params) {
this.prop1 = 123;
};
// We need a createViewModel function, not a plain constructor.
// We can use the default loader to convert to the
// required format.
ko.components.defaultLoader.loadViewModel(name, viewModelConstructor, callback);
} else {
// Unrecognized config format. Let another loader handle it.
callback(null);
}
}
};
// Register it
ko.components.loaders.unshift(viewModelCustomLoader);
If you prefer, you could combine templateFromUrlLoader and viewModelCustomLoader into a single loader by putting the loadTemplate and loadViewModel functions on a single object. However it’s quite nice to separate out these concerns, since their implementations are quite independent.
If you are using a component loader to fetch components by a naming convention, and are not registering your components using ko.components.register, then those components will not automatically be usable as custom elements (because you haven’t told Knockout that they even exist).
See: How to enable custom elements with names that don’t correspond to explicitly registered components
Browserify is a popular library for referencing JavaScript libraries with a Node-style synchronous require syntax. It’s often considered as an alternative to an AMD loader such as require.js. However Browserify solves a rather different problem: synchronous build-time reference resolution, rather than asynchronous runtime reference resolution as handled by AMD.
Since Browserify is a build-time tool, it doesn’t really need any special integration with KO components, and there’s no need to implement any kind of custom component loader to work with it. You can simply use Browserify’s require statements to grab instances of your component viewmodels, then explicitly register them, e.g.:
// Note that the following *only* works with Browserify - not with require.js,
// since it relies on require() returning synchronously.
ko.components.register('my-browserify-component', {
viewModel: require('myViewModel'),
template: require('fs').readFileSync(__dirname + '/my-template.html', 'utf8')
});
This uses the brfs Browserify plugin to automatically inline the .html file, so you would need to build the script file using a command similar to:
npm install brfs browserify -t brfs main.js > bundle.js
© Steven Sanderson, the Knockout.js team, and other contributors
Licensed under the MIT License.
http://knockoutjs.com/documentation/component-loaders.html