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.2.1. ready

3.2.1.1. Synopsis

Execute a user-specified function once the document is loaded. No arguments are provided to the user-specified function.

$_.ready(callback)

3.2.1.2. Example

$_.ready(function() {
  // do something
})

3.3. Window-scope APIs

3.3.1. windowHeight

3.3.1.1. Synopsis

Returns the height of the browser window.

$_.windowHeight()

3.3.2. windowWidth

3.3.2.1. Synopsis

Returns the width of the browser window.

$_.windowWidth()

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.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
  }
})