WSGI Overlay
This library is meant as a kind of macro templating system. It is by no means a complete templating system. You do not hook this up to your framework and pass in objects. This does not even attempt to transform markup. This library is for composing HTML output from many sources into a single rendered page. This library is meant to bring down some of the barriers to a heterogeneous backend.
What It Is Like
This library bears a great deal of similarity to server-side includes. In some ways it is more primitive, in some ways more powerful. It is HTML aware.
This also bears some similarity to HTML Overlays, and comes from some of the previous thinking I had done on that.
The basic idea is that you have a master template, and a set of overlays onto that template. In the original form, overlapping id attributes identified the overlays. In this model, slots are explicitly labeled, and content intended to go in a slot is explicitly labeled.
The relationship between resources is also a bit richer. There are a few types of pages:
- The content page:
- This is the page the user actually requested. This is the most authoritative page. The <title> comes from this page.
- The template pages:
- The content page identifies its template. The template itself can use a template, so there can be a chain leading from the content page.
- Included pages:
- These are pages included by any other page. The output from the page is integrated into the including page.
- Merged pages:
- These pages are explicitly brought in, but the markup is not inserted into a particular position. Instead the markup is fully merged into the page. Where a content page pushes its content into a template, these pages have had their content pulled in, but the mechanics are equivalent.
There are several bits of markup to do these compositions:
- over-name="a b c":
- This names an element's content. Element content can have multiple (space-separated) names. Note that the content of the element is named, the element itself is not directly accessible.
- over-content="a b c":
- This replaces the content of the tag with the named element. The names are tried in order. The name default means to leave the original content in; thus the original content can be a fallback.
- over-replace="a b c":
- This removes the tag and replaces it with the named element. With over-content the original tag remains and its content changes; with over-replace the original tag is eliminated.
- over-include="uri#id":
- This fetches the document-relative URI. The content id is inserted. If the id is not given as a fragment, the entire page is included. If the page includes a <head> element, the head is merged. If it includes a <body> element and no specific id was given, then the content of the body will be used. If no id is given and no <body> is present, then the entire document will be used.
- <link rel="over-template" href="...">:
- This uses the given document as a template for this page. This is typically only done for a content page; it is ignored in other pages.
- <link rel="over-content" href="...">:
- This fetches the document-relative URI and merges all the content into this page. Basically it makes the content accessible for the over-content and over-replace commands.
At this time, URLs are not adjusted, so only absolute URLs should be used. Maybe later URLs will be adjusted in known attributes (like href and src).
Each time content is brought in, the <head> of the content is merged. <title> is drawn only from the original document, as are the <meta> tags that cannot be repeated. The <link rel="wsgi*"> tags are not merged, as they are immediately interpreted. Other tags -- specifically other links, script, and style tags -- are merged into a single head.
Stages
The rendering of a final page takes place in stages:
- The first stage brings in all the prerequesite pages, and creates a structure from these pages. Thus <link>, over-include, and are all interpreted during this stage.
- Named elements are all found, but nothing is done with them.
- The second stage renders the actual output. over-content and over-replace are implemented.
- Any tags or attributes used for this system are removed from the final output.