summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/javascript.rst
blob: bb901ead98349e55e4c53691ed0dc383ecac300c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
################
Javascript Class
################

.. note:: This driver is experimental. Its feature set and
	implementation may change in future releases.

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.

.. contents::
  :local:

.. raw:: html

  <div class="custom-index container"></div>

**************************
Using the Javascript Class
**************************

Initializing the Class
======================

To initialize the Javascript class manually in your controller
constructor, use the ``$this->load->library()`` method. Currently,
the only available library is jQuery, which will automatically be
loaded like this::

	$this->load->library('javascript');

The Javascript class also accepts parameters:

- js_library_driver (string) *default: 'jquery'*
- autoload (bool) *default: TRUE*

You may override the defaults by sending an associative array::

	$this->load->library(
		'javascript',
		array(
			'js_library_driver' => 'scripto',
			'autoload' => FALSE
		)
	);

Again, presently only 'jquery' is available. You may wish to set
autoload 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.

Once loaded, the jQuery library object will be available using:

	$this->javascript

Setup and Configuration
=======================

Set these variables in your view
--------------------------------

As a Javascript library, your files must be available to your
application.

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 ``<head>``
sections of your output.

::

	<?php echo $library_src;?>
	<?php echo $script_head;?>


``$library_src``, is where the actual library file will be loaded, as
well as any subsequent plugin script calls; $script_head is where
specific events, functions and other commands will be rendered.

Set the path to the librarys with config items
----------------------------------------------

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.

An image to be used as an "ajax loader", or progress indicator. Without
one, the simple text message of "loading" will appear when Ajax calls
need to be made.

::

	$config['javascript_location'] = 'http://localhost/codeigniter/themes/js/jquery/';
	$config['javascript_ajax_img'] = 'images/ajax-loader.gif';

If you keep your files in the same directories they were downloaded
from, then you need not set this configuration items.

The jQuery Class
================

To initialize the jQuery class manually in your controller constructor,
use the ``$this->load->library()`` method::

	$this->load->library('javascript/jquery');

You may send an optional parameter to determine whether or not a script
tag for the main jQuery file will be automatically included when loading
the library. It will be created by default. To prevent this, load the
library as follows::

	$this->load->library('javascript/jquery', FALSE);

Once loaded, the jQuery library object will be available using:

	$this->jquery

jQuery Events
=============

Events are set using the following syntax.
::

	$this->jquery->event('element_path', code_to_run());

In the above example:

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

Effects
=======

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

	$this->jquery->effect([optional path] plugin name); // for example $this->jquery->effect('bounce');


hide() / show()
---------------

Each of this functions will affect the visibility of an item on your
page. hide() will set an item invisible, show() will reveal it.

::

	$this->jquery->hide(target, optional speed, optional extra information);
	$this->jquery->show(target, optional speed, optional extra information);


-  "target" will be any valid jQuery selector or selectors.
-  "speed" is optional, and is set to either slow, normal, fast, or
   alternatively a number of milliseconds.
-  "extra information" is optional, and could include a callback, or
   other additional information.

toggle()
--------

toggle() will change the visibility of an item to the opposite of its
current state, hiding visible elements, and revealing hidden ones.

::

	$this->jquery->toggle(target);


-  "target" will be any valid jQuery selector or selectors.

animate()
---------

::

	 $this->jquery->animate(target, parameters, optional speed, optional extra information);


-  "target" will be any valid jQuery selector or selectors.
-  "parameters" in jQuery would generally include a series of CSS
   properties that you wish to change.
-  "speed" is optional, and is set to either slow, normal, fast, or
   alternatively a number of milliseconds.
-  "extra information" is optional, and could include a callback, or
   other additional information.

For a full summary, see
`http://docs.jquery.com/Effects/animate <http://docs.jquery.com/Effects/animate>`_

Here is an example of an animate() called on a div with an id of "note",
and triggered by a click using the jQuery library's click() event.

::

	$params = array(
	'height' => 80,
	'width' => '50%',
	'marginLeft' => 125
	);
	$this->jquery->click('#trigger', $this->jquery->animate('#note', $params, 'normal'));

fadeIn() / fadeOut()
--------------------

::

	$this->jquery->fadeIn(target,  optional speed, optional extra information);
	$this->jquery->fadeOut(target,  optional speed, optional extra information);


-  "target" will be any valid jQuery selector or selectors.
-  "speed" is optional, and is set to either slow, normal, fast, or
   alternatively a number of milliseconds.
-  "extra information" is optional, and could include a callback, or
   other additional information.

toggleClass()
-------------

This function will add or remove a CSS class to its target.

::

	$this->jquery->toggleClass(target, class)


-  "target" will be any valid jQuery selector or selectors.
-  "class" is any CSS classname. Note that this class must be defined
   and available in a CSS that is already loaded.

fadeIn() / fadeOut()
--------------------

These effects cause an element(s) to disappear or reappear over time.

::

	$this->jquery->fadeIn(target,  optional speed, optional extra information);
	$this->jquery->fadeOut(target,  optional speed, optional extra information);


-  "target" will be any valid jQuery selector or selectors.
-  "speed" is optional, and is set to either slow, normal, fast, or
   alternatively a number of milliseconds.
-  "extra information" is optional, and could include a callback, or
   other additional information.

slideUp() / slideDown() / slideToggle()
---------------------------------------

These effects cause an element(s) to slide.

::

	$this->jquery->slideUp(target,  optional speed, optional extra information);
	$this->jquery->slideDown(target,  optional speed, optional extra information);
	$this->jquery->slideToggle(target,  optional speed, optional extra information);


-  "target" will be any valid jQuery selector or selectors.
-  "speed" is optional, and is set to either slow, normal, fast, or
   alternatively a number of milliseconds.
-  "extra information" is optional, and could include a callback, or
   other additional information.

Plugins
=======

Some select jQuery plugins are made available using this library.

corner()
--------

Used to add distinct corners to page elements. For full details see
`http://www.malsup.com/jquery/corner/ <http://www.malsup.com/jquery/corner/>`_

::

	$this->jquery->corner(target, corner_style);


-  "target" will be any valid jQuery selector or selectors.
-  "corner_style" 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 "tl" (top left), "tr"
   (top right), "bl" (bottom left), or "br" (bottom right).

::

	$this->jquery->corner("#note", "cool tl br");


tablesorter()
-------------

description to come

modal()
-------

description to come

calendar()
----------

description to come