lockandload
Lockandload is a minimalist AMD-loader-compatible boilerplate to kickstart
your website/single-page-app.
Gzipped, the essential script content amounts to roughly 1KB of code.
Without compression it blows up to just under 2KB. Further minifying this
code does not result in any significant gains, it would just hinder
readability.
Features
- Less filling: 1KB of gzipped script content.
- Handminified to retain readable and maintainable code.
- It's so small, it can and should be inlined on your HTML page
(which is also one of the reasons to handminify it only).
- Because it is inlined, it is faster than all other loaders.
- Fully asynchronous script loader: AMD-compatible.
- Supports anonymous define() calls.
- Supports local require() calls (with one and two arguments).
- Supports implicit and explicit ['require'] dependencies.
- Does not support implicit nor explicit exports/module dependencies.
- Circular dependencies will silently hang in unresolved state
(or put differently: do not do that).
- No extra diagnostic code to minimise code weight and optimise loading speed.
- Mostly event driven, no polling timers except for the scss() helper
function.
- Standard supported dependencies:
require
and domready
. - Both high and low priority asynchronous loading of Javascript and CSS files.
- Leverages native browser speed for high priority loading (by getting out
of the way).
- Legacy support for $(...) jquery riddled synchronous code.
- Legacy support for loading synchronous Javascript.
- Single-page-app support using $$(...) page refresh callbacks.
- Supports IE10 and up and all other webbrowsers.
- No config file, means: no syntax to learn, no config file parser code.
- No module system: all needed functionality is included already because
it was/is so small, that writing a module system would take more code
than the source of all the added functionality.
Requirements
It runs inside any webbrowser environment (starting at IE10 and up).
Usage
Copy index.html
, main.js
, lastjs.js
and css/main.css
boilerplate
files to your own new website, and start adjusting them to taste.
The index.html
contains two <script>
sections. The first section
should not be preceded by any other <script>
tags and should be left
verbatim.
The second section should be placed at or close to the end of the <head>
,
and should not precede any direct <link type="stylesheet">
tags.
Inside this second section there is a clearly marked section that is
your configuration area.
Whenever this loader is updated, you can expect the first script section
to be able to be replaced as is, and in the second script section you
will be able to replace the first part, up till your configurable area.
Backward and forward compatibility will be retained within those constraints.
The basic structure of a page should be:
- html
- head
- Charset declaration.
- Inline
lockandload
master script. - High priority async external scripts.
- Viewport declaration.
- High priority CSS scripts.
<title>
.- All other tags that should go in the
<head>
. - Inline
lockandload
'headready' script.
- CSS scripts fullfilling a custom applied-style dependency.
- Low priority CSS scripts.
- Medium priority async Javascript scripts.
- Low priority async Javascript scripts.
- Low priority synchronous Javascript scripts.
- body
- All other inline scripts (if you must).
The index.html
file is a production-stripped version of annotated.html
.
Look at annotated.html
to understand the code and read additional
inline documentation. This index.html
file is not present in the git
source repository, it can only be found in the npm repository (or after running
npm run prepublish
).
API
Globally
-
define(id?, dependencies?, factory)
The standard AMD global
entrypoint.
To figure out module ids of all
the modules that you are trying to load, uncomment some debugging code
in the primary load script and inspect your console-pane in the browser.
Running define(1, dependencies, factory)
is a custom extension and is
the same as the traditional global require(dependencies, factory)
.
It is used in the existing scripts to avoid defining the global
require()
.
Locally
In the secondary lockandload
'headready' script; all path arguments
are used verbatim in <link href="path">
or <script src="path">
tags:
scss(id, path)
Loads additional ordered css files asynchronously; after the stylesheet
has been applied, it fulfills the id
dependency.css(path)
Loads additional low priority ordered css files asynchronously.js(path)
Loads additional low priority unordered Javascript files asynchronously.sjs(path)
Loads additional low priority ordered Javascript files sequentially
yet asynchronously (as a group).
Dealing with jQuery
In order to support legacy code that uses inline $(function(){...})
scattered
throughout pages, this loader allows you to use that construct even before
the jQuery library has been loaded,
and thus enables you to load jQuery in an asynchronous and non-blocking fashion.
The standard headready
script contains a dependency on domready
and
jquery
which then at the end runs domready()
which will run all the
registered delayed functions.
SPA (Single Page App) support
To ease SPA development, the loader defines a
$$(function(jquery_document){...})
function which registers functions
for execution on every SPA-controlled page refresh. The registered functions
receive a convenience argument $(document)
when executed.
To run the registered functions, one needs to make a call to the entrypoint
of the AMD-dependency on domready
.
E.g. in your application, you could use code like this:
!function(){
define("main", ["domready"], function (domready) {
function refreshpage() {
domready();
}
});
}();
References
Other loaders: