CanJS

  • page
canjs  

This is the detailed documentation of the API for CanJS 2.0, 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 about 20K.

< TAG [ATTR-NAME=ATTR-VALUE] >

Create an instance of a component on a particular tag.

can.Component.extend(proto)

Extends the can.Component constructor function with prototype properties and methods.

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.List([array])

Create an observable array-like object.

new can.List(deferred)

Use for observable array-like objects.

list.attr()

Gets an array of all the elements in this `can.List`.

list.attr(index)

Reads an element from this `can.List`.

list.attr(index, value)

Assigns _value_ to the index _index_ on this `can.List`, expanding the list if necessary.

list.attr(elements[, replaceCompletely])

Merges the members of _elements_ into this List, replacing each from the beginning in order.

list.concat(...args)

Merge many collections together into a List.

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.

new can.Map([props])

Creates a new instance of can.Map.

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

Creates a new extended constructor function.

map.attr()

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

map.attr(key)

Reads a property from this `can.Map`.

map.attr(key, value)

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

map.attr(obj[, removeOthers])

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

map.bind(eventType, handler)

Bind event handlers to an Map.

map.compute(attrName)

Make a can.compute from an observable property.

map.each( callback(item, propName ) )

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

map.removeAttr(attrName)

Remove a property from an Map.

map.serialize()

Get the serialized Object form of the map.

map.unbind(eventType[, handler])

Unbind event handlers from an Map.

can.Map.keys(map)

Iterate over the keys of an Map.

observe.serialize([attrName])

Serializes the observe's properties using the attribute plugin.

map.backup()

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

map.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.

map.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.

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) -> deferred

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.

model: "PROPERTY"

Creates a `model` function that looks for the attributes object in the PROPERTY property of raw instance data.

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

Convert raw data into can.Model instances.

models: "PROPERTY"

Creates a `models` function that looks for the array of instance data in the PROPERTY property of the raw response data of findAll.

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.Model.List( [models] )

Create a model list with the provided model instances.

new can.Model.List( params )

Create an initially empty model list, but use the model's findAll to get a list of models and add it to this empty list.

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.

{{#log [message]}}

Logs the context of the current block with an optional message.

{{@index [offset]}}

Insert the index of an Array or can.List we are iterating on with [#each](can.Mustache.helpers.each)

{{@key}}

Insert the property name of an Object or attribute name of a can.Map that we iterate over with [#each](can.Mustache.helpers.each)

can.compute( getterSetter[, context] )

Create a compute that derives its value from can.Maps 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()

Sets up the two-way binding between the hash and the can.route observable map and sets the can.route map to its initial values.

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.batch.trigger(item, event [, args])

Trigger an event to be added to the current batch.

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.off.call(target, eventName, handler)

Stop listening for events on an object.

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

Listen for events on an object.

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-EVENT='KEY'

Specify a callback function to be called on a particular event.

can-value='KEY'

Binds the element's value or checked property to the value specified by key.

Scope.read(parent, reads, options)

Read properties from an object.

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.