pml

Polymer Module Loader

PML is an implementation of the AMD specification. The primary goal of it is to play nice with HTML Imports. Based on IMD. Currently PML supports basic loading of dependencies, HTML imports will be implemented later.

How Do I?

Download and Include PML

PML is distributed as an HTML Import-able HTML file, naturally. Install and use like this:

Install:

> bower install panuhorsmalahti/PML --save

Or, with npm:

> npm install panuhorsmalahti/PML --save

Import:

<link rel="import" href="../pml/pml.html">

We recommend that HTML files that require or define do not directly import PML, but rather let the main page import PML, usually as the very first import. Since PML is fully AMD compliant, all modules defined in HTML imports will work just fine.

Define a Module

Modules are defined exactly as in other AMD systems like RequireJS: Public modules are defined by name:

Here's the definition of a mythical module, 'squidbits', that depends on the modules 'tentacles.html', 'ink' and 'jquery';

define('squidbits', ['./tentacles.html', 'ink', 'jquery'], function(tentacles, ink, $) {
  return {tentacles: tentacles, ink: ink, squidbits: true};
});

Now, since PML is targeted at projects already using HTML Imports, it's likely that the module will be defined inside an HTML file, like so:

<link rel="import" href="./tentacles.html">
<script src="ink.js"></script>
 
<script>
define('squidbits', ['./tentacles.html', 'ink', 'jquery'], function(tentacles, ink) {
  return {tentacles: tentacles, ink: ink, squidbits: true};
});
</script> 

Notice the <link> and <script> tags. These tell the browser to load 'tentacles.html' and 'ink.js'. Because scripts are blocked until imports and other scripts have loaded and run, and 'tentacles.html' and 'ink.js' define modules, squidbits's dependencies are guaranteed to be loaded and registered when the inline script runs.

Note also that the jquery dependency is loaded automatically wihtout a <script> tag.

Note that we're assuming that ink.js defines a ink module here, and tentacles.html defines an anonymous module.

Define Anonymous / Relative Modules

Private (relative) module names are inferred from the current import:

tentacles.html:

<script>
define(function() {
  return /* module contents */;
})
</script> 

This module is available at a relative URL, as shown in the above squidbits example. There can be only one anonymous module per HTML document.

If you want to use an existing anonymous module (say, something defined following the UMD pattern), give it a name with the as attribute on a <script> tag:

<script src="thingo.js" as="thingy"></script>

Configuration

You can call require.config to set configuration options. This should be done before loading anything dependencies.

require.config({
    // Dependencies are loaded from this path, e.g. /js/lib/..
    // Defaults to the location of the HTML page that loads PML.
    baseUrl: "js/lib",
    // Mapping from module id to the path of the module
    paths: {
      // In this case 'jquery' is loaded from /js/lib/jquery/dist/jquery.js
      jquery: "jquery/dist/jquery"
    }
});

Future work

HTML dependencies.

Imagine:

foo.html:

<template id="bar">...</template>

You could import a document: index.html:

define(['foo.html'], function(foo) {
  // foo is a document
  let bar = foo.querySelector('#bar');
  document.appendChild(document.importNode(bar.content));
})

Or a node directly: index.html:

define(['foo.html#bar'], function(bar) {
  // bar is a HTMLTemplate node!
  document.appendChild(document.importNode(bar.content));
})

What about ES6 (ES2015) Modules?

They're great. Really, we can't wait for them to be implemented natively in browsers. And until then, compilers and loaders like SystemJS and Babel do allow developers to use ES6 modules now, if they're willing to deal with a build step.

Not every project can or wishes to do so, and HTML Imports is not a JavaScript module definition system, so PML is an extremely lightweight way to use modules on top of imports.

When the ES6 module loader spec is further along, we will look into ways of integrating the two so that JavaScript can import HTML "modules" and vice-versa. We're very excited about the possibilities for interop.

There is a lot to explore with ES6 module loading and HTML Imports. The loading and ordering semantics appear to be fully compatible, and given a configurable enough loader we should be able to let ES6 modules import HTML nodes and vice-versa.