CanJS

  • page
canjs  

This is the detailed documentation of the API for CanJS, a framework for building web applications that provides a lightweight inheritance system, observable objects and values, and a powerful MVC core with live-bound templates, among other resources.

If you are just starting with CanJS, you may want to try our getting started guide.

CanJS is composed of modules on the left. The following are typically distributed as part of the core framework:

The following modules are typically distributed as plugins:

You can use it out of the box on top of jQuery, Zepto, YUI, and Mootools, and it's only 13K.

new can.Construct([args..])

Create a new instance of a constructor function.

can.Construct([name,] [staticProperties,] instanceProperties)

Creates a new extended constructor function.

can.Construct([args...])

Create a new instance of a constructor function if constructorExtends is false.

construct.init(...args)

Called when a new instance of a can.Construct is created.

construct.setup(...args)

A setup function for the instantiation of a constructor function.

can.Construct.extend([name,] [staticProperties,] instanceProperties)

Extends `can.Construct`, or constructor functions derived from `can.Construct`, to create a new constructor function.

can.Construct.newInstance([...args])

Returns an instance of `can.Construct`.

can.Construct.setup(base, fullName, staticProps, protoProps)

A static `setup` method provides inheritable setup functionality for a Constructor function.

can.Construct.proxy(callback, [...args])

Creates a static callback function that has `this` set to the constructor function.

construct.proxy(callback, [...args])

Creates a static callback function that has `this` set to an instance of the constructor function.

construct._super([...args])

Calls the base constructor function's method.

can.Control( [staticProperties,] instanceProperties )

Create a new, extended, control constructor function.

new can.Control( element, options )

Create an instance of a control.

control.destroy()

Prepares a control for garbage collection and is a place to reset any changes the control has made.

control.on([el,] selector, eventName, func)

Bind an event handler to a Control, or rebind all event handlers on a Control.

control.on()

Rebind all of a control's event handlers.

control.setup(element, options)

Perform pre-initialization logic.

can.Control.extend( [staticProperties,] instanceProperties )

Create a new, extended, control constructor function.

update(newOptions)

Reconfigure a control.

jQuery.fn.control([type])

Get the Control associated with elements.

jQuery.fn.controls([type])

Get the Controls associated with elements.

new can.EJS(options)

Creates an EmbeddedJS template.

ejs.render(data[, helpers])

Render a view object with data and helpers.

<% CODE %>

Runs JavaScript Code.

<%= CODE %>

Runs JS Code and writes the _escaped_ result into the result of the template.

<%== CODE %>

Runs JS Code and writes the _unescaped_ result into the result of the template.

<%% CODE %>

Renders <% CODE %> as text in result of the template rather than running CODE itself.

<%# CODE %>

Used for explicitly for comments.

new can.Model([options])

Creates a new instance of _ModelConstructor_.

model.bind(eventName, handler)

Listen to events on this Model.

model.destroy([success[, error]])

Destroy a Model on the server.

model.isNew()

Check if a Model has yet to be saved on the server.

model.save([success[, error]])

Save a model back to the server.

model.unbind(eventName[, handler])

Stop listening to events on this Model.

can.Model.bind(eventType, handler)

Listen for events on a Model class.

can.Model.create: function(serialized) -> seferred

Specify a function to create persistent instances.

can.Model.create: "[METHOD] /path/to/resource"

Specify a HTTP method and url to create persistent instances.

can.Model.create: {ajaxSettings}

Specify an options object that is used to make a HTTP request to create persistent instances.

can.Model.destroy: function(id) -> deferred

If you provide a function, the Model will expect you to do your own AJAX requests.

can.Model.destroy: "[METHOD] /path/to/resource"

If you provide a URL, the Model will send a request to that URL using the method specified (or DELETE if none is specified) when deleting an instance on the server.

can.Model.findAll( params[, success[, error]] )

Retrieve multiple resources from a server.

can.Model.findAll: "[METHOD] /path/to/resource"

Implements `findAll` with a HTTP method and url to retrieve instance data.

can.Model.findOne( params[, success[, error]] )

Retrieve a single instance from the server.

can.Model.findOne: "[METHOD] /path/to/resource"

Implements `findOne` with a HTTP method and url to retrieve an instance's data.

can.Model.makeFindAll: function(findAllData) -> findAll

Returns the external `findAll` method given the implemented findAllData function.

can.Model.makeFindOne: function(findOneData) -> findOne

Returns the external `findOne` method given the implemented findOneData function.

can.Model.model(data)

Convert raw data into a can.Model instance.

can.Model.models(data[, oldList])

Convert raw data into can.Model instances.

can.Model.unbind(eventType, handler)

Stop listening for events on a Model class.

can.Model.update: "[METHOD] /path/to/resource"

If you provide a URL, the Model will send a request to that URL using the method specified (or PUT if none is specified) when updating an instance on the server.

can.Model.update: function(id, serialized) -> can.Deffered

If you provide a function, the Model will expect you to do your own AJAX requests.

new can.Mustache(options)

Creates an instance of a mustache template.

{{key}}

Insert the value of the key into the output of the template.

