3. API Documentation¶
3.1. browse.js wrapper¶
3.1.1. $_¶
3.1.1.1. Synopsis¶
Wraps the argument (should be a valid HTML element) into a browse.js
object and returns it.
function $_(element)
3.1.1.2. Example¶
var obj = $_(document.body)
// The above does the following:
// --> obj.element === document.body
// --> document.body.$_ === obj
3.1.1.3. Return Value¶
The browse.js
wrapper object. Returns null
if the argument passed is not a valid HTML element.
3.2. Document-scope APIs¶
3.3. Window-scope APIs¶
3.4. DOM Lookups¶
3.4.1. firstChild¶
3.4.1.1. Synopsis¶
Get the first HTML element child of a given HTML element. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.firstChild()
3.4.1.2. Example¶
<div id=my-div>
<div></div>
</div>
var div = $_(document.getElementById('my-div'))
var firstChild = div.firstChild()
3.4.1.3. Return Value¶
Returns browse.js
wrapper object of the first HTML element child if one exists. Returns null
otherwise.
3.4.2. lastChild¶
3.4.2.1. Synopsis¶
Get the last HTML element child of a given HTML element. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.lastChild()
3.4.2.2. Example¶
<div id=my-div>
<div></div>
</div>
var div = $_(document.getElementById('my-div'))
var lastChild = div.lastChild()
3.4.2.3. Return Value¶
Returns browse.js
wrapper object of the last HTML element child if one exists. Returns null
otherwise.
3.4.3. next¶
3.4.3.1. Synopsis¶
Get the next HTML element sibling of an HTML element. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.next()
3.4.3.2. Example¶
<div id=my-div></div>
<div></div>
var div = $_(document.getElementById('my-div'))
var next = div.next()
3.4.3.3. Return Value¶
Returns browse.js
wrapper object of the next HTML element sibling if one exists. Returns null
otherwise.
3.4.4. previous¶
3.4.4.1. Synopsis¶
Get the previous HTML element sibling of an HTML element. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.previous()
3.4.4.2. Example¶
<div></div>
<div id=my-div></div>
var div = $_(document.getElementById('my-div'))
var ret = div.previous()
3.4.4.3. Return Value¶
Returns browse.js
wrapper object of the previous HTML element sibling if one exists. Returns null
otherwise.
3.4.5. index¶
3.4.5.1. Synopsis¶
Gets the index (0-based) of an element relative to its parent. Called on the browse.js
object that wraps the HTML element the index of which is required.
browse.prototype.index()
3.4.5.2. Example¶
<div>
<div></div>
<p></p>
<div id=my-div></div>
</div>
var div = $_(document.getElementById('my-div'))
var idx = div.index() // --> 2
3.4.5.3. Return Value¶
Return a number.
3.4.6. nthChild¶
3.4.6.1. Synopsis¶
Get the nth child (0-based, so n=10 is 11th child) of a given HTML element. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.nthChild(n)
3.4.6.2. Example¶
<div id=parent-div>
<div></div>
<p></p>
<div id=my-div></div>
</div>
var div = $_(document.getElementById('parent-div'))
var nthChild = div.nthChild(2) // --> <div id=my-div></div>
3.4.6.3. Return Value¶
Returns browse.js
wrapper object of the nth child, if one exists. Returns null
otherwise.
3.5. DOM Tree Modification¶
3.5.1. append¶
3.5.1.1. Synopsis¶
Append given HTML into a given HTML element. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.append(htmlString)
3.5.1.2. Example¶
<div id=my-div></div>
var div = $_(document.getElementById('my-div'))
div.append('<div></div>')
Change in DOM after the above append
call (represented using HTML):
<div id=my-div>
<div></div>
</div>
3.5.1.3. Return Value¶
Returns the browse.js
wrapper object on which append
has been called. This can be used for chaining other API calls on this object e.g. obj.append(...).next()
.
3.5.2. prepend¶
3.5.2.1. Synopsis¶
Prepend given HTML into a given HTML element. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.prepend(htmlString)
3.5.2.2. Example¶
<div id=my-div></div>
var div = $_(document.getElementById('my-div'))
div.prepend('<div></div>')
Change in DOM after the above prepend
call (represented using HTML):
<div id=my-div>
<div></div>
</div>
3.5.2.3. Return Value¶
Returns the browse.js
wrapper object on which prepend
has been called. This can be used for chaining other API calls on this object e.g. obj.prepend(...).next()
.
3.5.3. after¶
3.5.3.1. Synopsis¶
Insert given HTML just after a given HTML element to create new siblings. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.after(htmlString)
3.5.3.2. Example¶
<div id=my-div></div>
var div = $_(document.getElementById('my-div'))
div.after('<div id=another></div>')
Change in DOM after the above after
call (represented using HTML):
<div id=my-div></div>
<div id=another></div>
3.5.3.3. Return Value¶
Returns the browse.js
wrapper object on which after
has been called. This can be used for chaining other API calls on this object e.g. obj.after(...).next()
.
3.5.4. before¶
3.5.4.1. Synopsis¶
Insert given HTML just before a given HTML element to create new siblings. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.before(htmlString)
3.5.4.2. Example¶
<div id=my-div></div>
var div = $_(document.getElementById('my-div'))
div.before('<div id=another></div>')
Change in DOM after the above before
call (represented using HTML):
<div id=another></div>
<div id=my-div></div>
3.5.4.3. Return Value¶
Returns the browse.js
wrapper object on which before
has been called. This can be used for chaining other API calls on this object e.g. obj.before(...).next()
.
3.5.5. remove¶
3.5.5.1. Synopsis¶
Removes an HTML element from DOM. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.remove()
3.5.5.2. Example¶
<div id=my-div></div>
<p></p>
var div = $_(document.getElementById('my-div'))
div.remove()
Change in DOM after the above remove
call (represented using HTML):
<p></p>
3.6. Element Dimensions & Position¶
3.6.1. height¶
3.6.1.1. Synopsis¶
Returns the visible height (in px) of an HTML element. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.height()
3.6.1.2. Example¶
<div id=my-div style=height:40px></div>
<img id=my-img height=40>
var div = $_(document.getElementById('my-div'))
div.height() // --> 40
var img = $_(document.getElementById('my-img'))
img.height() // --> 40
3.6.1.3. Return Value¶
A number that represents height of the given element in pixels (px unit).
3.6.2. width¶
3.6.2.1. Synopsis¶
Returns the visible width (in px) of an HTML element. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.width()
3.6.2.2. Example¶
<div id=my-div style=width:40px></div>
<img id=my-img width=40>
var div = $_(document.getElementById('my-div'))
div.width() // --> 40
var img = $_(document.getElementById('my-img'))
img.width() // --> 40
3.6.2.3. Return Value¶
A number that represents width of the given element in pixels (px unit).
3.6.3. innerHeight¶
3.6.3.1. Synopsis¶
Returns the height (in px) of an HTML element’s contents. It is different from the visible height when the element has a vertical scroll bar. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.innerHeight()
3.6.3.2. Example¶
<div id=my-div style=max-height:20px;overflow:scroll><!-- some contents here --></div>
var div = $_(document.getElementById('my-div'))
div.innerHeight() // --> 47 (randomly picked)
div.height() // --> 20
3.6.3.3. Return Value¶
A number that represents inner height of the given element in pixels (px unit).
3.6.4. innerWidth¶
3.6.4.1. Synopsis¶
Returns the width (in px) of an HTML element’s contents. It is different from the visible width when the element has a horizontal scroll bar. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.innerWidth()
3.6.4.2. Example¶
<div id=my-div style=max-width:20px;overflow:scroll><!-- some contents here --></div>
var div = $_(document.getElementById('my-div'))
div.innerWidth() // --> 83 (randomly picked)
div.width() // --> 20
3.6.4.3. Return Value¶
A number that represents inner width of the given element in pixels (px unit).
3.6.5. topLeft¶
3.6.5.1. Synopsis¶
Returns the position of an HTML element, relative to the document’s top-left corner (not relative to window’s top-left).
browse.topLeft()
3.6.5.2. Example¶
<div id=my-div</div>
var div = $_(document.getElementById('my-div'))
var topLeft = div.topLeft() // --> { top: 106, left: 203 }
3.6.5.3. Return Value¶
An object of the following format:
{ top: <Number>, left: <Number> }
For example:
{ top: 33, left: 121 }
3.7. Element Attributes¶
browse.js
has no APIs to access the attributes and it is recommended to use getAttribute
, hasAttribute
, setAttribute
and removeAttribute
DOM APIs that are available widely.
However; there are some attributes that have implementation-specific differences across browsers, and APIs have been provided for them.
3.7.1. getClass¶
3.7.1.1. Synopsis¶
Get the value of the class
attribute of an HTML element. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.getClass()
3.7.1.2. Example¶
<div class="my-class-1 my-class-2" id=my-div></div>
var div = $_(document.getElementById('my-div'))
div.getClass() // --> "my-class-1 my-class-2"
3.7.1.3. Return Value¶
A string which contains the value of the class
attribute of the element.
3.7.2. hasClass¶
3.7.2.1. Synopsis¶
Checks if an HTML element has the given argument class. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.hasClass(className)
3.7.2.2. Example¶
<div class="my-class-1 my-class-2" id=my-div></div>
var div = $_(document.getElementById('my-div'))
div.hasClass('my-class-1') // --> true
div.hasClass('my-class-abc') // --> false
3.7.2.3. Return Value¶
A boolean. True if argument class exists. False otherwise.
3.7.3. addClass¶
3.7.3.1. Synopsis¶
Adds the argument class to an HTML element (if it did not exist already). Called on the browse.js
object that wraps the given HTML element.
browse.prototype.addClass(className)
3.7.3.2. Example¶
<div id=my-div></div>
var div = $_(document.getElementById('my-div'))
div.addClass('my-class-1')
Change in DOM after the above addClass
call (represented using HTML):
<div id=my-div class=my-class-1></div>
3.7.3.3. Return Value¶
Returns the browse.js
wrapper object on which addClass
has been called. This can be used for chaining other API calls on this object e.g. obj.addClass(...).next()
.
3.7.4. removeClass¶
3.7.4.1. Synopsis¶
Removes the argument class to an HTML element (if it exists). Called on the browse.js
object that wraps the given HTML element.
browse.prototype.removeClass(className)
3.7.4.2. Example¶
<div id=my-div class=my-class></div>
var div = $_(document.getElementById('my-div'))
div.removeClass('my-class')
Change in DOM after the above removeClass
call (represented using HTML):
<div id=my-div class=""></div>
3.7.4.3. Return Value¶
Returns the browse.js
wrapper object on which removeClass
has been called. This can be used for chaining other API calls on this object e.g. obj.removeClass(...).next()
.
3.8. Working with Input Controls¶
3.8.1. value¶
3.8.1.1. Synopsis¶
Used to get and set the value of an input control HTML element (all input
types, select
, option
, and textarea
). Called on the browse.js
object that wraps the given HTML element.
browse.prototype.value()
browse.prototype.value(someValue)
3.8.1.2. Example¶
<input type=text name=text id=text value=10>
var text = $_(document.getElementById('text'))
text.value() // --> '10'
text.value('abc')
Change in DOM after the above value
call to set the value of an input control (represented using HTML):
<input type=text name=text id=text value=abc>
3.8.1.3. Return Value¶
Returns the value of the input control element (a String) when value
is called without an argument.
Returns the browse.js
wrapper object on which value
has been called, in case called with an argument. This can be used for chaining other API calls on this object e.g. obj.value(...).next()
.
3.9. Style Access & Manipulation¶
3.9.1. hide¶
3.9.1.1. Synopsis¶
Hides the given HTML element by setting its display
style property appropriately. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.hide()
3.9.1.2. Example¶
<div id=my-div></div>
var div = $_(document.getElementById('my-div'))
div.hide()
Change in DOM after calling hide
above (represented as HTML):
<div id=my-div style=display:none></div>
3.9.1.3. Return Value¶
Returns the browse.js
wrapper object on which hide
has been called. This can be used for chaining other API calls on this object e.g. obj.hide(...).next()
.
3.9.2. show¶
3.9.2.1. Synopsis¶
Shows a hidden HTML element by setting its display
style property appropriately. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.show()
3.9.2.2. Example¶
<div id=my-div style=display:none></div>
var div = $_(document.getElementById('my-div'))
div.show()
Change in DOM after calling show
above (represented as HTML):
<div id=my-div></div>
3.9.2.3. Return Value¶
Returns the browse.js
wrapper object on which show
has been called. This can be used for chaining other API calls on this object e.g. obj.show(...).next()
.
3.9.3. opacity¶
3.9.3.1. Synopsis¶
Sets and gets opacity of an HTML element. Called on the browse.js
object that wraps the given HTML element.
browse.prototype.opacity()
browse.prototype.opacity(opacityVal)
3.9.3.2. Example¶
<div id=my-div></div>
var div = $_(document.getElementById('my-div'))
var opacity = div.opacity() // --> 1.0
div.opacity(0.4)
Change in DOM after calling opacity
above to set the opacity (represented as HTML):
<div id=my-div style=opacity:0.4></div> // most browsers
<div id=my-div style="filter:alpha(opacity=40)"></div> // old IE
3.9.3.3. Return Value¶
Returns the opacity (decimal number) of the element when called without any arguments.
Returns the browse.js
wrapper object on which opacity
has been called, in case called with an argument. This can be used for chaining other API calls on this object e.g. obj.opacity(...).next()
.
3.9.4. style¶
3.9.4.1. Synopsis¶
Sets and gets style properties of an HTML element. Called on the browse.js
object that wraps the given HTML element.
NOTE: The specific methods hide
, show
, and opacity
defined above should be used for their respective purpose, rather than using this method to set/get the style properties involved (display
, and opacity
/filter
).
browse.prototype.style(property)
browse.prototype.style(property, value)
3.9.4.2. Example¶
<div id=my-div style=color:red></div>
var div = $_(document.getElementById('my-div'))
var color = div.style('color') // --> 'red'
div.style('color', 'blue')
div.style('width', '20px')
Change in DOM after calling style
above to set style properties (represented as HTML):
<div id=my-div style=color:blue;width:20px></div>
3.9.4.3. Return Value¶
Returns a style property when called with only the 1st argument property
.
Returns the browse.js
wrapper object on which style
has been called, in case called with two arguments. This can be used for chaining other API calls on this object e.g. obj.style(...).next()
.
3.10. Animation¶
Following animation modes are supported across all animation APIs:
linear
(default)swing
easeInQuadratic
easeOutQuadratic
3.10.1. fadeOut¶
3.10.1.1. Synopsis¶
Fades out an HTML element in given duration
(milliseconds) using the provided animation mode
(optional) and invokes user-provided callback
once done. The default mode
is linear
. No arguments are passed to the callback
.
browse.prototype.fadeOut(duration, callback)
browse.prototype.fadeOut(duration, mode, callback)
3.10.1.2. Example¶
<div id=my-div></div>
var div = $_(document.getElementById('my-div'))
div.fadeOut(300, function() {
// do something
})
div.fadeOut(300, 'swing', function() {
// do something
})
Change in DOM after invoking any of the fadeOut
calls above (represented as HTML):
<div id=my-div style=display:none;opacity:0></div>
3.10.1.3. Return Value¶
Returns the browse.js
wrapper object on which fadeOut
has been called, in case called with two arguments. This can be used for chaining other API calls on this object e.g. obj.fadeOut(...).next()
.
3.10.2. fadeIn¶
3.10.2.1. Synopsis¶
Fades in an HTML element in given duration
(milliseconds) using the provided animation mode
(optional) and invokes user-provided callback
once done. The default mode
is linear
. No arguments are passed to the callback
.
browse.prototype.fadeIn(duration, callback)
browse.prototype.fadeIn(duration, mode, callback)
3.10.2.2. Example¶
<div id=my-div style=display:none;opacity:0></div>
var div = $_(document.getElementById('my-div'))
div.fadeIn(300, function() {
// do something
})
div.fadeIn(300, 'easeInQuadratic', function() {
// do something
})
Change in DOM after invoking any of the fadeIn
calls above (represented as HTML):
<div id=my-div style=opacity:1></div>
3.10.2.3. Return Value¶
Returns the browse.js
wrapper object on which fadeIn
has been called, in case called with two arguments. This can be used for chaining other API calls on this object e.g. obj.fadeIn(...).next()
.
3.10.3. scrollY¶
3.10.3.1. Synopsis¶
Scrolls the window to given toY
position in given duration
(milliseconds) using the provided animation mode
(optional) and invokes user-provided callback
once done. No arguments are passed to the callback
.
$_.scrollY(toY, duration, callback)
$_.scrollY(toY, duration, mode, callback)
3.10.3.2. Example¶
$_.scrollY(100, 2000, function() {
// do something
})
$_.scrollY(100, 2000, 'easeOutQuadratic', function() {
// do something
})
3.11. Events¶
3.11.1. onclick¶
3.11.1.1. Synopsis¶
Binds a handler function to an HTML element or document
for the click
event. An event
argument is passed to the callback
.
browse.prototype.onclick(callback)
$_.onclick(callback)
3.11.1.2. Example¶
<input type=submit name=submit id=submit>
var submit = $_(document.getElementById('submit'))
submit.onclick(function(e){
// do something
})
$_.onclick(function(e){
// do something when document receives a click
}
3.11.1.3. Return Value¶
The version used to bind a handler to document
does not return anything.
The version used to bind a handler to an HTML element returns the browse.js
wrapper object on which onclick
has been called, in case called with two arguments. This can be used for chaining other API calls on this object e.g. obj.onclick(...).next()
.
3.11.2. onkeyup¶
3.11.2.1. Synopsis¶
Binds a handler function to an HTML element or document
for the keyup
event. An event
argument is passed to the callback
.
browse.prototype.onkeyup(callback)
$_.onkeyup(callback)
3.11.2.2. Example¶
<input type=text name=text id=text value=10>
var text = $_(document.getElementById('text'))
text.onkeyup(function(e){
// do something
})
$_.onkeyup(function(e){
// do something when document receives a keyup
})
3.11.2.3. Return Value¶
The version used to bind a handler to document
does not return anything.
The version used to bind a handler to an HTML element returns the browse.js
wrapper object on which onkeyup
has been called, in case called with two arguments. This can be used for chaining other API calls on this object e.g. obj.onkeyup(...).next()
.
3.11.3. onchange¶
3.11.3.1. Synopsis¶
Binds a handler function to an HTML element or document
for the change
event. No arguments are passed to the callback
.
browse.prototype.onchange(callback)
$_.onkeyup(callback)
3.11.3.2. Example¶
<input type=text name=text id=text value=10>
var text = $_(document.getElementById('text'))
text.onchange(function(){
// do something
})
$_.onchange(function(){
// do something when document receives a change
})
3.11.3.3. Return Value¶
The version used to bind a handler to document
does not return anything.
The version used to bind a handler to an HTML element returns the browse.js
wrapper object on which onchange
has been called, in case called with two arguments. This can be used for chaining other API calls on this object e.g. obj.onchange(...).next()
.
3.11.4. trigger¶
3.11.4.1. Synopsis¶
Triggers an event on an HTML element or document
. Currently, following events can be triggered:
click
keyup
change
browse.prototype.trigger('change')
browse.prototype.trigger('keyup'||'click', event)
$_.trigger('change')
$_.trigger('keyup'||'click', event)
3.11.4.2. Example¶
<input type=text name=text id=text value=10>
<input type=submit name=submit id=submit>
var text = $_(document.getElementById('text'))
text.trigger('change')
text.trigger('keyup', {keyCode: 2})
var submit = $_(document.getElementById('submit'))
submit.trigger('click', {button: 1, ctrlKey: true})
$_.trigger('change')
$_.trigger('keyup', {keyCode: 2})
$_.trigger('click', {button: 1, ctrlKey: true})
Pending Documentation: Specification of the event parameters for different event types.
3.11.4.3. Return Value¶
The version used with document
does not return anything.
The version used with an HTML element returns the browse.js
wrapper object on which trigger
has been called, in case called with two arguments. This can be used for chaining other API calls on this object e.g. obj.trigger(...).next()
.
3.12. AJAX¶
3.12.1. ajax¶
3.12.1.1. Synopsis¶
Performs an AJAX request to specified url
while applying the options
provided.
$_.ajax(url, options)
Allowed keys and values in the argument options
object are as follows:
Name | Required? | Default | Allowed Values | Description |
---|---|---|---|---|
method |
Yes | None | GET
POST
PATCH
PUT
DELETE
OPTIONS
HEAD |
Uppercase name of HTTP verb/method to be used |
success |
Yes | None | A function to call once there is a
2XX status. Expected signature:
function(data, status, url, xhr) |
|
error |
Yes | None | A function to call once there is an
error status. Expected signature:
function(err, status, url, xhr) |
|
timeout |
No | None | If provided, a timeout of given milliseconds is applied to the request | |
headers |
No | None | An object containing headers to add to the HTTP request | |
contentType |
No | application/x-www-form-urlencoed; charset=utf-8 | application/x-www-form-urlencoded; charsett=utf-8 multipart/form-data; charset=utf-8 application/json; charset=utf-8 |
Desired value for Content-type
header. NOTE: Do not add this
header in headers if using the
contentType key. |
data |
No | None | String
Object |
The data to send with a request like
POST , PATCH , and PUT .
It is ignored for GET , HEAD ,
and OPTIONS . |
format |
No | None | json
xml |
The response body is parsed as per
the format specified and passed as
data parameter of success
callback, or as err parameter of
error callback. |
cache |
No | false |
Boolean |
If it is true , a nonce is added
to the URL to avoid response caching
in the server. |
3.12.1.2. Example¶
Sending a GET request with caching in server disallowed, a timeout of 5 seconds, and JSON being the expected format of response data:
$_.ajax('http://myhost.com/', {
method: 'GET',
cache: false,
timeout: 5000,
format: 'json',
success: function(response, status, url, xhr) {
// do something
},
error: function(error, status, url, xhr) {
// do something
}
})
Sending a POST request that should send stringized JSON data created using the input data provided:
$_.ajax('http://myhost.com/', {
method: 'POST',
data: {a: 1, b: 2},
contentType: 'application/json; charset=utf-8',
timeout: 5000,
success: function(response, status, url, xhr) {
// do something
},
error: function(error, status, url, xhr) {
// do something
}
})
Sending files using multipart/form-data
:
<form id=my-form enctype=multipart/form-data>
<input type=file name=file>
</form>
$_.ajax('http://myhost.com/', {
method: 'POST',
data: document.getElementById('my-form'),
contentType: 'multipart/form-data; charset=utf-8',
timeout: 5000,
success: function(response, status, url, xhr) {
// do something
},
error: function(error, status, url, xhr) {
// do something
}
})