Custom Loaders

Whenever you inject a component using the component binding or a custom element, Footwork 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.

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.

Available Functions¶

A custom component loader is simply an object whose properties are any combination of the following functions:

getConfig¶

getConfig(name, callback)

Define this if: you want to supply configurations programmatically based on names, e.g., to implement a naming convention.

If declared, Footwork will call this function to obtain a configuration object for each component being instantiated.

To supply a configuration, call callback(componentConfig), where componentConfig is any object that can be understood by the loadComponent function on your loader or any other loader. The default loader simply supplies whatever object was registered using fw.components.register.

For example, a componentConfig like:
```
{
  template: 'someElementId',
  viewModel: { require: 'myModule' }
}
```
...can be understood and instantiated by the default loader.
You are not limited to supplying configuration objects in any standard format. You can supply arbitrary objects as long as your loadComponent function understands them.
If you do not want your loader to supply a configuration for the named component, then call callback(null). Footwork will then consult any other registered loaders in sequence, until one supplies a non-null value.

loadComponent¶

loadComponent(name, componentConfig, callback)

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, Footwork 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:
template - Required. An array of DOM nodes
createViewModel(params, componentInfo) - Optional. A function that will later be called to supply a viewmodel object for each instance of this component
If you do not want your loader to supply a viewmodel/template pair for the given parameters, then call callback(null). Footwork will then consult any other registered loaders in sequence, until one supplies a non-null value.

loadTemplate¶

loadTemplate(name, templateConfig, callback)

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). Footwork will then consult any other registered loaders in sequence, until one supplies a non-null value.

loadViewModel¶

loadViewModel(name, templateConfig, callback)

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). Footwork will then consult any other registered loaders in sequence, until one supplies a non-null value.

Registering custom component loaders¶

Footwork 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, fw.components.loaders is an array containing all the loaders currently enabled. By default, this array contains just one item: fw.components.defaultLoader. To add additional loaders, simply insert them into the fw.components.loaders array.

Controlling precedence¶

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.
fw.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.
fw.components.loaders.unshift(myHighPriorityLoader)

If required, you can remove fw.components.defaultLoader from the loaders array altogether.

Sequence of calls¶

The first time Footwork needs to construct a component with a given name, it:

Calls each of the registered loaders' getConfig functions in turn, until the first one supplies a non-null componentConfig.
Then, with this componentConfig object, calls each of the registered loaders' loadComponent functions in turn, until the first one supplies a non-null template/createViewModel pair.

When the default loader's loadComponent runs, it simultaneously:

Calls each of the registered loaders' loadTemplate functions in turn, until the first one supplies a non-null DOM array.
The default loader itself has a loadTemplate function that resolves a range of template configuration formats into DOM arrays.
Calls each of the registered loaders' loadViewModel functions in turn, until the first one supplies a non-null createViewModel function.
The default loader itself has a loadViewModel function that resolves a range of viewmodel configuration formats into createViewModel functions.

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 fw.components.loaders, you can control the priority order of different loading strategies.

Examples¶

A component loader that sets up naming conventions¶

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.
fw.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>

A component loader that loads external files using custom code¶

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:

fw.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.
        fw.components.defaultLoader.loadTemplate(name, markupString, callback);
      });
    } else {
      // Unrecognized config format. Let another loader handle it.
      callback(null);
    }
  }
};

// Register it
fw.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.
      fw.components.defaultLoader.loadViewModel(name, viewModelConstructor, callback);
    } else {
      // Unrecognized config format. Let another loader handle it.
      callback(null);
    }
  }
};

// Register it
fw.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.

Notes

Custom component loaders and custom elements

If you are using a component loader to fetch components by a naming convention, and are not registering your components using fw.components.register or fw.components.registerLocation, then those components will not automatically be usable as custom elements (because you haven't told Footwork that they even exist).

See: How to enable custom elements with names that don't correspond to explicitly registered components
Integrating with browserify

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 Footwork 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.

fw.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
```