Table of contents
- 1. Example
MindTouch uses a simple, but powerful HTML composition model that makes it possible to embed rich content into wiki pages. By rich content, we mean CSS definitions, JavaScript inclusions, and code to be run once the document has loaded.
This is done by extension function by responding with an XML value that mimics a HTML document. For example, the following response would be processed according to MindTouch's HTML composition rules.
<html>
<head>
<script type="text/javascript" src="http://my-server/my-script.js" />
</head>
<body>
<div id="alerter">Click Me</div>
</body>
<tail>
<script type="text/javascript">
Deki.$("alerter").click(function() {
alert("you clicked");
});
</script>
</tail>
</html>
NOTE: MindTouch requires that the HTML response be wrapped in an XML value.
The HTML composition is done by appending all <head> elements from all HTML responses and discarding duplicates. This avoids loading the same javascript libraries over-and-over again. The same is done for the <tail> elements, except that they are further converted to be only executed once the document has been fully loaded in the browser. Finally, the contents of the <body> element are injected into the outer document replacing the function call-site.
In short, here are the steps that occur:
- append all elements inside the <head> element to the outer <head> element, unless such element has already been appended
- append all elements inside the <tail> element to the outer <tail> element, unless such element has already been appended
- replace the function invocation call-site with the contents of the <body> element
These few steps allow you to embed very rich content that may have dependencies on javascript and CSS files, without requiring the outer document to be aware of them ahead of time.
Example
Let's assume we have the following raw HTML that is being processed by MindTouch. The DekiScript call to function() returns the HTML described above.
<html>
<body>
This is plain content before.
{{ function() }}
This is plain content after.
</body>
</html>
First, we resolve the function call and embed the content returned, which leads to an invalid document by HTML specification. This is where the MindTouch HTML composition model kicks in.
<html>
<body>
This is plain content before.
<html>
<head>
<script type="text/javascript" src="http://my-server/my-script.js" />
</head>
<body>
<div id="alerter">Click Me</div>
</body>
<tail>
<script type="text/javascript">
Deki.$("alerter").click(function() {
alert("you clicked");
});
</script>
</tail>
</html>
This is plain content after.
</body>
</html>
When MindTouch detects that a HTML document is embedded into another HTML document, it replaces the entire <html>...</html> document with the contents of the contained <body> element. It also, moves the contents of the inner <head> and <tail> into the respective <head> and <tail> sections of the outer document. If the outer sections don't exist, they get created.
The outcome of the composition is the following (semi-)valid HTML:
<html>
<head>
<script type="text/javascript" src="http://my-server/my-script.js" />
</head>
<body>
This is plain content before.
<div id="alerter">Click Me</div>
This is plain content after.
</body>
<tail>
<script type="text/javascript">
Deki.$("alerter").click(function() {
alert("you clicked");
});
</script>
</tail>
</html>
- Tag page
- What links here
