Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 9228f85b1b4f59cc88ba7c4addc258a7a5fd0ac0 / . / user_guide_src / source / libraries / javascript.rst
blob: bb901ead98349e55e4c53691ed0dc383ecac300c [file] [log] [blame]
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]1################
2Javascript Class
3################
4
Andrey Andreev46145fa2014-02-07 15:49:06 +0200[diff] [blame]5.. note:: This driver is experimental. Its feature set and
6 implementation may change in future releases.
7
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]8CodeIgniter provides a library to help you with certain common functions
9that you may want to use with Javascript. Please note that CodeIgniter
10does not require the jQuery library to run, and that any scripting
11library will work equally well. The jQuery library is simply presented
12as a convenience if you choose to use it.
13
Andrey Andreev46145fa2014-02-07 15:49:06 +0200[diff] [blame]14.. contents::
15 :local:
16
17.. raw:: html
18
19 <div class="custom-index container"></div>
20
21**************************
22Using the Javascript Class
23**************************
24
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]25Initializing the Class
26======================
27
28To initialize the Javascript class manually in your controller
Andrey Andreev46145fa2014-02-07 15:49:06 +0200[diff] [blame]29constructor, use the ``$this->load->library()`` method. Currently,
30the only available library is jQuery, which will automatically be
31loaded like this::
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]32
33 $this->load->library('javascript');
34
Andrey Andreev46145fa2014-02-07 15:49:06 +0200[diff] [blame]35The Javascript class also accepts parameters:
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]36
Andrey Andreev46145fa2014-02-07 15:49:06 +0200[diff] [blame]37- js_library_driver (string) *default: 'jquery'*
38- autoload (bool) *default: TRUE*
39
40You may override the defaults by sending an associative array::
41
42 $this->load->library(
43 'javascript',
44 array(
45 'js_library_driver' => 'scripto',
46 'autoload' => FALSE
47 )
48 );
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]49
50Again, presently only 'jquery' is available. You may wish to set
51autoload to FALSE, though, if you do not want the jQuery library to
52automatically include a script tag for the main jQuery script file. This
53is useful if you are loading it from a location outside of CodeIgniter,
54or already have the script tag in your markup.
55
56Once loaded, the jQuery library object will be available using:
Andrey Andreev46145fa2014-02-07 15:49:06 +0200[diff] [blame]57
58 $this->javascript
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]59
60Setup and Configuration
61=======================
62
63Set these variables in your view
64--------------------------------
65
66As a Javascript library, your files must be available to your
67application.
68
69As Javascript is a client side language, the library must be able to
70write content into your final output. This generally means a view.
Andrey Andreev46145fa2014-02-07 15:49:06 +0200[diff] [blame]71You'll need to include the following variables in the ``<head>``
72sections of your output.
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]73
74::
75
Derek Jonesd095adf2011-10-05 15:55:20 -0500[diff] [blame]76 <?php echo $library_src;?>
77 <?php echo $script_head;?>
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]78
79
Andrey Andreev46145fa2014-02-07 15:49:06 +0200[diff] [blame]80``$library_src``, is where the actual library file will be loaded, as
81well as any subsequent plugin script calls; $script_head is where
82specific events, functions and other commands will be rendered.
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]83
84Set the path to the librarys with config items
85----------------------------------------------
86
87There are some configuration items in Javascript library. These can
Andrey Andreev46145fa2014-02-07 15:49:06 +0200[diff] [blame]88either be set in *application/config.php*, within its own
89*config/javascript.php* file, or within any controller usings the
90``set_item()`` function.
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]91
92An image to be used as an "ajax loader", or progress indicator. Without
93one, the simple text message of "loading" will appear when Ajax calls
94need to be made.
95
96::
97
Derek Jonesd095adf2011-10-05 15:55:20 -0500[diff] [blame]98 $config['javascript_location'] = 'http://localhost/codeigniter/themes/js/jquery/';
99 $config['javascript_ajax_img'] = 'images/ajax-loader.gif';
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]100
101If you keep your files in the same directories they were downloaded
102from, then you need not set this configuration items.
103
104The jQuery Class
105================
106
107To initialize the jQuery class manually in your controller constructor,
Andrey Andreev46145fa2014-02-07 15:49:06 +0200[diff] [blame]108use the ``$this->load->library()`` method::
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]109
Chad Hedgcocka28812a2012-04-25 23:29:52 -0300[diff] [blame]110 $this->load->library('javascript/jquery');
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]111
112You may send an optional parameter to determine whether or not a script
113tag for the main jQuery file will be automatically included when loading
114the library. It will be created by default. To prevent this, load the
115library as follows::
116
Chad Hedgcocka28812a2012-04-25 23:29:52 -0300[diff] [blame]117 $this->load->library('javascript/jquery', FALSE);
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]118
119Once loaded, the jQuery library object will be available using:
Andrey Andreev46145fa2014-02-07 15:49:06 +0200[diff] [blame]120
121 $this->jquery
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]122
123jQuery Events
124=============
125
126Events are set using the following syntax.
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]127::
128
129 $this->jquery->event('element_path', code_to_run());
130
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]131In the above example:
132
133- "event" is any of blur, change, click, dblclick, error, focus, hover,
134 keydown, keyup, load, mousedown, mouseup, mouseover, mouseup, resize,
135 scroll, or unload.
Andrey Andreev46145fa2014-02-07 15:49:06 +0200[diff] [blame]136- "element_path" is any valid `jQuery selector
137 <http://docs.jquery.com/Selectors>`_. Due to jQuery's unique
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]138 selector syntax, this is usually an element id, or CSS selector. For
Andrey Andreev46145fa2014-02-07 15:49:06 +0200[diff] [blame]139 example "#notice_area" would effect ``<div id="notice_area">``, and
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]140 "#content a.notice" would effect all anchors with a class of "notice"
141 in the div with id "content".
Andrey Andreev46145fa2014-02-07 15:49:06 +0200[diff] [blame]142- "``code_to_run()``" is script your write yourself, or an action such as
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]143 an effect from the jQuery library below.
144
145Effects
146=======
147
148The query library supports a powerful
149`Effects <http://docs.jquery.com/Effects>`_ repertoire. Before an effect
150can be used, it must be loaded::
151
152 $this->jquery->effect([optional path] plugin name); // for example $this->jquery->effect('bounce');
153
154
155hide() / show()
156---------------
157
158Each of this functions will affect the visibility of an item on your
159page. hide() will set an item invisible, show() will reveal it.
160
161::
162
Derek Jonesd095adf2011-10-05 15:55:20 -0500[diff] [blame]163 $this->jquery->hide(target, optional speed, optional extra information);
164 $this->jquery->show(target, optional speed, optional extra information);
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]165
166
167- "target" will be any valid jQuery selector or selectors.
168- "speed" is optional, and is set to either slow, normal, fast, or
169 alternatively a number of milliseconds.
170- "extra information" is optional, and could include a callback, or
171 other additional information.
172
173toggle()
174--------
175
176toggle() will change the visibility of an item to the opposite of its
177current state, hiding visible elements, and revealing hidden ones.
178
179::
180
181 $this->jquery->toggle(target);
182
183
184- "target" will be any valid jQuery selector or selectors.
185
186animate()
187---------
188
189::
190
191 $this->jquery->animate(target, parameters, optional speed, optional extra information);
192
193
194- "target" will be any valid jQuery selector or selectors.
195- "parameters" in jQuery would generally include a series of CSS
196 properties that you wish to change.
197- "speed" is optional, and is set to either slow, normal, fast, or
198 alternatively a number of milliseconds.
199- "extra information" is optional, and could include a callback, or
200 other additional information.
201
202For a full summary, see
203`http://docs.jquery.com/Effects/animate <http://docs.jquery.com/Effects/animate>`_
204
205Here is an example of an animate() called on a div with an id of "note",
206and triggered by a click using the jQuery library's click() event.
207
208::
209
Derek Jonesd095adf2011-10-05 15:55:20 -0500[diff] [blame]210 $params = array(
211 'height' => 80,
212 'width' => '50%',
213 'marginLeft' => 125
214 );
János Rusiczki126c09b2012-10-16 01:50:31 +0300[diff] [blame]215 $this->jquery->click('#trigger', $this->jquery->animate('#note', $params, 'normal'));
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]216
217fadeIn() / fadeOut()
218--------------------
219
220::
221
Derek Jonesd095adf2011-10-05 15:55:20 -0500[diff] [blame]222 $this->jquery->fadeIn(target, optional speed, optional extra information);
223 $this->jquery->fadeOut(target, optional speed, optional extra information);
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]224
225
226- "target" will be any valid jQuery selector or selectors.
227- "speed" is optional, and is set to either slow, normal, fast, or
228 alternatively a number of milliseconds.
229- "extra information" is optional, and could include a callback, or
230 other additional information.
231
232toggleClass()
233-------------
234
235This function will add or remove a CSS class to its target.
236
237::
238
239 $this->jquery->toggleClass(target, class)
240
241
242- "target" will be any valid jQuery selector or selectors.
243- "class" is any CSS classname. Note that this class must be defined
244 and available in a CSS that is already loaded.
245
246fadeIn() / fadeOut()
247--------------------
248
249These effects cause an element(s) to disappear or reappear over time.
250
251::
252
Derek Jonesd095adf2011-10-05 15:55:20 -0500[diff] [blame]253 $this->jquery->fadeIn(target, optional speed, optional extra information);
254 $this->jquery->fadeOut(target, optional speed, optional extra information);
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]255
256
257- "target" will be any valid jQuery selector or selectors.
258- "speed" is optional, and is set to either slow, normal, fast, or
259 alternatively a number of milliseconds.
260- "extra information" is optional, and could include a callback, or
261 other additional information.
262
263slideUp() / slideDown() / slideToggle()
264---------------------------------------
265
266These effects cause an element(s) to slide.
267
268::
269
Derek Jonesd095adf2011-10-05 15:55:20 -0500[diff] [blame]270 $this->jquery->slideUp(target, optional speed, optional extra information);
271 $this->jquery->slideDown(target, optional speed, optional extra information);
272 $this->jquery->slideToggle(target, optional speed, optional extra information);
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]273
274
275- "target" will be any valid jQuery selector or selectors.
276- "speed" is optional, and is set to either slow, normal, fast, or
277 alternatively a number of milliseconds.
278- "extra information" is optional, and could include a callback, or
279 other additional information.
280
281Plugins
282=======
283
284Some select jQuery plugins are made available using this library.
285
286corner()
287--------
288
289Used to add distinct corners to page elements. For full details see
290`http://www.malsup.com/jquery/corner/ <http://www.malsup.com/jquery/corner/>`_
291
292::
293
294 $this->jquery->corner(target, corner_style);
295
296
297- "target" will be any valid jQuery selector or selectors.
298- "corner_style" is optional, and can be set to any valid style such
299 as round, sharp, bevel, bite, dog, etc. Individual corners can be set
300 by following the style with a space and using "tl" (top left), "tr"
301 (top right), "bl" (bottom left), or "br" (bottom right).
302
303::
304
305 $this->jquery->corner("#note", "cool tl br");
306
307
308tablesorter()
309-------------
310
311description to come
312
313modal()
314-------
315
316description to come
317
318calendar()
319----------
320
Andrey Andreev46145fa2014-02-07 15:49:06 +0200[diff] [blame]321description to come