Source

CodeIgniter Reactor / user_guide / libraries / javascript.html

Full commit
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>

<title>JavaScript Driver : CodeIgniter User Guide</title>

<style type='text/css' media='all'>@import url('../userguide.css');</style>
<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />

<script type="text/javascript" src="../nav/nav.js"></script>
<script type="text/javascript" src="../nav/prototype.lite.js"></script>
<script type="text/javascript" src="../nav/moo.fx.js"></script>
<script type="text/javascript" src="../nav/user_guide_menu.js"></script>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv='expires' content='-1' />
<meta http-equiv= 'pragma' content='no-cache' />
<meta name='robots' content='all' />
<meta name='author' content='ExpressionEngine Dev Team' />
<meta name='description' content='CodeIgniter User Guide' />

</head>
<body>

<!-- START NAVIGATION -->
<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
<div id="nav2"><a name="top"></a><a href="javascript:void(0);" onclick="myHeight.toggle();"><img src="../images/nav_toggle_darker.jpg" width="153" height="44" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
<div id="masthead">
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td><h1>CodeIgniter User Guide Version 2.0.0</h1></td>
<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
</tr>
</table>
</div>
<!-- END NAVIGATION -->


<!-- START BREADCRUMB -->
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td id="breadcrumb">
<a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
<a href="../general/drivers.html">Drivers</a> &nbsp;&#8250;&nbsp;
JavaScript Driver
</td>
<td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="codeigniter.com/user_guide/" />Search User Guide&nbsp; <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" />&nbsp;<input type="submit" class="submit" name="sa" value="Go" /></form></td>
</tr>
</table>
<!-- END BREADCRUMB -->

<br clear="all" />


<!-- START CONTENT -->
<div id="content">

<p class="important"><strong>Note:</strong> This driver is experimental. Its feature set and implementation may change in future releases.</p><br>

<h1>Javascript Driver</h1>
<p>CodeIgniter provides a library to help you with certain common functions that you may want to use with Javascript. Please note that CodeIgniter does not require the jQuery library to run, and that any scripting library will work equally well. The jQuery library is simply presented as a convenience if you choose to use it.</p>
<h2>Initializing the Class</h2>
<p>To initialize the Javascript class manually in your controller constructor, use the <dfn>$this-&gt;load-&gt;driver</dfn> function. Currently, the only available library is jQuery, which will automatically be loaded like this:</p>

<code>$this-&gt;load-&gt;driver('javascript');</code>

<p>The Javascript class also accepts parameters, <dfn>adapter (string) default 'jquery'</dfn> and <dfn>autoload (bool) default TRUE</dfn>.  You may override the defaults if you wish by sending an associative array:</p>

<code>$this-&gt;load-&gt;driver('javascript', array('adapter' =&gt; 'scripto', 'autoload' =&gt; FALSE));</code>

<p>Again, presently only 'jquery' is available.  You may wish to set <dfn>autoload</dfn> to FALSE, though, if you do not want the jQuery library to automatically include a script tag for the main jQuery script file.  This is useful if you are loading it from a location outside of CodeIgniter, or already have the script tag in your markup.</p>

<p>Once loaded, the jQuery library object will be available using: <dfn>$this-&gt;javascript</dfn></p>
<h2>Setup and Configuration</h2>
<h3>Set these variables in your view</h3>
<p>As a Javascript library, your files must be available to your application.</p>
<p>As Javascript is a client side language, the library must be able to write content into your final output. This generally means a view. You'll need to include the following variables in the &lt;head&gt; sections of your output.</p>
<p><code>&lt;?php echo $library_src;?&gt;<br />
&lt;?php echo $script_foot;?&gt;
</code></p>
<p>$library_src, is where the actual library file will be loaded, as well as any subsequent plugin script calls; $script_foot is where specific events, functions and other commands will be rendered.</p>
<h3>Set the path to the libraries with config items</h3>
<p>There are some configuration items in Javascript library. These can either be set in application/config.php, within its own config/javascript.php file, or within any controller usings the set_item() function. </p>
<p>An image to be used as an &quot;ajax loader&quot;, or progress indicator. Without one, the simple text message of &quot;loading&quot; will appear when Ajax calls need to be made.</p>
<p><code>$config['javascript_location'] = 'http://localhost/codeigniter/themes/js/jquery/';<br />
		$config['javascript_ajax_img'] = 'images/ajax-loader.gif';</code></p>
<p>If you keep your files in the same directories they were downloaded from, then you need not set this configuration items.</p>
<h2>Example Usage</h2>
<p>In order to create any output to created you must pass an array to <dfn>output($array)</dfn> function as shown.</p>
<p><code>$js = array();<br/><br/>//Add javascript to be compiled<br/>$js[] = $this-&gt;javascript-&gt;show('#details');<br/><br/>$this-&gt;javascript-&gt;output($js);<br/><br/>//Generate output<br/>$this-&gt;javascript-&gt;compile();</code>
</p>

