ContentPane

A ContentPane is the most basic layout tile and it inherits directly from _Widget; conceptually, it is like a super-duper variation of an iframe except that it fits right into the page with all sorts of bells and whistles, not the least of which are the ability to render arbitrary snippets of HTML (not just full documents), reload content via XHR on demand, render widgets, and respect the page's theme. More often than not, a ContentPane is contained within another widget such as a TabContainer, although a ContentPane has several interesting uses cases on its own.

In its most generic usage, a layout pane does nothing special at all, as shown in Example 14-1.

Example 14-1. Creating a ContentPane in markup

<html>
    <head><title>Fun with ContentPane!</title>

        <link rel="stylesheet" type="text/css"
          href="http://o.aolcdn.com/dojo/1.1/dojo/resources/dojo.css" />
        <link rel="stylesheet" type="text/css"
          href="http://o.aolcdn.com/dojo/1.1/dijit/themes/tundra/tundra.css" />

        <script
            djConfig="parseOnLoad:true",
            type="text/javascript"
            src="http://o.aolcdn.com/dojo/1.1/dojo/dojo.xd.js">
        </script>

        <script type="text/javascript">
            dojo.require("dijit.layout.ContentPane");
        </script>

    </head>
    <body class="tundra">
        <div dojoType="dijit.layout.ContentPane">
            Nothing special going on here.
        </div>
    </body>
</html>

Tip

When browsing the source code or reading about Dojo online, you may notice that there is also a LinkPane dijit. Over the course of time, ContentPane evolved to absorb much of what LinkPane used to do, and it is likely that LinkPane will become deprecated because it offers a trivial amount of built-in functionality beyond that of ContentPane.

However, you can trivially fetch arbitrary content from a server and render it into the page by merely providing a reference to the server side URL. Suppose that a server-side URL called foo returns a snippet of text; you could use the ContentPane to display it like so:

<div id="foo" preload="false"  dojoType="dijit.layout.ContentPane" href="foo">

In this particular case, the foo URL might have returned just a simple string value, although it could have returned a widget that would have been automatically parsed and rendered into the page. Just note that the widget must already have been dojo.require'd into the page. For example, let's suppose the foo URL returned <div dojoType="dijit.form.Textarea"></div>, then by default, the dijit would be parsed and rendered into the page.

Table 14-3 presents a summary of everything that a ContentPane supports.

Table 14-3. ContentPane API

Name

Type

Comment

href

String

Used to designate the external data the pane should load.

extractContent

Boolean

If true, the visible content between the BODY tags of the document the ContentPane retrieves is extracted from it and placed into the pane. false by default.

parseOnLoad

Boolean

If true, any dijits returned in the data are automatically parsed and rendered. true by default.

preventCache

Boolean

Acts just like the preventCache parameter for a dojo.xhrGet. If true, an additional parameter is passed that changes with each request to prevent caching from occurring. false by default.

preload

Boolean

Used to force the pane to load content, even if it is not initially visible. (If the node is styled with display:none then content may not load unless preload is set to true.) false by default.

refereshOnShow

Boolean

Used to indicate whether the pane should reload every time the pane goes from a hidden state to a visible state. false by default.

loadingMessage

String

Defined in dijit.nls.loading. Provides a default message to the user while a load is in process. "Loading..." by default.

errorMessage

String

Defined in dijit.nls.loading. Provides a default message to the user when a load fails. "Sorry, an error occurred" by default.

isLoaded

Boolean

Used to provide an explicit status for whether content is loaded. Useful for inquiries involving content that is often refreshed.

refresh( )

Function

Used to force the content to refresh by downloading it again.

setHref(/*String*/ href)

Function

Used to change the location of the external content for the dijit. If preload is false, the content is not downloaded until the widget becomes visible again.

setContent(/*String | DOMNode | NodeList */data)

Function

Used to explicitly set local content for the pane.

cancel( )

Function

Cancels the in-progress download of content.

onLoad(/*Event*/evt)

Function

Extension point that is called after the load (and optional parsing of widgets) takes place.

onUnload(/*Event*/evt)

Function

Extension point that is called before existing content is cleared by a refresh, setHref, or setContent.

onDownloadStart

Function

Extension point that is called just before the download begins. By default, returns the string that is displayed as the loading message.

onContentError(/*Error*/ e)

Function

Extension point that is called when DOM errors occur. The string that is returned is what is displayed to the user.

onDownloadError(/*Error*/ e)

Function

Extension point that is called if an error occurs during the download. By default, returns the string that is displayed as the error message.

onDownloadEnd( )

Function

Extension point that is called when the download completes.

Given an existing node called foo, you could programmatically create a ContentPane like so:

Hacking ContentPane

One of the great things about a purely interpreted, highly dynamic language like JavaScript is that you can extend functionality as you need it on the fly. The discussion about fetching a dijit such as Textarea via a ContentPane cited that Textarea must first be required into the page. The natural tendency would be to dojo.require("dijit.form.Textarea") somewhere in the head of the page, and that probably covers most of the common cases. But what if you wanted to be able to have the server return to you any dijit to render in the ContentPane?

No problem—if the client is requesting a specific dijit, through the URL's query string perhaps, you could simply dojo.require it yourself, on the fly, before the request to update the ContentPane. If the server were returning you a dijit that you don't have knowledge of beforehand, then matters are a bit tricker, but not so tricky that you can't overcome. Simply set the ContentPane's parseOnLoad value to be false so that no automatic parsing occurs (resulting in an error since the corresponding dojo.require hasn't executed yet), and use the onLoad extension point to find the node, require it into the page, and parse it yourself.

Here's an example in markup:

<div dojoType="dijit.layout.ContentPane"
     href="bar" parseOnLoad="false">
     <script type="dojo/method" event="onLoad">
        dojo.query("[dojoType]", this.domNode)
        .forEach(function(x) {
          var _resource = dojo.attr(x, "dojoType");
          dojo.require(_resource);
            //don't parse till the module is loaded
            var _interval = setInterval(function() {
                 if (eval(_resource)) { //does the object exist?
                    clearInterval(_interval);
                    dojo.parser.parse(x.parentNode);
                 }
            }, 100);
         });
    </script>
</div>
var contentPane = new dijit.layout.ContentPane({ /* properties*/, "foo");
contentPane.startup(  ); //good practice to get in the habit of always calling startup

Because ContentPane is not a descendant of _Container, there are no built-in methods for adding children to a ContentPane. However, you can use a ContentPane's domNode reference to append another node inside of it using plain old JavaScript, which works just fine. For example, using the existing content pane from the previous example:

contentPane.domNode.appendChild(someOtherDijit.domNode);

Tip

You may be wondering why ContentPane does not directly support the interface provided by _Container. The unofficial answer is that a ContentPane, in general, does not need to perform a specific action when a child is placed into it for a specific reason. The reasons for adding children to a ContentPane are wide and varied. If you really wanted to, however, you could mixin or extend _Container into ContentPane.

Get Dojo: The Definitive Guide now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial