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