safeframe

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="generator" content="JsDoc Toolkit" /> <title>$sf.lib.dom.iframes | SafeFrames JS API</title> <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0" /> <meta name="mobileoptimized" content="0" /> <link rel="stylesheet" href="../css/all.css" media="all" /> <link rel="stylesheet" href="../css/handheld.css" media="only screen and (max-width: 660px)" /> <link rel="stylesheet" href="../css/handheld.css" media="handheld" /> <link rel="stylesheet" href="../css/screen.css" media="screen and (min-width: 661px)" /> <script src="../javascript/all.js"></script>  </head> <body> <div class="index"> <div class="menu"> <div class="indexLinks"> </div> <h2 class="heading1">Classes</h2> <input type="text" name="classFilter" class="classFilter" id="ClassFilter" placeholder="Filter"></input> <nav> <ul class="classList" id="ClassList"> <li><a href="../symbols/%24sf.html">$sf</a></li> <li><a href="../symbols/%24sf.env.html">$sf<span class='break'> </span>.<span class='break'> </span>env</a></li> <li><a href="../symbols/%24sf.env.ua.html">$sf<span class='break'> </span>.<span class='break'> </span>env<span class='break'> </span>.<span class='break'> </span>ua</a></li> <li><a href="../symbols/%24sf.lib.html">$sf<span class='break'> </span>.<span class='break'> </span>lib</a></li> <li><a href="../symbols/%24sf.lib.dom.html">$sf<span class='break'> </span>.<span class='break'> </span>lib<span class='break'> </span>.<span class='break'> </span>dom</a></li> <li><a href="../symbols/%24sf.lib.dom.iframes.html">$sf<span class='break'> </span>.<span class='break'> </span>lib<span class='break'> </span>.<span class='break'> </span>dom<span class='break'> </span>.<span class='break'> </span>iframes</a></li> <li><a href="../symbols/%24sf.lib.dom.msghost.html">$sf<span class='break'> </span>.<span class='break'> </span>lib<span class='break'> </span>.<span class='break'> </span>dom<span class='break'> </span>.<span class='break'> </span>msghost</a></li> <li><a href="../symbols/%24sf.lib.lang.html">$sf<span class='break'> </span>.<span class='break'> </span>lib<span class='break'> </span>.<span class='break'> </span>lang</a></li> <li><a href="../symbols/%24sf.lib.lang.ParamHash.html">$sf<span class='break'> </span>.<span class='break'> </span>lib<span class='break'> </span>.<span class='break'> </span>lang<span class='break'> </span>.<span class='break'> </span>ParamHash</a></li> <li><a href="../symbols/%24sf.pub.html">$sf<span class='break'> </span>.<span class='break'> </span>pub</a></li> <li><a href="../symbols/%24sf.pub.Config.html">$sf<span class='break'> </span>.<span class='break'> </span>pub<span class='break'> </span>.<span class='break'> </span>Config</a></li> <li><a href="../symbols/%24sf.pub.PosConfig.html">$sf<span class='break'> </span>.<span class='break'> </span>pub<span class='break'> </span>.<span class='break'> </span>PosConfig</a></li> <li><a href="../symbols/%24sf.pub.Position.html">$sf<span class='break'> </span>.<span class='break'> </span>pub<span class='break'> </span>.<span class='break'> </span>Position</a></li> <li><a href="../symbols/%24sf.vend.html">$sf<span class='break'> </span>.<span class='break'> </span>vend</a></li> </ul> </nav> </div> <div class="fineprint" style="clear:both"> <footer> Documentation generator: <a href="http://code.google.com/p/jsdoc-toolkit/" target="_blank">JsDoc Toolkit</a> 2.4.0<br /> Template: <a href="" target="_blank">Codeview</a> 1.2.1<br /> Generated on: <time datetime='2012-7-6' pubdate>2012-7-6 16:05</time> </footer> </div> </div> <div class="index indexStatic"></div> <div class="content"> <div class="innerContent"> <article> <header> <h1 class="classTitle"> Namespace <span>$sf.lib.dom.iframes</span> </h1> <div class="intro"> <p class="description summary"> $sf.lib.dom.iframes Defines helper functions for dealing specifically with IFRAME tags, which is key to SafeFrames tech in a browser. </p> <ul class="summary"> </ul> </div> </header>  <section> <div class="props"> <h2 class="sectionTitle">Method Summary</h2> <nav> <table class="summaryTable" id="MethodsList" cellspacing="0" summary="A summary of the methods documented in the class $sf.lib.dom.iframes."> <thead> <tr> <th scope="col">Method Attributes</th> <th scope="col">Method Name and Description</th> </tr> </thead> <tbody> <tr class='item0' > <td class="attributes"><static>  </td> <td class="nameDescription"> <div class="fixedFont">$sf.lib.dom.iframes.<b><a href="../symbols/%24sf.lib.dom.iframes.html#.clone">clone</a></b>(el, attrs, cssText, cb, xmsgCB) </div> <div class="description">Clones an iframe.</div> </td> </tr> <tr class='item1' > <td class="attributes"><static>  </td> <td class="nameDescription"> <div class="fixedFont">$sf.lib.dom.iframes.<b><a href="../symbols/%24sf.lib.dom.iframes.html#.make">make</a></b>(attrs, cssText, cb, xmsgCB) </div> <div class="description">Make a new iframe</div> </td> </tr> <tr class='item2' > <td class="attributes"><static>  </td> <td class="nameDescription"> <div class="fixedFont">$sf.lib.dom.iframes.<b><a href="../symbols/%24sf.lib.dom.iframes.html#.replace">replace</a></b>(attrs, cssText, parRef, cb, xmsgCB) </div> <div class="description">A method to insert or replace an HTML tag with an IFRAME tag, with a new URL and attributes.</div> </td> </tr> <tr class='item3' > <td class="attributes"><static>  </td> <td class="nameDescription"> <div class="fixedFont">$sf.lib.dom.iframes.<b><a href="../symbols/%24sf.lib.dom.iframes.html#.view">view</a></b>(el) </div> <div class="description">Retrieve the window reference inside of an IFRAME.</div> </td> </tr> </tbody> </table> </nav> </div> </section>     <section> <div class="details props"> <div class="innerProps"> <h2 class="sectionTitle"> Method Detail </h2> <ul class="methodDetail" id="MethodDetail"> <li class='item0' > <div class="fixedFont heading" id=".clone"> <span class='lighter'> <static> </span> <span class="light">{HTMLElement}</span> <span class="light">$sf.lib.dom.iframes.</span><b>clone</b>(el, attrs, cssText, cb, xmsgCB) </div> <div class="description"> Clones an iframe. . . This code creates / clones iframe tags in a very specific way to ensure both optimal performance and stability. We use string buffers to build markup internally, which is typically faster than using all DOM APIs. Also we allow the usage of the "name" attribute as a data pipeline, which in turn allows for synchronous downward x-domain messaging. </div> <dl class="detailList params"> <dt class="heading">Parameters:</dt> <dt> <span class="light fixedFont">{HTMLElement/String}</span> <b>el</b> </dt> <dd>An iframe element or id of an iframe element to clone</dd> <dt> <span class="light fixedFont">{Object}</span> <b>attrs</b> <i>Optional</i> </dt> <dd>A hash map of other attributes to be set on the iframe. Do not set style properties for the frame here, see the next argument for that.</dd> <dt> <span class="light fixedFont">{String}</span> <b>cssText</b> <i>Optional</i> </dt> <dd>The style string (as in what you would use in HTML markup, e.g. "background-color:red;border:solid 3px blue;"), to use for this iframe</dd> <dt> <span class="light fixedFont">{Function}</span> <b>cb</b> <i>Optional</i> </dt> <dd>An optional callback function to specify for when the iframe loads.</dd> <dt> <span class="light fixedFont">{Function}</span> <b>xmsgCB</b> <i>Optional</i> </dt> <dd>An optional call back for receiving messages from the iframe</dd> </dl> <dl class="detailList nomargin"> <dt class="heading">Returns:</dt> <dd><span class="light fixedFont">{HTMLElement}</span> the iframe node if succesfully created or NULL. Note that this does not insert the iframe into the document for you. . .</dd> </dl> <div class="hr"></div> </li> <li class='item1' > <div class="fixedFont heading" id=".make"> <span class='lighter'> <static> </span> <span class="light">{HTMLElement}</span> <span class="light">$sf.lib.dom.iframes.</span><b>make</b>(attrs, cssText, cb, xmsgCB) </div> <div class="description"> Make a new iframe </div> <dl class="detailList params"> <dt class="heading">Parameters:</dt> <dt> <span class="light fixedFont">{Object}</span> <b>attrs</b> </dt> <dd>A hash map of other attributes to be set on the iframe. Do not set style properties for the frame here, see the next argument for that.</dd> <dt> <span class="light fixedFont">{String}</span> <b>cssText</b> <i>Optional</i> </dt> <dd>The style string (as in what you would use in HTML markup, e.g. "background-color:red;border:solid 3px blue;"), to use for this iframe</dd> <dt> <span class="light fixedFont">{Function}</span> <b>cb</b> <i>Optional</i> </dt> <dd>An callback function to specify for when the iframe loads.</dd> <dt> <span class="light fixedFont">{Function}</span> <b>xmsgCB</b> <i>Optional</i> </dt> <dd>An call back for receiving messages from the iframe</dd> </dl> <dl class="detailList nomargin"> <dt class="heading">Returns:</dt> <dd><span class="light fixedFont">{HTMLElement}</span> the iframe node if succesfully created or NULL. Note that this does not insert the iframe into the document for you. . .</dd> </dl> <div class="hr"></div> </li> <li class='item2' > <div class="fixedFont heading" id=".replace"> <span class='lighter'> <static> </span> <span class="light">{HTMLElement}</span> <span class="light">$sf.lib.dom.iframes.</span><b>replace</b>(attrs, cssText, parRef, cb, xmsgCB) </div> <div class="description"> A method to insert or replace an HTML tag with an IFRAME tag, with a new URL and attributes. Used for 3 reasons: <ol> <li>It avoids click sounds on IE.</li> <li>It allows always resetting the window.name property of the iframes underlying HTMLWindow object, unforunately IE will not let you set this attribute on a clone.</li> <li>It ensures that event handlers in the underlying document for unloading are executed.</li> <li>Changing the src attribute directly will result in a browser history update, which we do not want.</li> </ol> We could just change location.href property or call location.replace, however that is not always possible since the frame could be x-domain. </div> <dl class="detailList params"> <dt class="heading">Parameters:</dt> <dt> <span class="light fixedFont">{Object}</span> <b>attrs</b> </dt> <dd>A hash map of other attributes to be set on the iframe. Do not set style properties for the frame here, see the next argument for that.</dd> <dt> <span class="light fixedFont">{String}</span> <b>cssText</b> <i>Optional</i> </dt> <dd>The style string (as in what you would use in HTML markup, e.g. "background-color:red;border:solid 3px blue;"), to use for this iframe</dd> <dt> <span class="light fixedFont">{HTMLElement|String}</span> <b>parRef</b> <i>Optional</i> </dt> <dd>An parent element or parent element id, to be used only if a new iframe is created, the iframe will be append to that parent, if not specified document body is used</dd> <dt> <span class="light fixedFont">{Function}</span> <b>cb</b> <i>Optional</i> </dt> <dd>An callback function to specify for when the iframe loads.</dd> <dt> <span class="light fixedFont">{Function}</span> <b>xmsgCB</b> <i>Optional</i> </dt> <dd>An call back for receiving messages from the iframe</dd> </dl> <dl class="detailList nomargin"> <dt class="heading">Returns:</dt> <dd><span class="light fixedFont">{HTMLElement}</span> a reference to the newly created iframe element if successfully inserted, otherwise NULL.</dd> </dl> <div class="hr"></div> </li> <li class='item3' > <div class="fixedFont heading" id=".view"> <span class='lighter'> <static> </span> <span class="light">{HTMLWindow}</span> <span class="light">$sf.lib.dom.iframes.</span><b>view</b>(el) </div> <div class="description"> Retrieve the window reference inside of an IFRAME. Not to be confused with $sf.lib.dom.view which returns the parent window reference of an element. Note that even in cross-domain scenarios, you are supposed to able to get access to the window reference. In a cross-domain scenario, you would not be able to then acesss most properties / methods / objects of that window, but the reference itself is allowed. </div> <dl class="detailList params"> <dt class="heading">Parameters:</dt> <dt> <span class="light fixedFont">{HTMLElement}</span> <b>el</b> </dt> <dd>The iframe element to safely get back the window</dd> </dl> <dl class="detailList nomargin"> <dt class="heading">Returns:</dt> <dd><span class="light fixedFont">{HTMLWindow}</span> the window reference inside the iframe.</dd> </dl> </li> </ul> </div> </div> </section>  </article> </div> </div> <script type="text/javascript"> wbos.CssTools.MediaQueryFallBack.LoadCss('../css/screen.css', '../css/handheld.css', 660) codeview.classFilter.Init() </script> </body> </html>