HTML Decor II
This page uses HTMLDecor.js so I'll use it to demonstrate.
Without HTMLDecor the page is just the HTML content of this article. You can see the undecorated page by appending a ?nodecor query to the page URL.
The decor is defined in a normal HTML file which is independent of this page and therefore can be modified without changing the HTML of this page.
HTMLDecor merges the decor into the undecorated page resulting in what you are viewing now.
Currently this isn't particularly impressive because the decor is very simple. But when I do get around to providing a more feature-rich decor I won't need to update this page at all. I could even give this page an expiry date of one year from now and still be able to update the decor at any time.
How it works
The merging principle for HTMLDecor is that the decor provides generic page layout, styles and meta-data, and the page provides content and, if necessary, more specific styles and meta-data.
In the merged
<head>, tags from the decor document are inserted
ahead of the existing tags from the page. This means that stylesheets from the decor
have lower priority. If there is a clash between the decor and the page then the decor
loses, so that
<meta> tags won't be
inserted if they already exist in the page.
Merging the page and decor
<body> sections is basically two steps:
- insert the complete content of the decor body into the start of the page body
- for each original node of the page body:
- if it is an element with
@id, and the
idmatches that of a target-element in the decor body, then move the element into the decor, replacing the target-element.
- otherwise, remove the node from the document.
- if it is an element with
<head> of this page looks like:
I've rearranged and removed some tags so only the relevant HTML is shown.
<head> <script src="/HTMLDecor.js"></script> <link rel="meeko-decor" type="text/html" href="/blog/decor.html" /> <title>HTML Decor II</title> <link rel="stylesheet" href="/nodecor.css" title="nodecor" /> </head>
Let's look at the
This line includes the HTMLDecor script in the page.
<link rel="meeko-decor" type="text/html" href="/blog/decor.html" />
This line links to the decor file. The HTMLDecor script looks for the first
<link> tag with
@rel="meeko-decor". The type of decor
file should be declared as
<title>HTML Decor II</title>
Because this page already has a title, the title from the decor document will be ignored.
<link rel="stylesheet" href="/nodecor.css" title="nodecor" />
Any stylesheet in the page, whether
<link rel="stylesheet" /> or
@title="nodecor" will be removed from the page when decor has been successfully loaded.
This allows some basic styles to be applied to the page in the case when decor can't be loaded, or if
scripting is disabled in the browser.
<body> of this page looks like:
<body> <div role="navigation"> <h1> <a href="/" title="Home">meekostuff.net</a> / <a href="/blog/">Blog</a> </h1> </div> <div role="main" id="main"> Main content here </div> </body>
There are two child-elements of the
<body>, but the first one has no
so it will be removed from the page, while the second child -
@id="main" - will be relocated
to where-ever the matching decor element is placed.
Although the first child is removed by HTMLDecor, it is not irrelevant - it will still be seen in browsers when scripting is disabled, and it is processed by search-engines. I would suggest providing links to the site and section of the site in which the page is located. This prevents search-engines, etc arriving at the page and finding it to be a dead-end.
To understand how scripts are handled, you need some insight into how decor documents are loaded. Firstly, the decor is fetched with XMLHttpRequest. Then there is some pre-processing to handle various issues (including the option to disable scripts). The decor HTML is written into an iframe (which takes care of HTML parsing). Lastly the decor is merged into the page.
Scripts within the page are not handled by HTMLDecor. The only consideration is how they interact with content, styles and scripts from the decor document.
Scripts in the decor document are handled by the following rules:
- if the
@deferthen it is disabled in the context of the decor document (that is, the decor iframe). Within a normal HTML page, the behavior of a
@srcis unaffected by
@defer, but with HTMLDecor these two attributes still disable the script in the context of the decor document.
- otherwise the script runs in the context of the decor document. This could facilitate modifying the decor in response to the browser, device, or even page URL.
- scripts that were disabled in the context of the decor document are enabled when inserted into the original page (as part of the decor).
Future articles will deal with tips and best-practises for using HTMLDecor.
HTMLDecor has a project page at github. The README page contains a few more details.
At this stage, installation involves downloading the HTMLDecor script from http://devel.meekostuff.net/HTMLDecor/0.9-devel/HTMLDecor.js.
HTMLDecor is available under MPL 2.0.
See the MPL 2.0 FAQ for your obligations if you intend to modify or distribute HTMLDecor or part thereof.