There are several use cases for including large blocks of content into your applications.  A couple common scenarios are to include a basic help system or "About" information.  I'll cover three possible ways to do this today.[[MORE]]

Here's the HTML I'll use for illustration.  Note that it doesn't include any enyo kinds, only raw HTML.  If you want to include enyo, these solutions won't work for you.

<div class="help">
  <div class="topic">Getting Started</div>
  <div class="content">
    Here is a quick introduction to imported html into you enyo applications.  You can include <a href="http://developer.palm.com">links to external resources</a> or other random markup as you need.  Normally, you'd have much more content but this will do for illustration.
  </div>
</div>

The simplest solution for small blocks of content is the content property from Control (technically DomNodeBuilder) and its children.  Since it's a published property, you can interact with it in the same way as any other property -- either declaratively in the component definition or programmatically via setContent().  You can specify any valid HTML for content and it will be included as the innerHTML of the node.  One caveat here is that HTML is escaped by default; to include the raw HTML, set the allowHtml property to true.

{content:
'<div class="help">' +
'  <div class="topic">Getting Started</div>' +
'  <div class="content">' +
'    Here is a quick introduction to imported html into you enyo applications.  You can include <a href="http://developer.palm.com">links to external resources</a> or other random markup as you need.  Normally, you'd have much more content but this will do for illustration.' +
'  </div>' +
'</div>'}

That reasonably supportable for that length of text.  If, however, you had 10 topics, your enyo code would become untenable.  If the text is relatively static, at least static for a particular version of your application, the HtmlContent kind might be a good fit.

HtmlContent allows you to specify content inside your HTML document (as opposed to the JavaScript document containing your enyo components).  The content is referenced by specifying the id of the node wrapping it in the srcId property of HtmlContent.  One nice feature of HtmlContent you don't get in the other options is a special event handler for links.  So, in addition to "regular" links, you can encode special instructions in the href attribute of anchor tags to execute unique actions.

index.html

<!doctype html>
<html>
<head>
    <title>technisode example app</title>
    <script src="/dev/enyo/1.0/framework/enyo.js" type="text/javascript"></script>
</head>
<body>
<div id="helpContent">
    <div class="help">
      <div class="topic">Getting Started</div>
      <div class="content">
        Here is a quick introduction to imported html into you enyo applications.  You can include <a href="http://developer.palm.com">links to external resources</a> or other random markup as you need.  Normally, you'd have much more content but this will do for illustration.
      </div>
    </div>
</div>
<script type="text/javascript">
    new com.technisode.example.App().renderInto(document.body);
</script>
</body>
</html>

javascript

{kind:"HtmlContent", srcId:"helpContent", onLinkClick:"linkClicked"},

The third option is AjaxContent.  It functions similar to HtmlContent except that it loads the content asynchronously from an external file -- either remotely or locally.  With both the content property and the HtmlContent control, the DOM nodes are available as soon as they are created.  With AjaxContent, the nodes aren't available until the onContentChanged event fires.  Turns out that the DOM nodes aren't quite ready when onContentChanged fires; it fires 1 line earlier.  I assume the reason is to allow you to modify the content before it is inserted.  Regardless, if you want to find or traverse the HTML using DOM methods, you can't do so quite yet.

A simple solution is to wrap any DOM manipulation calls in an enyo.asynchMethod.  This will allow the current call stack to complete which includes inserting the content.  This method is illustrated in the complete example below.

{kind:"AjaxContent", name:"ajaxContent", allowHtml:true, url:"http://www.technisode.com/blog/helpContent.html", onContentChanged:"ajaxContentChanged"}

And finally, all together now ...

index.html

<!doctype html>
<html>
<head>
    <title>technisode example app</title>
    <script src="/dev/enyo/1.0/framework/enyo.js" type="text/javascript"></script>
</head>
<body>
<div id="helpContent">
    <div class="help">
      <div class="topic">Getting Started</div>
      <div class="content">
        Here is a quick introduction to imported html into you enyo applications.  You can include <a href="http://developer.palm.com">links to external resources</a> or other random markup as you need.  Normally, you'd have much more content but this will do for illustration.
      </div>
    </div>
</div>
<script type="text/javascript">
    new com.technisode.example.App().renderInto(document.body);
</script>
</body>
</html>

content.js

var _Example = {
    name:"com.technisode.example.App",
    kind:"Control",
    components:[
        {content:
            '<div class="help">' +
            '  <div class="topic">Getting Started</div>' +
            '  <div class="content">' +
            '    Here is a quick introduction to imported html into you enyo applications.  You can include <a href="http://developer.palm.com">links to external resources</a> or other random markup as you need.  Normally, you\'d have much more content but this will do for illustration.' +
            '  </div>' +
            '</div>'},
        {kind:"HtmlContent", srcId:"helpContent", onLinkClick:"linkClicked"},
        {kind:"AjaxContent", name:"ajaxContent", allowHtml:true, url:"http://www.technisode.com/blog/helpContent.html", onContentChanged:"ajaxContentChanged"}
    ],
    linkClicked:function(sender, url) {
        // simple pass-through
        window.open(url);
    },
    ajaxContentChanged:function(sender) {
        enyo.asyncMethod(this, function() {
            enyo.log("loading complete.  feel free to manipulate the content now", sender.content);
            sender.hasNode().querySelectorAll(".topic");  // for example
        });
    }
}

enyo.kind(_Example);