jcoola web-api is a very light and robust client-side javascript core framework for desktop and mobile web development.
Download:
 |
A Simple Mobile Accordion Menu Live Demo, check the page source and documentation. |
Getting Started:
jcoola selectors are used to intelligently select the right nodes to be used for further operations that can be bound on a single jcoola statement. Selector phase starts with q(param), and based on the param the desired nodes are sifted to be used with the jcoola object.
Returns the jcoola object that can be operated on the element or an array of elements.
Note: The shortcut 'qp' can be used to get the element reference: var el1 = qp('id1'), el2 = qp('id2');
Constructing a jcoola object feeding the elements: q(el1); q([el1,el2]);
Note: An array of element identifiers (or a combination of them) can also be passed: q([ 'id1','id2' ]); or q([ 'id1',el2 ]);
Note: In some scenarios there is a need to have direct access to html nodes within the jcoola object, the 'elem' array on the jcoola object contains all the node references: q([el1,el2]).elem[0].id;
Returns the jcoola object that can be operated on an element that has the identifier. q('id1');
Is used to select similar identifiers that are similar from the beginning q('name*'), from the end q('*name'), or variable in the middle q('name1*name2').
- ex 1: q('name*'); // name1, named, name2 , ...
- ex 2: q('*name'); // Xname, Yname, Zname , ...
- ex 3: q('n1*n2'); // n1Xn2, n1Yn2, n1Zn2 , ...
Selects all the elements: q('*');
Selects the elements whose atribute and the corresponding value matches the provided value.
Pattern: q('atrib=value')
- ex 1: q('title=welcome');
- ex 2: q('class=class1');
- ex 3: q('dir=ltr');
Note: *Filter can be used in the value part of EQ-Atrib.
- ex 1: q('id=div*') // div1, div_body, div_footer , ...
- ex 2: q('title=Welcome*') // Selects those elements whose title starts with 'Welcome' ...
Note: Regular Expresion (RE-Filter) can be used in the value part of EQ-Atrib.
Pattern: q('atrib=(regular expresion)')
- ex : q('id=(^a.*z$)') // Selects the elements whose id begins with the character 'a' and ends with 'z' ...
Selects the element whose atrib's value is greater than the provided value.
Pattern: q('atrib > value')
- ex 1: q('id > 2') // div3, div4, div5_body , ...
- ex 2: q('width > 2') // Selects elements whose width atrib has the value greater than 2
Selects the element whose atrib's value is less than the provided value.
Pattern: q('atrib < value')
- ex: q('id < 5') // div4, div3, ...
Note: *Filter and RE-Filter cannot be used with the LT-Atrib and GT-Atrib.
Selects the tags by tag type.
Pattern: q('<TAG>')
- ex: q('<span>'); q('<img>'); // Selects all the span tags, img tags.
Selects the elements that have the related css class assgined.
Pattern: q('.classes')
- ex 1: q('.class1'); // Selects the elements that have class1 assigned as their css class.
- ex 2: q('.class1 class2'); // Selects the elements that have class1 or class2 assigned.
Pattern: q('c: text [slash-star]')
Selects elements that contain the related text. Note that the default search would be in the first-level depth, if an all-level depth search is required then use '/*' at the end.
- <div>First-Level-Text<span>Second-Level-Text<div>Third-Level-Text</div>Second-Level-Text</span>First-Level-Text</div>
The following example, selects the elements that contain the text 'foo' in the first tag-level:
- q('c: foo');
In this example, the elements that contain the text 'foo' in all tag-levels of 'div1' element are filtered:
- q('div1').sift('c: foo /*');
Note: In addition to Selector C-Colon, jcoola method contains() can be used, but the difference is that Selector C-Colon can be used in several methods that accept selector -such as sift(), join() and etc., but the contains() method can only be applied to the queried/sifted elements.
jcoola methods operate on the elements that have been sifted by jcoola selectors.
Pattern: q().loaded( func )
It is a good practice to let the browser finish downloading all the required document data before doing anything else. The 'loaded' method is invoked right after the document loaded.
- q().loaded( function(){ // other jcoola operations or custom codes });
Note: q() is used to get access to native methods.
Pattern: .name( func [,add])
Some of jcoola methods are event methods meaning that they will be invoked as soon as the event occurs on the element. If you need to add it to the execution queue(invokation list)- pass the third param the boolean 'true'.
List of events: blur, change, copy, cut, paste, select, click, dblclick, contextmenu, error, focus, keydown, keypress, keyup, load, unload, mousedown, mouseup, mousemove, mouseover, mouseout, mousewheel, reset, submit, resize, scroll
The following statement get's the html element 'div1' and sets two events on it so that when they occur, the related functions are invoked.
- q('div1').click(function() { alert('clicked '+ this.id); });
- q('div1').contextmenu(function() { alert('right-clicked '+ this.id); });
The above two statements can be combined into one simple statement:
- q('div1').click(function() { alert('clicked '+ this.id); }).contextmenu(function() { alert('right-clicked '+ this.id); });
In all events, 'cq' and 'e' scope variables can be used. 'cq' for jcoola object, and 'e' contains information about the event:
- q('Container*').click( function(){ alert( this.id + ' count:' + cq.elem.length + ' event:' + e.type ); } );
Pattern: .event('name', func [,add])
The event() method is used for the events which are not defined in the event list. Simply give the event name and the desired function, and if you want to add it to the execution queue- pass the third param the boolean 'true'.
Note: The execution queue as its name implies, contains multiple functions to be invoked when the event it fired. And passing the third argument as 'true', enrolls the function to the execution queue and therefore it's not replaced with the old function (if any defined on the element).
The first statement defines a 'click' event on the element:
- q('<a>').event('click', function() { alert(this.id); } );
The second statement will execute both of the defined functions since they are added to the queue:
- q('<a>').event('click', function() { alert('1'); }, true).event('click', function() { alert('2'); }, true);
To get access to the jcoola shortcut object within a function that is passed to a jcoola method, use 'cq'.
Note: 'cq' is only accessible inside the function that is passed to a jcoola method. 'cq' contains the filtered or sifted elements that has been chosen by jcoola selectors and has jcoola methods that can be used to operate on the elements.
The following statement sets the click event on the elements that start with 'ChildB' and the shortcut 'cq' contains the elements alreay queried:
- q('ChildB*').click(function() { for(i=0; i< cq.elem.length; i++) alert('id:'+ cq.elem[i].id); });
Note: In case you have nested mechanism or methods, each 'cq' is in its own jcoola method scope:
Pattern: .apply( func [,delay])
Element code execution is done using the jcoola method 'apply', the first param is the function to be executed and the second param is specified when a delay in milliseconds is desired.
Suppose you're going to assign a click event on every html element whose 'type' attribute is set to 'button' (input button type) and when clicked, a specific function be executed on every 'li' element in the web page that 'li' values be shown using 'alert'.
The first code snippet accomplishes this using regular jcoola code:
The next code, accomplishes it using jcool 'apply' method which is used to execute code:
Note: To execute code on the fly, use native jcoola q(). The following code, executes a function with a four-second optional delay param:
- q().apply( function() { alert('native apply...'); }, 4000);
Pattern: .sift(selector)
The sift() method is used when a subset of elements needs to be filtered out, the same selector rules applies to sift() as it is for q().
The following code snippet shows how to employ sift() to filter out mailto link anchor elements:
The above statement could have been written as:
- q('<a>').sift('href = mailto:*').style('background-color : black;');
Firstly, the anchor tags are selected and secondly they are filtered out by those whose href attribute values start with 'mailto:', and then a statement applies a specific style on them. Again, 'cq' is a shortcut to jcoola object, and it could have been written as 'q('<a>').sift('href = mailto:*')', but 'cq' is optimized and is better to be used instead of the whole query method.
Pattern: .join(selector)
The join() method is used to join query results; so element sets would be united into one element set.
The following code snippet firstly finds elements whose title attribute has valid email address and joins the elements to the next query which finds the elements that their identifier starts with 'addr'. And a statement is applied to all the elements and sets a style on them:
Pattern: .disjoin(selector)
The disjoin() method is used to remove the queried elements from the element set.
The following example firstly finds elements whose id attributes start with 'id' and then disjoins the elements that their 'id' attribute is less than 3 (like 'id2','id1') and would show the resulted elements:
- q('id*').disjoin("id<3").apply( function(){ alert(this.id); });
Pattern: .contains(text [,all])
The contains() method filters the elements from the element set that have the related text inside them.
The following snippet selects the elements that contain the text 'mat':
- q('*').contains('mat').apply( function(){ alert(this.id); } );
Note: Only direct(first-level) text nodes between the beginning tag and the ending tag of the elements are processed, if full-level search is needed, then pass the second parameter a boolean 'true'.
- <div>First-Level-Text<span>Second-Level-Text<div>Third-Level-Text</div>Second-Level-Text</span>First-Level-Text</div>
Pattern: .first(), .last()
Filters the first or the last element.
- q('id*').first().apply( function(){ alert(this.id);} );
Pattern: item(index), between(index,index)
Filters the elements based on the index range.
- q('id*').between(0,3).item(0).apply( function(){ alert(this.id);} );
Pattern Get: .html():string
Pattern Set: .html( htm [,totop])
Gets or sets the HTML contents of the element.
Note: If you need to add the html to the element's current html content, simply set the second param to a boolean value (true: added to the top).
- q('l*').click( function(){ alert(q(this).html()); });
Pattern Get: .text():string
Pattern Set: .text( txt [,totop])
Gets or sets the text contents of the element.
Note: If you need to add the text to the element's current text content, simply set the second param to a boolean value (true: added to the top).
Pattern: .show([func])
Shows the selected elements. The first param is a conditional predicate function that returns boolean, based on the value, the elements are considered to be shown.
- q('l*').show(function(){ return this.style.visibility == 'hidden'; });
Pattern: .hide([func,preserve])
Hides the selected elements. The first param is a conditional predicate function that returns boolean, based on the value, the elements are considered to be hidden. The second param, if passed boolean true, will preserve the hidden element's space after hiding it.
- q('l*').hide(function(){ return this.style.visibility == '' || this.style.visibility == 'visible'; });
Pattern: .toggle([func,preserve])
Toggles between the 'visible' and 'hidden' states.
The first param is a conditional predicate function that returns boolean, based on the value, the elements are considered to be shown or hidden. The second param, if passed boolean true, will preserve the hidden element's space after hiding it.
Pattern: .class([+/-] list)
Replaces, adds or removes css classes of elements. If no sign of '+' or '-' is mentioned at the start of the list, then the css classes will be replaced with old values. If '+' is used at the beginning, then the classes will be added, and if '-' used, all the mentioned classes will be removed from elements.
- q('l*').class('class1 class2');
- q('l*').class('+ class3 class4');
- q('l*').class('- class2 class1');
Pattern: .iterate(func [,order])
Iterates through the elements and provides the 'item' object and 'cq' variable to the scope. The 'item' object contains the element (item.e) and the index(item.index) in which it's being processed and 'cq' is jcoola object. In order to have a descending iteration, pass the second parameter a boolean true.
Pattern Get: .style('name'):string
Pattern Set: .style('name:value;...' | array | object)
Is used to set/get style members.
Pattern: .cstyle('name'):string
Is used to get the computed-value of a style member.
Pattern Get: .value('name'):string
Pattern Set: .value('name','value' | object)
Use this method to get/set the value of the attributes.
Note: To set the 'value' attribute of the form elements use form() method.
- Get: alert(q('img1').value('src'));
- Set: q('img2').value('alt','image2');
- Set: q('img2').value({'alt':'image2'});
Pattern Get: .form(): string | array
Pattern Set: .form('value' | array)
Use this method to get/set the value of form elements, such as input fields, button, radio button, check boxes.
Note: Form elements are not usually handled by identifier at the server-side; instead , a common 'name' attribute is used to be processed in the server-side query string. By default jcoola uses 'id' of the elements to query, but does support this situation(those elements having 'name' attribute) in a limited manner by just allowing the name attribute be simply stated for query (but not mergable with other filters), as in q('rd_button_name'). But, jcoola allows you to write more complex against the 'name' attribute by using it as an EQ-Atrib selector syntax, then you can combine the filter with other allowed filters in that context of the selector, as in q('name=rd_group*'). You must use and set 'name' attribute when dealing with form input elements, and not use/set 'id' attributes on form input elements since this will not work when you're dealing with option-input and checkbox-set, because when dealing with them as a group, the attribute 'id' cannot be repeated and must be unique -so you have to group them using 'name'. Another reason is that most of the server-side scripts use 'name' to process form elements from the query string.
Note: Checkboxes can get/set multiple values (array of values). For that, for checkboxes the get signature would yeild an array. The same goes for set signature, they can set multiple values using an array of values.
- Get: alert(q('rd_btn').form());
- Set: q('chk_box').form('0');
- Set: q('chk_box').form(['3','4']);
Pattern: .ajax(url, [data, oncomplete, onerror])
An ajax request to call the url to complete an action or to download data from the current domain.
Note: The parameter 'data' is optional and contains the payload to be sent along with the request. There are two callback functions: 'oncomplete' is invoked when the ajax request is done successfuly, 'onerror' is called back when some error occurs during the process, like the time the resource is not available, or time-outs.
The following statement, processes the url and loads the result into 'div1' element:
- q('div1').ajax('http://127.0.0.1:8020/status.php');
Pattern: .node_child()
Sets the jcoola element set to the child nodes of the current element set so that you can operate on the children using jcoola methods.
- q('div_p*').node_child().iterate(function(){ alert('child:' + item.e.id); });
Pattern: .node_parent()
Sets the jcoola element set to the parent nodes of the current element set so that you can operate on the parent nodes using jcoola methods.
- q('div_c*').node_parent().iterate(function(){ alert('parent:' + item.e.id); });
Pattern: .node_sibling()
Sets the jcoola element set to the sibling nodes of the current element set so that you can operate on the sibling nodes using jcoola methods.
- q('div_sx*').node_sibling().iterate(function(){ alert('sibling:' + item.e.id); });
Pattern: .node_next()
Sets the jcoola element set to the next nodes of the current element set so that you can operate on the next nodes using jcoola methods.
- q('div_question*').node_next().iterate(function(){ alert('next:' + item.e.id); });
Pattern: .node_prev()
Sets the jcoola element set to the previous nodes of the current element set so that you can operate on the previous nodes using jcoola methods.
- q('div_question*').node_prev().iterate(function(){ alert('previous:' + item.e.id); });
Pattern: .node_add(tag, [atrib, text, to-top])
Adds a new html element to the current jcoola memeber's nodes.
- q('div_board').node_add('p', {'id':'news1','style':'color:orange;'}, 'news1');
Pattern: .node_move(destination-ref, [to-top])
Moves the current element set nodes to the destination node. Destination reference could be q('id').elem[0] or can be resolved directly using qp('id'). To prepend the item set to-top argument to true.
- q('div_item*').node_move(qp('div_board'));
Pattern: .node_remove([just-children])
Removes the current element set nodes. Set the second parameter to boolean 'true' when you only want to remove the children of the elements.
- q('div_item*').node_remove();
Pattern: .node_replace(element-ref)
Replaces the current element set nodes with an element.
- q('div_item2').node_replace(qp('div_item1'));
team at jcoola.com