<h1 id="function_reference">Function Reference</h1>
<h2>clear_compile()</h2>
<p>This function will clear any collected javascript for output.</p>
<p><code>$this-&gt;javascript-&gt;clear_compile();</code></p>
<h2>compile(<var>$view_var</var>['string'], <var>$script_tags</var>['bool'])</h2>
<p>This function will compile any collected javascript and return a string. By default <dfn>compile()</dfn> will generate the <var>$script_foot</var> variable to be used in views. All collected javascript will be created along with the appropriate &lt;script&gt; tag with CDATA block.</p>
<p><code>$this-&gt;javascript-&gt;compile();</code></p>
<p>Optionally, use the first parameter to change the name of the variable to be outputted automatically to your views, and pass <samp>FALSE</samp> to prevent the &lt;script&gt; tag block from being created.</p>
<p><code>$this-&gt;javascript-&gt;compile('script_head', FALSE);</code></p>
<h2>external(<var>$external_file</var>['string'], <var>$relative</var>['bool'])</h2>
<p>This function will create a &lt;script&gt; tag with a src attribute for the filename passed to it, and return it as a string.</p>
<p><code>$this-&gt;javascript-&gt;external($external_file);</code></p>
<p>You may pass <samp>TRUE</samp> as the second parameter to generate a relative url.</p>
<h2>generate_json(<var>$result</var>['mixed'], <var>$match_array_type</var>['bool'])</h2>
<p>This function will take a database result or associative array and return a JSON formatted string.</p>
<p><code>$this-&gt;javascript-&gt;generate_json($result);</code></p>
<p>Optionally, you may pass <samp>TRUE</samp> as the second parameter to match array types (defaults to objects).</p>
<h2>inline(<var>$script</var>['string'], <var>$cdata</var>['bool'])</h2>
<p>This function allows you to create your own custom inline javascript. The function will return a string wrapped with &lt;script&gt; tag with a CDATA block.</p>
<p><code>$inline = "jQuery(document).ready(function(){ $('#element').hide(); });";<br/>$this-&gt;javascript->inline($inline);</code></p>
<p>Optionally, you may pass <samp>FALSE</samp> as the second parameter to prevent the CDATA block from being created.</p>
<h2>jQuery Events</h2>

<p>Events are set using the following syntax.</p>

<p><code>$this-&gt;javascript-&gt;event('element_path', code_to_run());</code></p>

<p>In the above example:</p>

<ul>
	<li>&quot;event&quot; is any of blur, change, click, dblclick, error, focus, hover, keydown, keyup, load, mousedown, mouseup, mouseover, mouseup, resize, scroll, or unload.</li>
	<li>&quot;element_path&quot; is any valid <a href="http://docs.jquery.com/Selectors">jQuery selector</a>. Due to jQuery's unique selector syntax, this is usually an element id, or CSS selector. For example &quot;#notice_area&quot; would effect &lt;div id=&quot;notice_area&quot;&gt;, and &quot;#content a.notice&quot; would effect all anchors with a class of &quot;notice&quot; in the div with id &quot;content&quot;.</li>
	<li>&quot;code_to_run()&quot; is script your write yourself, or an action such as an effect from the jQuery library below.</li>
	</ul>

<h2>Effects</h2>

<p>The query library supports a powerful <a href="http://docs.jquery.com/Effects">Effects</a> repertoire.  Before an effect can be used, it must be loaded:</p>

<p><code>$this->javascript->effect([optional path] plugin name);
// for example
$this-&gt;javascript-&lt;effect('bounce');
</code></p>

<h3>hide() / show()</h3>

<p>Each of this functions will affect the visibility of an item on your page. hide() will set an item invisible, show() will reveal it.</p>
<p><code>$this-&gt;javascript-&gt;hide(target,  optional speed, optional extra information);<br />
	$this-&gt;javascript-&gt;show(target,  optional speed, optional extra information);</code></p>

<ul>
	<li>&quot;target&quot; will be any valid jQuery selector or selectors.</li>
	<li>&quot;speed&quot; is optional, and is set to either slow, normal, fast, or alternatively a number of milliseconds.</li>
	<li>&quot;extra information&quot; is optional, and could include a callback, or other additional information.</li>
</ul>

<h3>toggle()</h3>

<p>toggle() will change the visibility of an item to the opposite of its current state, hiding visible elements, and revealing hidden ones.</p>
<p><code>$this-&gt;javascript-&gt;toggle(target);</code></p>
<ul>
	<li>&quot;target&quot; will be any valid jQuery selector or selectors.</li>
</ul>

<h3>animate()</h3>

