Introduction

A common use case for DHTML/ajax is to fetch a fragment of html using XHR or some other way, and change the innerHTML of a div with that content. Problem with this is that it doesn't instanciate widgets and doesn't fire scripts. ContentPane was created to make widgets and scripts work and reduce the potential for memory leaks. ContentPane is a base widget for many (Html)widgets, it handles remote loading as well as local setting of content and instanciating widgets in that content. Think of it as islands in your page that can easily switch content using setContent() or setUrl().

Many other widgets inherits ContentPane, like Tooltip, Dialog, FloatingPane etc. That means that all the methods and properties of ContentPane also applies to them.

ContentPane is often used as children of Layout widgets like LayoutContainer, TabContainer, AccordionContainer

Dont misstake it for a Iframe though, It should not be used on very large html fragments.

Usage

Simple usage ... <div id="cpane" dojoType="contentPane" href="initialContent.html"><div> <a href="javascript:dojo.widget.byId('nextContent.html')">Goto nextPage</a> ...

Basic options

• loadingMessage Default: "Loading..." Set a custom loading message, see onDownloadStart to avoid showing this message completely
• adjustPaths Default: true When content is setUrl'ed from a different folder paths to images, links etc. is adjusted so the point to the correct dir
• href Default: "" Use this to grab initial content when contentpane is created.
• extractContent Default: true Only insert the html that is inside Script and style tags are not affected by this setting
• parseContent Default: true Create widgets inside content
• cacheContent Default: true Use dojo.io.bind javascript cache and, if it exists, browsers cache
• preload Default: false Lazyload switch, if true it will download content even if domNode is hidden Note: To make use of the default lazyload setting you need to hide your domNode Like this: <div dojoType="Dialog" style="display:none;"></div>
• bindArgs Default: {} Send in a custom setting to the dojo.io.bind call, like: mypane.bindArgs = {sync: true, preventCache: false}; mypane.seetUrl('nextHtmlFragment.html');
• refreshOnShow Default: false Re-download content each time ContentPane is shown again
• executeScripts Default: false Fire scripts in content Note: see scriptSeparation
• scriptSeparation Default: true Run scripts in a separete scope for ContentPane Note: set to false if you want similar behaviour as a normal pageload
• handler Default: "" Java function name, generate pane content
• isLoaded Default: false Tells wheather we are loaded or not, see also: onLoad() and addOnLoad()

Methods apart form those provided by ContentPane's superclass HtmlWidget

• setContent(String or DomNode) Use this instead of innerHTML
• setUrl(String or dojo.uri.Uri) Use this to set a new href and download and diplay that href
• refresh() Re-download and display href
• loadContents() Like refresh but only when isLoaded is false
• setHandler(Function) Set a function callback for javacontent generation
• abort() Abort a async download
• addOnLoad(Object, "functionname" or Function) Push a callback that will be run when content the next onLoad occurs. It's a fire and forget stack, if you want a callback each onLoad, see onLoad() Works for setContent as well
• addOnUnload(Object, "functionname" or Function) Same as addOnLoad but for onUnLoad event

Methods (Intended as event hooks using dojo.event.connect)

• onLoad() Called when everything rendered initialized and ready
• onUnload() Called before content is cleared
• onDownloadStart(e) preventDefault'able Called before a download occurs To prevent showing the loading message, do like this:
• onDownloadEnd(url, string) Called when download is completed, before it is setContent'ed
• onDownloadError(e) preventDefault'able Called when a load error occures, before The load error message is displayed. Prevent it the same way as onDownloadEnd Tip: During debug, you can display debug info like responseHeaders, responseText etc.
• onContentError(e) preventDefault'able Called when content insertion generates a error, before error mesage is displayed, like DOM faults, dojo.require() *syntax* faults etc.
• onExecError(e) Called when there is errors evaling script, doing java setContent and download errors of external scripts

In order to prevent the default messages you can do something like this:

<script>
	var myLoadMessage = {
		show: function(event){
			event.preventDefault();
			... custom code here
		}, 
		hide: function(){...}
	}

	dojo.addOnLoad(function(){
		var pane = dojo.widget.byId('myPaneId');
			dojo.event.connect(pane, "onDownloadStart", myLoadmessage, "show");
	});
</script>
<div dojoType="ContentPane" id="myPaneId">...startcontent...</div>

or

<div dojoType="ContentPane" 
	onDownloadStart="myLoadMessage.show(arguments[0]);">...startcontent...</div>
		

When used as a child to TabContainer, AccordionContainer or PageContainer TabContainer, AccordionContainer or PageContainer extends Widgets with these extra options

• label Tab text
• selected Preselect this tab after creation
• closable Display close button
Note:
• Height and width settings is done on the Container, not the ContentPane.
• In order for lazyload to work you have to hide your domNode initialy

When used as a child of LayoutContainer LayoutContainer package extends Widgets with this option

• layoutAlign "left", "right", "bottom", "top", or "client" see layout section of the book for more info

FAQ

• Why doesn't my widgets show up? Most likely you have used mypane.domNode.innerHTML = htmlstr; Use setContent instead: mypane.setContent(htmlstr);
• Why doesn't lazy load work? You have to hide your domNode, style="display:none;", initialy while creating ContentPane
• ContentPane displays strange looking characters when loaded remotly in some browsers, why? Like all server communication your browser need to know what charset your html is encoded with. Make sure your server is sending the correct Content-type header. example in php: header("Content-type: text/html; charset=utf-8"); Make sure you type utf-8 and not utf8, else IE will generate a warning and bail out.
• Why is ContentPane so slow? You probaly send it a big chunk of html with deeply nested tags.
  • Send it a html fragment, not a complete page with doctype and everything
  • Try to make the HTML simpler and use css for styling
  • Turn off the options you dont need: adjustPaths, extractContent, executeScripts, parseContent
  • Consider redesigning your page with serveral ContentPanes which grabs a smaller portion of your html that way you dont have to scan, render and create as many DomNodes/Widgets on each update.
  • Perhaps dojo.io.updateNode("nodeId", "myUrl") is all you need, and ContentPane is to heavy for your needs
• dojo.addOnLoad() is called to early, before my Content is loaded See onLoad event and addOnLoad for ContentPane, it is usualy easier to do this using <script>_container_.addOnLoad(..)</script> in your downloaded page, just be sure to set executeScripts=true
• My inline scripts doesnt work when loaded in ContentPane, I have turned executeScripts to true? Short answer: set scriptSeparation=false Long answer: ContentPane separates scope of scripts between different ContentPane's see: scriptScope page in dojo book
• When I press submit in my form inside a ContentPane, the whole page unloads, why? ContentPane doesn't have a form handling feature, look at dojo.widget.Form or see sample use case below