Namespace atropa.inject

Version 20130308.
Contains tools for injecting elements and assemblies.
Defined in: <node_modules/atropa-inject/src/atropa-inject.js>.

Namespace Summary
Constructor Attributes	Constructor Name and Description
	atropa.inject Contains tools for injecting elements and assemblies.

Method Summary
Method Attributes	Method Name and Description
<static>	atropa.inject.element(elementType, docref, parentNod, attributes, onloadHandler, callback) Generic Element Injector.
<static>	atropa.inject.hiddenFrame(id, srcUrl, docref, onloadHandler, parentNod, callback) Hidden Iframe Injector.
<static>	atropa.inject.script(id, srcUrl, docref, callback) Script Injector.

Namespace Detail

atropa.inject

Contains tools for injecting elements and assemblies. into the page.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

Requires:: atropa.data; atropa.supportCheck; atropa.setAsOptionalArg

Method Detail

<static> {HTML Element} atropa.inject.element(elementType, docref, parentNod, attributes, onloadHandler, callback)

Generic Element Injector.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

Example attributes object :

attributesObj = {
    "id" : "elementID",
    "class" : "classy"
};

 // this will inject a div element into the document body.
 var el = atropa.inject.element ('div');
 
 // This will inject a div with the id "myId" into the element referenced by
 // "container"
 var el = atropa.inject.element (
     'div', document, container, { 'id': 'myId' }, null, null
 );
 
 // this will inject a div into the document of an iframe referenced with "fdoc"
 // Just before the div is injected the callback will be called and the element
 // may be augmented. When the callback returns the element will be injected.
 var fdoc = document.getElementById('someFrame').contentWindow.document;
 
 var el = atropa.inject.element (
     'div', fdoc, fdoc.body, { 'id': 'myId' },
     null,
     function (myDiv) {
         myDiv.textContent = 'I could have attached event handlers';
     }
 );
 
 // this will inject an iframe into the document
 // once the iframe's document has finished loading the onload handler will be
 // called. If the document and the iframe are on the same domain, scripts on
 // the frame and the parent document will be able to commuincate with each
 // other.
 function iframeHasLoaded (message) {
     console.log(message);
 }
 
 var el = atropa.inject.element (
     'iframe', document, document.body,
     { 'id': 'myId', 'src' : 'http://localhost' },
     function () {
         iframeHasLoaded('hey look at that, the frame is ready!');
         // what could I do with the frame? anything I want!
     },
     null
 );

Parameters:
{String} elementType: The type of element to be injected.
{HTML DOM Document} docref: Optional. A reference to the document to target, defaults to document.
{DOM Node} parentNod: Optional. A reference to the parent node to target, defaults to docref.body.
{Object} attributes: Optional. An object whose properties are names of HTML attributes, defaults to {}. The value of these properties are to be strings representing the values of the HTML attributes as they are to be applied to the injected element.
{Function} onloadHandler: Optional. If the element being injected will fire a load event, this function will be called. Defaults to function () {}.
{Function} callback: Optional. This function will be called just before the element is to be appended to the page. The callback will receive the element in its current state for any additional processing to be done prior to it's attachment on callback completion. Defaults to function () {}.

Returns:: {HTML Element} Returns a reference to the HTML Element created and injected.

See:: http://www.w3.org/Security/wiki/Same_Origin_Policy

<static> {HTML Element} atropa.inject.hiddenFrame(id, srcUrl, docref, onloadHandler, parentNod, callback)

Hidden Iframe Injector.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

 el = atropa.inject.hiddenFrame(
     'injectHiddenFrame3',
     'http://localhost/',
     null,
     function () {
         console.log('hey look at that, the frame is ready!');
     },
     null,
     null
 );

Parameters:
{String} id: The id of the element to be injected.
{String} srcUrl: The URL to load in the iframe.
{HTML DOM Document} docref: Optional. Reference to the document to inject the iframe in. Defaults to document.
{Function} onloadHandler: Optional. The onload handler for the iframe.
{DOM Node} parentNod: Optional. Referenct to the parent node to append the iframe to. Defaults to docref.body
{Function} callback: Optional. Callback function for preprocessing the iframe prior to injection. Called with a reference to the iframe.

Returns:: {HTML Element} Returns a reference to the HTML Element created and injected.

See:: atropa.inject.element; http://www.w3.org/Security/wiki/Same_Origin_Policy

<static> {HTML Element} atropa.inject.script(id, srcUrl, docref, callback)

Script Injector.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

 // Given a script "dummy.js" located at "http://localhost/dummy.js"
 // you can fetch the script and execute functions from within it
 // as soon as it has loaded into the page.
 
 // contents of "dummy.js"
 function dummy() {
     return 'dummy';
 }
 
 // injecting "dummy.js" into any page. The script tag isn't restricted by
 // the same origin policy. Host your script anywhere and inject it to any
 // page on the net that you want to.
 el = atropa.inject.script(
     'injectScript',
     'http://localhost/',
     document,
     function () {
         console.log(dummy());
     }
 );
 // you may also load scripts into iframes by replacing the third parameter
 // with a reference to the iframe's document object.

Parameters:
{String} id: The id of the element to be injected.
{String} srcUrl: The URL where the script is located.
{HTML DOM Document} docref: Optional. The document to inject the script into. Defaults to document.
{Function} callback: Optional. A function to execute once the script has loaded. Defaults to function () {};

Returns:: {HTML Element} Returns a reference to the HTML Element created and injected.

See:: atropa.inject.element; http://www.w3.org/Security/wiki/Same_Origin_Policy

Classes

Namespace atropa.inject