{{{key}}}

Behaves just like {{key}} and {{helper}} but does not escape the result.

{{&key}}

The `{{&key}}` tag is an alias for {{{key}}}, behaving just like {{key}} and {{helper}} but does not escape the result.

{{#key}}BLOCK{{/key}}

Render blocks of text one or more times, depending on the value of the key in the current context.

{{/key}}

Ends a {{#key}} or {{#helper}} block.

{{^key}}BLOCK{{/key}}

Render blocks of text if the value of the key is falsey.

{{>key}}

Render another template within the current template.

{{!key}}

The comment tag operates similarly to a `` tag in HTML.

{{helper [args...] [hashProperty=hashValue...]}}

Calls a mustache helper function or a function.

{{#helper [args...] [hashName=hashValue...]}}BLOCK{{/helper}}

Calls a mustache helper function or a function with a block to render.

{{#helper [args...] [hashName=hashValue...]}}BLOCK{{else}}INVERSE{{/helper}}

Calls a mustache helper function or a function with a `fn` and `inverse` block to render.

{{#if key}}BLOCK{{/if}}

Renders the `BLOCK` template within the current template.

{{#helper}}BLOCK{{else}}INVERSE{{/helper}}

Creates an `inverse` block for a helper function's options argument's `inverse` property.

{{#unless key}}BLOCK{{/unless}}

Render the block of text if the key's value is falsey.

{{#each key}}BLOCK{{/each}}

Render the block of text for each item in key's value.

{{#with key}}BLOCK{{/with}}

Changes the context within a block.

{{data name}}

Adds the current context to the element's can.data.

{{(el) -> CODE}}

Executes an element callback with the inline code on the element.

new can.Observe([props])

Creates a new instance of can.Observe.

can.Observe([name,] [staticProperties,] instanceProperties)

Creates a new extended constructor function.

observe.serialize([attrName])

Serializes the observe's properties using the attribute plugin.

observe.backup()

`backup` backs up the current state of the properties of an Observe and marks the Observe as clean.

observe.isDirty([deep])

`isDirty` checks whether any properties have changed value or whether any properties have been added or removed since the last time the Observe was backed up.

observe.restore( [deep] )

`restore` sets the properties of an Observe back to what they were the last time backup was called.

observe.delegate( selector, event, handler )

`delegate( selector, event, handler(ev,newVal,oldVal,from) )` listen for changes in a child attribute from the parent.

observe.undelegate( selector, event, handler )

`undelegate( selector, event, handler )` removes a delegated event handler from an observe.

observe.validateInclusionOf(attrNames, inArray, options)

Validates whether the values of the specified attributes are available in a particular array.

observe.validateLengthOf(attrNames, min, max, options)

Validates that the specified attributes' lengths are in the given range.

observe.validatePresenceOf(attrNames, options)

Validates that the specified attributes are not blank.

observe.validateRangeOf(attrNames, low, hi, options)

Validates that the specified attributes are in the given numeric range.

observe.validatesNumericalityOf(attrNames)

Validates that the specified attributes is a valid Number.

observe.attr()

Gets a collection of all the properties in this `can.Observe`.

observe.attr(key)

Reads a property from this `can.Observe`.

observe.attr(key, value)

Assigns _value_ to a property on this `can.Observe` called _key_.

observe.attr(obj[, removeOthers])

Assigns each value in _obj_ to a property on this `can.Observe` named after the corresponding key in _obj_, effectively merging _obj_ into the Observe.

observe.bind(eventType, handler)

Bind event handlers to an Observe.

observe.compute(attrName)

Make a can.compute from an observable property.

observe.each( callback(item, propName ) )

`each` iterates through the Observe, calling a function for each property value and key.

observe.removeAttr(attrName)

Remove a property from an Observe.

observe.serialize()

Get the serialized Object form of the observe.

observe.unbind(eventType[, handler])

Unbind event handlers from an Observe.

can.Observe.keys(observe)

Iterate over the keys of an Observe.

can.Observe.triggerBatch(item, event [, args])

Trigger an event to be added to the current batch.

new can.Observe.List([array])

Create an observable array-like object.

can.Observe.List([name,] [staticProperties,] instanceProperties)

Creates a new extended constructor function.

list.attr()

Gets a collection of all the elements in this `can.Observe.List`.

list.concat(...args)

Merge many collections together into a List.

list.each( callback(item, index) )

`each` iterates through the Observe, calling a function for each element.

list.forEach(callback[, thisArg])

Call a function for each element of a List.

list.indexOf(item)

`indexOf` finds the position of a given item in the List.

list.join(separator)

`join` turns a List into a string by inserting _separator_ between the string representations of all the elements of the List.

list.pop()

`push` removes an element from the end of a List.

list.push(...elements)

`push` adds elements onto the end of a List.]

list.replace(collection)

Replace all the elements of a List.

list.reverse()

`reverse` reverses the elements of the List in place.

list.shift()

`shift` removes an element from the beginning of a List.

list.slice([start[, end]])

`slice` creates a copy of a portion of the List.

list.splice(index[, howMany[, ...newElements]])

Insert and remove elements from a List.

list.unshift(...elements)

`unshift` adds elements onto the beginning of a List.

can.compute( getterSetter[, context] )

Create a compute that derives its value from can.Observes and other can.computes.

can.compute( initialValue [, settings] )

Creates a compute from a value and optionally specifies how to read, update, and listen to changes in dependent values.

can.compute( initialValue, setter(newVal,oldVal) )

Create a compute that has a setter that can adjust incoming new values.

can.compute( object, propertyName [, eventName] )

Create a compute from an object's property value.

compute.bind(eventType, handler)

Bind an event handler to a compute.

compute.unbind(eventType[, handler])

Unbind an event handler from a compute.

can.fixture( url, toUrl )

Trap requests from one url and redirect them from another.

can.fixture( url, handler(request, response, requestHeaders) )

Trap requests to a url and provide the response with a callback function.

can.fixture(fixtures)

Configures multiple ajax traps.

can.fixture.rand([min,] max)

Create a random number or selection.

can.fixture.rand(choices, min[ ,max])

Create a random number or selection.

can.fixture.store(count, make[, filter])

Make a store of objects to use when making requests against fixtures.

store.create(request, callback)

Simulate creating a Model with a fixture.

store.destroy(request, callback)

Simulate destroying a Model on a fixture.

store.find(settings)

Get an item from the store by ID.

store.findAll(request)

`store.findAll(request)` simulates a request to get a list items from the server.

store.findOne(request, callback)

Simulate a findOne request on a fixture.

store.reset()

Reset the fixture store.

store.update(request, callback)

Simulate an update on a fixture.

can.route( template [, defaults] )

Create a route matching rule.

can.route.current( data )

Check if data represents the current route.

can.route.deparam( url )

Extract data from a route path.

can.route.link( innerText, data, props [, merge] )

Make an anchor tag (``) that when clicked on will update can.route's properties to match those in `data`.

can.route.param( data )

Get a route path from given data.

can.route.ready( readyYet )

Pause and resume the initialization of can.route.

can.route.url( data [, merge] )

Make a URL fragment that when set to window.location.hash will update can.route's properties to match those in `data`.

can.$(element)

Make a library's nodelist.

can.Deferred()

`can.Deferred` is a object that allows users to assign and chain callback function(s) for the success or failure state of both asynchronous and synchronous function(s).

can.Object.subset(subset, set, compares)

Compares if subset is a subset of set.

can.Object.subsets(checkSet, sets, compares)

Returns the sets in 'sets' that are a subset of checkSet ```js can.Object.subsets({userId: 20}, [ {userId: 20, limit: 30}, {userId: 5}, {} ]) //-> [{userId: 20, limit: 30}] ```

can.addClass(nodeList, className)

Add a class to elements.

can.ajax(settings)

Make an AJAX request.

can.append(nodeList, html)

Append content to elements.

can.bind.call(target, eventName, handler)

Listen for events on an object.

can.buildFragment(html, node)

Make a document fragment.

can.capitalize(str)

Capitalize the first letter of a string.

can.data(nodeList, key, value)

Associate data with or retrieve data from DOM nodes.

can.data(nodeList, key)

Associate data with or retrieve data from DOM nodes.

can.delegate.call(element, selector, eventName, handler)

Listen for events from the children of an element.

can.deparam(params)

Takes a string of name value pairs and returns a Object literal that represents those params.

can.each(collection, callback)

Iterate through an array or object.

can.esc(str)

Escapes a string for insertion into HTML.

can.extend(target, ...obj)

Merge objects together.

can.getObject(name, roots, add)

Gets an object from a string.

can.isArray(obj)

Check if an object is an array.

can.isDeferred(subject)

Check if an object is a Deferred.

can.isEmptyObject(obj)

Check if an object has no properties.

can.isFunction(obj)

Check if an Object is a function.

can.makeArray(arrLike)

Convert an array-like object to an Array.

can.param(obj)

Serialize an object into a query string.

can.proxy(fn, context)

Bind a function to its context.

can.remode(nodeList)

Remove elements from the DOM.

can.sub(str, data, remove, s)

Returns a string with {param} replaced values from data.

can.trigger(target, eventName[, args])

Trigger an event on an object.

can.trim(str)

Trim whitespace off a string.

can.unbind.call(target, eventName, handler)

Stop listening for events on an object.

can.undelegate.call(element, selector, eventName, handler)

Stop listening for events from the children of an element.

can.underscore(str)

Takes a CamelCase or mixedCase string and underscores the string on the capital letter.

can.when(deferred)

Call a callback when a Deferred resolves.

can.view( idOrUrl, data[, helpers] )

Loads a template, renders it with data and helper functions and returns the HTML of the template within a documentFragment.

can.view( idOrUrl )

Registers or loads a template and returns a renderer function that can be used to render the template with `data` and `helpers`.

can.view.ejs( [id,] template )

Register an EJS template string and create a renderer function.

can.view.hook(callback)

Create a hookup to insert into templates.

can.view.mustache( [id,] template )

Register a Mustache template string and create a renderer function.

can.view.register(info)

Register a templating language.