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