Docs/Slick/Slick.md

   1 Slick {#Slick}
   2 ==========================
   3
   4 Slick is the selector engine used by MooTools. It supports many CSS3 selectors and more!
   5
   6 ### See Also:
   7
   8 - [W3C Pseudo Classes](http://www.w3.org/TR/2005/WD-css3-selectors-20051215/#pseudo-classes)
   9
  10
  11 Reverse Combinators
  12 -------------------
  13
  14 Reverse Combinators redirect the flow of selectors and combinators. Slick implements these by prepending `!` to a selector or combinator.
  15
  16 ### Examples:
  17
  18         document.getElement('p ! div')    // A <div> that is an ancestor of a <p>
  19         document.getElement('p !> div')   // A <div> that is a direct parent of a <p>
  20         document.getElement('.foo !+ p')  // Gets the previous adjacent <p> sibling
  21
  22 ### Notes:
  23
  24 Reverse Combinators are used internally by MooTools for many of our traversal methods. They offer an extremely concise and powerful alternative to traversal methods like `getParent()`.
  25
  26
  27 Function: Slick.definePseudo  {#Slick:Slick-definePseudo}
  28 ---------------------------------------------------------
  29
  30 definePseudo allows you to create your own custom pseudo selectors.
  31
  32 ### Examples:
  33
  34         Slick.definePseudo('display', function(value){
  35                 return Element.getStyle(this, 'display') == value;
  36         });
  37
  38         <div style="display: none">foo</div>
  39         <div style="display: block">bar</div>
  40
  41         $$(':display(block)');          // Will return the block element
  42
  43         Slick.definePseudo('my-custom-pseudo', function(){
  44                 // 'this' is the node to check
  45                 return Element.retrieve(this, 'something-custom').isAwesome;
  46         });
  47
  48         $$(':my-custom-pseudo')         // Will return the first <p> tag that is awesome
  49
  50
  51 Selector: Next Siblings ('~') {#Slick:nextSiblings}
  52 ---------------------------------------------------
  53
  54 Gets the next siblings.
  55
  56 ### Example:
  57
  58         $$('p.foo ~')            // Gets all next siblings of <p class="foo">
  59         $$('p.foo ~ blockquote') // Gets every <blockquote> with a <p class="foo"> sibling somewhere *before* it
  60
  61
  62 Selector: Previous Siblings ('!~') {#Slick:previouSiblings}
  63 ------------------------------------------------------------
  64
  65 Gets the previous siblings.
  66
  67 ### Example:
  68
  69         $$('p.foo !~')            // Gets all previous siblings of <p class="foo">
  70         $$('p.foo !~ blockquote') // Gets every <blockquote> with a <p class="foo"> sibling somewhere *after* it
  71
  72
  73 Selector: All Siblings ('~~') {#Slick:allSiblings}
  74 --------------------------------------------------
  75
  76 Gets all siblings.
  77
  78 ### Example:
  79
  80         $$('p.foo ~~')            // Gets all previous and next siblings of <p class="foo">
  81         $$('p.foo ~~ blockquote') // Gets every <blockquote> with a <p class="foo"> sibling before OR after it
  82
  83 Selector: First Child ('^') {#Slick:firstChild}
  84 -----------------------------------------------
  85
  86 Gets the first child of an element.
  87
  88 ### Example:
  89
  90         $$('p.foo ^')           // Gets the first child of <p class="foo">
  91         $$('p.foo ^ strong')    // Gets every <strong> that is the first element child of a <p class="foo">
  92
  93
  94 Selector: Last Child ('!^') {#Slick:lastChild}
  95 ----------------------------------------------
  96
  97 Gets the last child of an element.
  98
  99 ### Example:
 100
 101         $$('p.foo !^')          // Gets the last child of <p class="foo">
 102         $$('p.foo !^ strong')   // Gets every <strong> that is the last element child of a <p class="foo">
 103
 104
 105
 106 Selector: checked {#Slick:checked}
 107 ----------------------------------
 108
 109 Matches all Elements that are checked.
 110
 111 ### Examples:
 112
 113         $$(':checked')
 114
 115         $('myForm').getElements('input:checked');
 116
 117
 118 Selector: enabled {#Slick:enabled}
 119 ----------------------------------
 120
 121 Matches all Elements that are enabled.
 122
 123 ### Examples:
 124
 125         $$(':enabled')
 126
 127         $('myElement').getElements(':enabled');
 128
 129
 130 Selector: empty {#Slick:empty}
 131 ------------------------------
 132
 133 Matches all elements which are empty.
 134
 135 ### Example:
 136
 137         $$(':empty');
 138
 139
 140 Selector: contains {#Slick:contains}
 141 ------------------------------------
 142
 143 Matches all the Elements which contains the text.
 144
 145 ### Variables:
 146
 147 * text - (string) The text that the Element should contain.
 148
 149 ### Example:
 150
 151         $$('p:contains("find me")');
 152
 153
 154 Selector: focus {#Slick:focus}
 155 ------------------------------
 156
 157 Gets the element in focus.
 158
 159 ### Example:
 160
 161         $$(':focus');           // Gets the element in focus
 162
 163
 164 Selector: not {#Slick:not}
 165 --------------------------
 166
 167 Matches all elements that do not match the selector.
 168
 169 <small>Note: The Slick implementation of the `:not` pseudoClass is a superset of the standard. i.e. it is more advanced than the specification.</small>
 170
 171 ### Examples:
 172
 173         $$(':not(div.foo)'); // all elements except divs with class 'foo'
 174
 175         $$('input:not([type="submit"])'); // all inputs except submit buttons
 176
 177         myElement.getElements(':not(a)');
 178
 179         $$(':not(ul li)');
 180
 181
 182 Selector: nth-child {#Slick:nth-child}
 183 --------------------------------------
 184
 185 Matches every nth child.
 186
 187 ### Usage:
 188
 189 Nth Expression:
 190
 191         ':nth-child(nExpression)'
 192
 193 ### Variables:
 194
 195 * nExpression - (string) A nth expression for the "every" nth-child.
 196
 197 ### Examples:
 198
 199         <span id="i1"></span>
 200         <span id="i2"></span>
 201         <span id="i3"></span>
 202         <span id="i4"></span>
 203         <span id="i5"></span>
 204
 205         $$(':nth-child(1)'); //Returns Element #i1.
 206
 207         $$(':nth-child(2n)'); //Returns Elements #i2 and #i4.
 208
 209         $$(':nth-child(2n+1)') //Returns Elements #i1, #i3 and #i5.
 210
 211         $$(':nth-child(3n+2)') //Returns Elements #i2 and #i5.
 212
 213
 214 Every Odd Child (same as 2n+1):
 215
 216         ':nth-child(odd)'
 217
 218 Every Even Child (same as 2n):
 219
 220         ':nth-child(even)'
 221
 222 ### Note:
 223
 224 This selector respects the w3c specifications, so it has 1 as its first index, not 0. Therefore nth-child(odd) will actually select the even children, if you think in zero-based indexes.
 225
 226
 227 Selector: nth-last-child {#Slick:nth-last-child}
 228 --------------------------------------
 229
 230 Matches every nth child, starting from the last child.
 231
 232 ### Usage:
 233
 234 Nth Expression:
 235
 236         ':nth-last-child(nExpression)'
 237
 238 ### Variables:
 239
 240 * nExpression - (string) A nth expression for the "every" nth-child.
 241
 242 ### Examples:
 243
 244         <span id="i1"></span>
 245         <span id="i2"></span>
 246         <span id="i3"></span>
 247         <span id="i4"></span>
 248         <span id="i5"></span>
 249
 250         $$(':nth-last-child(1)'); //Returns Element #i5.
 251
 252         $$(':nth-last-child(2n)'); //Returns Elements #i2 and #i4.
 253
 254         $$(':nth-last-child(2n+1)') //Returns Elements #i1, #i3 and #i5.
 255
 256         $$(':nth-last-child(3n+2)') //Returns Elements #i1 and #i4.
 257
 258 Every Odd Child (same as 2n+1):
 259
 260         ':nth-last-child(odd)'
 261
 262 Every Even Child  (same as 2n):
 263
 264         ':nth-last-child(even)'
 265
 266 ### Note:
 267
 268 This selector respects the w3c specifications, so it has 1 as its first index, not 0. Therefore nth-last-child(odd) will actually select the even last-children, if you think in zero-based indexes.
 269
 270
 271 Selector: even {#Slick:even}
 272 ----------------------------
 273
 274 Matches every even child.
 275
 276 ### Example:
 277
 278         $$('td:even');
 279
 280 ### Note:
 281
 282 This selector is not part of the w3c specification, therefore its index starts at 0. This selector is highly recommended over nth-child(even), as this will return the real even children.
 283
 284
 285 Selector: odd {#Slick:odd}
 286 --------------------------
 287
 288 Matches every odd child.
 289
 290 ### Example:
 291
 292         $$('td:odd');
 293
 294 ### Note:
 295
 296 This selector is not part of the w3c specification, therefore its index starts at 0. This selector is highly recommended over nth-child(odd), as this will return the real odd children.
 297
 298
 299 Selector: index {#Slick:index}
 300 ------------------------------
 301
 302 Matches the node at the specified index
 303
 304 ### Example:
 305
 306         $$('p:index(2)');               // Gets the third <p> tag.
 307
 308 ### Note:
 309
 310 This is zero-indexed.
 311
 312
 313 Selector: first-child {#Slick:first-child}
 314 ------------------------------------------
 315
 316 Matches the first child.
 317
 318 ### Usage:
 319
 320         ':first-child'
 321
 322 ### Example:
 323
 324         $$('td:first-child');
 325
 326
 327 Selector: last-child {#Slick:last-child}
 328 ----------------------------------------
 329
 330         Matches the last child.
 331
 332 ### Usage:
 333
 334         ':last-child'
 335
 336 ### Example:
 337
 338         $$('td:last-child');
 339
 340
 341 Selector: only-child {#Slick:only-child}
 342 ----------------------------------------
 343
 344 Matches an only child of its parent Element.
 345
 346 ### Usage:
 347
 348         ':only-child'
 349
 350 ### Example:
 351
 352         $$('td:only-child');
 353
 354
 355
 356 [Slick]: /core/Slick/Slick