Include  

home > documentation > Reference > JavaScript API > Include
Save & Share  Subscribe

 
 
// summary:
//	The include functionality allow developers to construct modular applications.
//	Pieces of the application can defined in separate files or requests and then 
//	pulled them together on the client-side. Client-side includes can be both good
//	and bad.  Good in allow developers to componentize applications and bad in the 
//	fact that multiple requests will be made to build the applications.
//	Developers should minimize the use of includes during application startup and rely
//	on includes to build the application on an as-needed basis.  This will maximize
//	the effectiveness of the include functionality.
//
//	<strong>What are we trying to achieve with include?</strong>
//	We are trying to let people include piece of content into the existing HTML DOM.
//	The content can be plain HTML or Dojo Component.
//		
//	This will allow developers to control the location of where the content goes and
//	how the content is included.
//	Why is this different from other functionality that seems to do the same thing?
//	1.) The other mechanisms for including the content <script type="dojoe/xml" src=""/>
//	and the process functions (processDocument...) require the content to contain all
//	the supporting markup syntax. For example to get the aforementioned ways to work 
//	you will need to supply the following.
//		
//	<outertag>
//		<declarations | ui | ...>
//			<!-- my content goes here -->
//
//	In this scenario it is very hard to reuse content as it contains the exact 
//	operations for how the content is included. <append query="myDiv">...
//	developers can't parameterize the content that is in the files unless they 
//	use a server-side mechanism.
//
//	2.)All the above mechanisms are declarative and offer no programmattic way to 
//	perform the same functionality.
//
// example:
//
//	Include functionality can be called programatically using the following functions.
//	dojoe.includeString();
//	dojoe.includeDocument();
//	dojoe.includeRequest();
//
//	Include functionality can be called declaratively using the following Markup.
//	<dojoe.Include src="" query="" blendMode=""/>
//	<dojoe.Include query="" blendMode="">
//		<tr><td class=cnTableBody>$1000.21</td><
//	</dojoe.Include>
//	The markup can be included in <declarations>, <dojoe.Macros>, or inside of
//	the UI block.  Using a <dojoe.Include/> tag inside of the UI will require
//	including the query and blendMode attributes, these attribute will NOT be
//	inferred from the location of the include <dojoe.Include/> tag. As mentioned
//	above using <dojoe.Include/> in the <ui> or <declarations> block should be
//	be used sparingly.
//		
dojo.mixin(dojoe, {
	includeDocument: function(/*XML Doc*/doc, /*String*/query, /*String*/blendMode) {
	// 	summary:
	//     	Takes an XML document and blends it into the HTML DOM. 
	// 	doc:
	//     	Native XML document to be processed.
 	// 	query:
	//     	An HTML node or query that the processor can use as reference for
	//     	output placement. For example, the processor
	//     	can replace this node with some output, or create a sibling
	//     	of this node.
	//	blendMode:
	//	This parameter controls how the content is "mixed" into the HTML DOM.
	//	You can use any of the following xModify operations to specify how the
	//	inclusion will occur.
	//	append, replace, replace-children, prepend, insert-before, insert-after.
	//
	},
 
	includeString: function(/*String*/xmlStr, /*String*/query, /*String*/blendMode){
	// 	summary:
	//     	Blends a string that represents a DOM into the HTML DOM. 
	// 	xmlStr:
	//     	A string that is a valid XML document.
	// 	query:
	//     	An HTML node or query that the processor can use as reference for
	//     	output placement. For example, the processor
	//     	can replace this node with some output, or create a sibling
	//     	of this node.
	//	blendMode:
	//	This parameter controls how the content is "mixed" into the HTML DOM.
	//	You can use any of the following xModify operations to specify how the
	//	inclusion will occur.
	//	append, replace, replace-children, prepend, insert-before, insert-after.
	//
	},
 
	includeRequest: function(/*dojo._xhrArgs*/args, /*String*/query, /*String*/blendMode){
	// 	summary:
	//     	Blends the response to a request into the HTML DOM. The request is made
	//		synchronously.
	// 	args:
	//     An dojo._xhrArgs object containing the arguments for the http
	//     request. The response to the request must be a parsable XML document.
	// 	query:
	//     	An HTML node or query that the processor can use as reference for
	//     	output placement. For example, the processor
	//     	can replace this node with some output, or create a sibling
	//     	of this node.
	//	blendMode:
	//	This parameter controls how the content is "mixed" into the HTML DOM.
	//	You can use any of the following xModify operations to specify how the
	//	inclusion will occur.
	//	append, replace, replace-children, prepend, insert-before, insert-after.
	//		
 
	}
 
});
 
dojo.declare("dojoe.Include", [], {
	//	summary:
	//	The dojoe.Include class allows developers to access the 
	//	functionality of the underlying dojoe.includeDocument and
	//	dojoe.includeRequest functions via markup.
	//
	//	Developers should only use this object by defining it in markup.
	//	If this functionality is needed programmatically use the include* 
	//	functions that are located on the dojoe object.
	//
	//	example:
	//	<dojoe.Include src="addContact.php" 
	//			query="myContact" blendMode="prepend"
	//			onSuccess="" onFailure="">
	//	or
	//	<dojoe.Include query="myContact" blendMode="prepend">
	//		<tr><td class=cnTableBody>Joe Smith</td>
	//		<td class=cnTableBody>jsmith@gmail.com</td></tr>
	//	</dojoe.Include>
	//
 
	//Defines the url that dojo.E retrieve for the content. 
	// This parameter/attribute is optional, if not specified
	// the include will take the children of the content tag.
	src: "",
 
	// Defines how the content will be blended into the HTML DOM.
	// Possible values for the blendMode is:
	// append, replace, replace-children, prepend, insert-before, insert-after.
	blendMode: "append",
 
	//A dojo.query string that defines where in the HTML DOM to 
	//place the content.
	query: "",
 
	/**
	 * PUBLIC EVENTS
	 */
	onSuccess: function(){
	},
 
	onFailure: function(){
	}
});