<p><code> $this-&gt;javascript-&gt;animate(target, parameters, optional speed, optional extra information);</code></p>
<ul>
	<li>&quot;target&quot; will be any valid jQuery selector or selectors.</li>
	<li>&quot;paramters&quot; in jQuery would generally include a series of CSS properties that you wish to change.</li>
	<li>&quot;speed&quot; is optional, and is set to either slow, normal, fast, or alternatively a number of milliseconds.</li>
	<li>&quot;extra information&quot; is optional, and could include a callback, or other additional information.</li>
</ul>
<p>For a full summary, see <a href="http://docs.jquery.com/Effects/animate">http://docs.jquery.com/Effects/animate</a></p>
<p>Here is an example of an animate() called on a div with an id of &quot;note&quot;, and triggered by a click using the jQuery library's click() event.</p>
<p><code> $params = array(<br />
	'height' =&gt; 80,<br />
	'width' =&gt; '50%',<br />
	'marginLeft' =&gt; 125<br />
);<br />
$this-&gt;javascript-&gt;click('#trigger', $this-&gt;javascript-&gt;animate('#note', $params, normal));</code></p>

<h3>fadeIn() / fadeOut()</h3>

<p><code>$this-&gt;javascript-&gt;fadeIn(target,  optional speed, optional extra information);<br />
	$this-&gt;javascript-&gt;fadeOut(target,  optional speed, optional extra information);</code></p>
<ul>
	<li>&quot;target&quot; will be any valid jQuery selector or selectors.</li>
	<li>&quot;speed&quot; is optional, and is set to either slow, normal, fast, or alternatively a number of milliseconds.</li>
	<li>&quot;extra information&quot; is optional, and could include a callback, or other additional information.</li>
</ul>

<h3>toggleClass()</h3>

<p>This function will add or remove a CSS class to its target.</p>
<p><code>$this-&gt;javascript-&gt;toggleClass(target, class)</code></p>
<ul>
	<li>&quot;target&quot; will be any valid jQuery selector or selectors.</li>
	<li>&quot;class&quot; is any CSS classname. Note that this class must be defined and available in a CSS that is already loaded.</li>
	</ul>

<h3>fadeIn() / fadeOut()</h3>

<p>These effects cause an element(s) to disappear or reappear over time.</p>
<p><code>$this-&gt;javascript-&gt;fadeIn(target,  optional speed, optional extra information);<br />
	$this-&gt;javascript-&gt;fadeOut(target,  optional speed, optional extra information);</code></p>
<ul>
	<li>&quot;target&quot; will be any valid jQuery selector or selectors.</li>
	<li>&quot;speed&quot; is optional, and is set to either slow, normal, fast, or alternatively a number of milliseconds.</li>
	<li>&quot;extra information&quot; is optional, and could include a callback, or other additional information.</li>
</ul>

<h3>slideUp() / slideDown() / slideToggle()</h3>

<p>These effects cause an element(s) to slide.</p>
<p><code>$this-&gt;javascript-&gt;slideUp(target,  optional speed, optional extra information);<br />
	$this-&gt;javascript-&gt;slideDown(target,  optional speed, optional extra information);<br />
$this-&gt;javascript-&gt;slideToggle(target,  optional speed, optional extra information);</code></p>
<ul>
	<li>&quot;target&quot; will be any valid jQuery selector or selectors.</li>
	<li>&quot;speed&quot; is optional, and is set to either slow, normal, fast, or alternatively a number of milliseconds.</li>
	<li>&quot;extra information&quot; is optional, and could include a callback, or other additional information.</li>
</ul>

<h2>Plugins</h2>

<p>

<p>Some select jQuery plugins are made available using this library.</p>

<h3>corner()</h3>
<p>Used to add distinct corners to page elements. For full details see <a href="http://www.malsup.com/jquery/corner/">http://www.malsup.com/jquery/corner/</a></p>
<p><code>$this-&gt;javascript-&gt;corner(target, corner_style);</code></p>
<ul>
	<li>&quot;target&quot; will be any valid jQuery selector or selectors.</li>
	<li>&quot;corner_style&quot; is optional, and can be set to any valid style such as round, sharp, bevel, bite, dog, etc. Individual corners can be set by following the style with a space and using &quot;tl&quot; (top left), &quot;tr&quot; (top right), &quot;bl&quot; (bottom left), or &quot;br&quot; (bottom right).</li>
</ul>
<p><code>$this-&gt;jquery-&gt;corner(&quot;#note&quot;, &quot;cool tl br&quot;);</code></p>

<h3>tablesorter()</h3>

<p>description to come</p>

<h3>modal()</h3>

<p>description to come</p>

<h3>calendar()</h3>

<p>description to come</p>

</div>
<!-- END CONTENT -->


<div id="footer">
<p>
Previous Topic:&nbsp;&nbsp;<a href="input.html">Input Class</a>
&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
Next Topic:&nbsp;&nbsp;<a href="language.html">Language Class</a></p>
<p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006 - 2011 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">EllisLab, Inc.</a></p>
</div>

</body>
</html>