\n ```\n\n- [(EVENT)=\"handler()\"](http://canjs.com/docs/can.view.bindings.event.html) - Listen to the viewModel event `EVENT` and use `handler()` as the event handler.\n\n ```\n
\n ```\n\n### can.Component\n\n[can.Component](http://canjs.com/docs/can.Component.html) lets you \ncreate widgets with well-defined View Models and are instantiated with\ncustom elements.\n\nDefine a `can.Component` by extending one with a `tag` name, [can.Map](#section=section_can_Map) `viewModel` and \n[can.stache template](#section=section_can_stache) like:\n\n```\n// Define the view model\nvar HelloViewModel = can.Map.extend({\n excitedMessage: function(){\n return this.attr(\"message\")+\"!\"\n }\n});\n\ncan.Component.extend({\n tag: \"hello-world\",\n viewModel: HelloViewModel,\n template: can.stache(\"
{{excitedMessage}}
\")\n});\n```\n\nTo instantiate this component so it says `Hello World!`, add\na `
` element to the page like:\n\n```\n\n```\n\nUse [can.view.bindings](#section=section_can_view_bindings)\nto send a value from the `can.stache` scope like:\n\n```\n// a `can.Map` that will be available in the scope\nvar appViewModel = new can.Map({\n greeting: \"Howdy Planet\"\n});\n\nvar template = can.stache('');\n\nvar frag = template(appViewModel);\n\nfrag //-> \n // Howdy Planet!
\n // \n```\n\n`can.Component`s are usually built as [modlets](/Features.html#section_Modlets),\nmeaning their template and styles are another file and imported:\n\n```\n// hello-world.js\nimport Component from 'can/component/';\nimport Map from 'can/map/';\nimport 'can/map/define/';\nimport './hello-world.less!';\nimport template from './hello-world.stache!';\n\nexport const ViewModel = Map.extend({\n excitedMessage: function(){\n return this.attr(\"message\")+\"!\"\n } \n});\n\nexport default Component.extend({\n tag: \"hello-world\",\n viewModel: ViewModel,\n template\n});\n```\n\nSome components are so small, they they don't require three\nseperate files. For these, you can use a `.component` file:\n\n```\n\n\">\n \n \n {{excitedMessage}}
\n \n \n import Map from 'can/map/';\n import 'can/map/define/';\n\n export default Map.extend({\n excitedMessage: function(){\n return this.attr(\"message\")+\"!\"\n }\n });\n \n\n```\n\n### can.route\n\n[can.route](http://canjs.com/docs/can.route.html) provides powerful 2-way, nested, routing to your application, supporting both hash and [pushstate](http://canjs.com/docs/can.route.pushstate.html). \n\nConfigure routing rules to define property values on your application's \nView Model when a url is matched.\n\n\nThe following sets the application ViewModel's `page` property\nto `\"chat\"` when the url looks like `/chat`:\n\n```\ncan.route(\":page\");\n```\n\nYou can define defaults that get set when `:page` is empty. The\nfollowing sets the default `page` property to `\"home\"`.\n\n```\ncan.route(\":page\", { page: \"home\" }); \n```\n\nYou can specify multiple properties to set for a given url: \n\n```\ncan.route(\":page/:slug\");\ncan.route(\":page/:slug/:action\");\n```\n\n\nUpdate the url by changing `can.route`:\n\n```\ncan.route.attr(\"page\", \"restaurants\");\n// location.href -> \"/restaurants\"\n```\n\nOr change `can.route` by modifying the url:\n\n```\nhistory.pushState(null, null, \"/\");\n// can.route.attr(\"page\"); // -> \"home\"\n```\n\nIn a DoneJS application can.route is bound to the [application View Model](#section=section_can_ssr_app_map), but you can connect `can.route` to other\nmaps:\n\n```\nvar Map = require(\"can/map/\");\n\nvar AppViewModel = Map.extend({\n ...\n});\n\nvar viewModel = new AppViewModel();\n\ncan.route.map(viewModel);\n```\n\nWhich will cause any changes in the route to reflect in the View Model instance, and any changes in the View Model instance to reflect in the route.\n\n## Data Layer APIs\n\n\n### can-connect\n\n[can-connect](https://connect.canjs.com) is used to connect typed \ndata to backend services. In a DoneJS application, that typed data is a \n[can.Map](#section=section_can_Map) and [can.Map](#section=section_can_List) type. \n\nTo make a simple connection to a restful interface:\n\n```\n// First, create custom Map and List type \nvar Todo = Map.extend({\n canComplete: function(ownerId) {\n return this.attr(\"ownerId\") === ownerId;\n }\n});\n\nvar TodoList = List.extend({\n Map: Todo\n},{\n incomplete: function(){\n return this.filter(function(todo){\n return !todo.attr(\"complete\")\n });\n }\n});\n\n// Then, make a connection with the right behaviors and options.\nvar todoConnection = connect([\"data-url\",\"constructor\",\"can/map\"],{\n Map: Todo,\n List: TodoList,\n url: \"/services/todos\"\n});\n```\n\nThis adds a [getList](http://connect.canjs.com/doc/can.Map.getList.html), \n[.get](http://connect.canjs.com/doc/can.Map.get.html), \n[.save](http://connect.canjs.com/doc/can.Map.prototype.save.html) and \n[.destroy](http://connect.canjs.com/doc/can.Map.prototype.destroy.html) methods to\n`Todo` allowing you to CRUD `Todo`s and `TodoList`s from the service layer like:\n\n```\n// Get a list of todos\nTodo.getList({due: \"today\"}).then(function(todos){ ... });\n\n// Get a single todo\nTodo.get({id: 5}).then(function(todo){ ... });\n\n// Create a todo\nvar todo = new Todo({name: \"dishes\"})\n\n// Create it on the server \ntodo.save().then(function(todo){\n\n // Update its properties\n todo.attr({\n name: \"Do the dishes\"\n })\n // Update the service layer with changes\n .save().then(function(todo){\n \n // Delete the todo on the service layer\n todo.destroy();\n });\n});\n```\n\n`can-connect` comes with a wide variety of behaviors that\ncan be mixed into a connection. Examples include:\n\n - [real-time](http://connect.canjs.com/doc/can-connect%7Creal-time.html) keeps `can.List`s updated with changes.\n - [fall-through-cache](http://connect.canjs.com/doc/can-connect%7Cfall-through-cache.html)\n\nTo make the process of creating `can.Map` based connections easier,\nDoneJS comes with a [supermodel generator](#section=section_generator_donejs)\ncreates a [super-map](http://connect.canjs.com/doc/can-connect%7Ccan%7Csuper-map.html).\n\nA super-map is just a connection with a bunch of the mostly commonly used\nbehaviors. Create one with the `superMap` function like:\n\n```\nexport const messageConnection = superMap({\n url: \"/services/todos\",\n Map: Todo,\n List: TodoList,\n name: 'todo'\n});\n```\n\n### can-set\n\n[can-set](https://github.com/canjs/can-set) is used to compare\nset objects that are represented by the parameters commonly passed \nto service requests. \n\nFor example, if you want all todos for user `5` that are complete, you\nmight call:\n\n```\nTodo.getList({userId: 5, complete: true})\n```\n\n`{userId: 5, complete: true}` represents a set. Using\n`can-set` we can compare it to other sets. The following\nreturns `true` because `{userId: 5, complete: true}` represents\na subset of `{userId: 5}`.\n\n```\nset.subset({userId: 5, complete: true},{userId: 5}) //-> true\n```\n\n`can-set` can perform more complex logic with custom [set Algebras](https://github.com/canjs/can-set#setalgebra).\n\nThe following creates a set-algebra that is able to combine ranges:\n\n```\n// Create a set Algebra\nvar algebra = new set.Algebra(\n set.comparators.rangeInclusive(\"start\",\"end\"));\n\n// use it\nalgebra.union({start: 1, end: 10},\n {start: 11, end: 20}) //-> {start: 1, end: 20}\n``` \n\nIn a DoneJS application, you create custom algebras to pass\nto [can-connect](#section=section_can_connect) connections. The\nconnection's behaviors use that [algebra](http://connect.canjs.com/doc/connect.base.algebra.html) to their optimizations.\n\nFor example, if the `Todo` type in the [can-connect section](#section=section_can_connect) has the following property behaviors:\n\n - `complete` can be true or false\n - `type` can be one of \"dev\", \"design\", or \"QA\"\n\n... and the service layer supports queries like:\n\n```\n//-> gets all incomplete todos\n/services/todos?complete=false \n\n// -> gets all todos that are for design and dev\n/services/todos?type[]=dev&type[]=design\n```\n\nYou'd want to create an algebra for the `superMap` as follows:\n\n```\nvar algebra = new set.Algebra(\n set.comparators.boolean(\"complete\"),\n set.comparators.enum(\"type\", [\"dev\", \"design\", \"QA\"])\n);\n\nexport const messageConnection = superMap({\n url: \"/services/todos\",\n Map: Todo,\n List: TodoList,\n name: 'todo',\n algebra: algebra\n});\n```\n\nThis allows a `superMap` to combine requests like:\n\n```\n Todo.getList({complete: true})\n+ Todo.getList({complete: true})\n================================\n Todo.getList({})\n```\n\nAnd know that if `Todo.getList({type: [\"dev\",\"design\"]})` has already been \nretrieved, there's no need to make a request for \n`Todo.getList({type: [\"dev\"]})`.\n\n\n## Testing APIs\n\n### QUnit\n\n[QUnit](http://qunitjs.com/) is DoneJS's default JavaScript unit testing framework. It is provided for DoneJS by the [steal-qunit](https://github.com/stealjs/steal-qunit) project. A basic unit test for a can.Component view-model looks like this:\n\n```js\nimport QUnit from 'steal-qunit';\nimport { ViewModel } from 'my/component/';\n\n// ViewModel unit tests\nQUnit.module('my/component');\n\nQUnit.test('Has message', function(){\n var vm = new ViewModel();\n QUnit.equal(vm.attr('message'), 'This is the my-component component');\n});\n```\n\nWhile the generators create QUnit tests by default you can switch your own tests easily to [Jasmine](https://github.com/stealjs/steal-jasmine) or [Mocha](https://github.com/stealjs/steal-mocha).\nTo use Mocha instead for the previous view-model example we just need to install the wrapper with\n\n```\nnpm install steal-mocha --save-dev\nnpm install assert --save-dev\n```\n\nAnd then change the test file to:\n\n```\nimport mocha from 'steal-mocha';\nimport assert from 'assert';\nimport { ViewModel } from 'my/component/';\n\nmocha.setup('bdd');\n\n// ViewModel unit tests\ndescribe('my/component', function() {\n it('Has a message', function() {\n var vm = new ViewModel();\n assert.equal(vm.attr('message'), 'This is the my-component component');\n });\n});\n```\n\n### FuncUnit\n\n[FuncUnit](http://funcunit.com/) enhances QUnit, Mocha or Jasmine and enables them to simulate user actions, easily test asynchronous behavior, and support black box testing. It uses a jQuery-like syntax to write functional or unit tests. When generating an application, DoneJS already includes a basic FuncUnit smoke-test which runs alongside the other tests. It looks like this:\n\n```js\nimport F from 'funcunit';\nimport QUnit from 'steal-qunit';\n\nF.attach(QUnit);\n\nQUnit.module('my-app functional smoke test', {\n beforeEach() {\n F.open('../development.html');\n }\n});\n\nQUnit.test('my-app main page shows up', function() {\n F('title').text('my-app', 'Title is set');\n});\n```\n\nThis will open the main application (`development.html` is the HTML file that loads our DoneJS app without server-side-rendering) and ensures that the `` is set to the name (which is the default in a newly generated application). To learn more about the user interactions and assertions available, follow up in the [FuncUnit API documentation](http://funcunit.com/docs/index.html).\n\n### Testee\n\n[Testee](https://github.com/bitovi/testee) is a JavaScript test runner that can run your QUnit, Mocha and Jasmine tests from the command line. The command executed when running `donejs test` (which is the same as running `npm test`) is located in the `package.json` `scripts` section and already set up to run the main test suite in Firefox like this:\n\n```\ntestee src/test.html --browsers firefox --reporter Spec\n```\n\nTo change the browsers that our tests run on we can update the list of browsers, for example to add Safari and Google Chrome Canary by changing the test script to:\n\n```\ntestee src/test.html --browsers firefox,canary,safari --reporter Spec\n```\n\nTestee supports all [Mocha command line reporters](https://mochajs.org/#reporters). For example, running the tests in the default browser [PhantomJS](http://phantomjs.org/) (DoneJS only works with PhantomJS >= 2.0) on a [Jenkins CI](https://jenkins-ci.org/) server that uses XUnit output from a `testresults.xml` can be accomplished like this:\n\n```\ntestee src/test.html --reporter XUnit > testresults.xml\n```\n\nFor more configuration options follow up in the [Testee documentation](https://github.com/bitovi/testee#testee).\n\n## DocumentJS\n\nWhen working on large applications keeping updated documentation is critical. \n[DocumentJS](http://documentjs.com/) generates API documentation for your\napplication supporting [jsdoc](http://usejsdoc.org/) syntax that can be multi-versioned.\n\n### Configuration\n\nDocumentJS is configured with a [docConfig](http://documentjs.com/docs/DocumentJS.docConfig.html) specified\nin a **documentjs.json** file within your project:\n\n```\n{\n \"sites\": {\n \"docs\": {\n \"dest\": \"docs\",\n \"glob\" : \"**/*.{js,md}\"\n }\n }\n}\n```\n\nThis specifies to look in JavaScript and Markdown files for jsdoc tags. When ran the documentation will be written to the **docs** folder.\n\n### Documenting\n\nDocumentJS includes most [tags](http://documentjs.com/docs/documentjs.tags.html) you need to document a web application and includes an API to create your own.\n\nHere's how you would document a [can.Component](#section=section_can_Component) View Model:\n\n```\n/**\n * @add order/new\n */\nexport const ViewModel = Map.extend({\n define: {\n /**\n * @property {String} slug\n *\n * The restaurants slug (short name). Will\n * be used to request the actual restaurant.\n */\n slug: {\n type: 'string'\n },\n /**\n * @property {place-my-order/models/order} order\n *\n * The order that is being processed. Will\n * be an empty new order inititally.\n */\n order: {\n Value: Order\n },\n /**\n * @property {can.Deferred} saveStatus\n *\n * A deferred that contains the status of the order when\n * it is being saved.\n */\n saveStatus: {\n Value: Object\n },\n /**\n * @property {Boolean} canPlaceOrder\n *\n * A flag to enable / disable the \"Place my order\" button.\n */\n canPlaceOrder: {\n get() {\n let items = this.attr('order.items');\n return items.attr('length');\n }\n }\n },\n\n /**\n * @function placeOrder\n *\n * Save the current order and update the status Deferred.\n *\n * @return {boolean} false to prevent the form submission\n */\n placeOrder() {\n let order = this.attr('order');\n this.attr('saveStatus', order.save());\n return false;\n },\n\n /**\n * @function startNewOrder\n *\n * Resets the order form, so a new order can be placed.\n *\n * @return {boolean} false to prevent the form submission\n */\n startNewOrder: function() {\n this.attr('order', new Order());\n this.attr('saveStatus', null);\n return false;\n }\n});\n```\n\n### Generating\n\nDoneJS preconfigures your app to be documented with:\n\n```\ndonejs document\n```\n\nOr you can run the [documentjs](http://documentjs.com/docs/DocumentJS.apis.generate.documentjs.html) command directly with:\n\n```\nnode_modules/.bin/documentjs\n```\n\n## DOM APIs\n\n### jQuery\n\n[jQuery](http://jquery.com/) is the ubiquitous DOM manipulation \nlibrary. While you don't often need to write jQuery directly,\n[CanJS](#section=section_CanJS) is built making it safe to use jQuery when needed.\n\nFor example, you can make your own custom elements that call jQuery\nplugins:\n\n```\ncan.view.tag(\"tooltip\", function(el){\n $(el).tooltip({\n content: el.getAttribute(\"content\"), \n items: \"tooltip\"\n });\n})\n```\n\n[can.view.bindings](#section=section_can_view_bindings) lets you listen \nto [jQuery special events](http://benalman.com/news/2010/03/jquery-special-events/) like:\n\n```\n<div ($tripleclick)=\"doSomething()\">\n```\n\n[can.Component](#section=section_can_Component)'s events object also supports this: \n\n```\ncan.Component.extend({\n events: {\n \"li tripleclick\": function(li, ev){ ... }\n }\n})\n```\n\n\nCanJS adds special [inserted](http://canjs.com/docs/can.events.inserted.html), [removed](http://canjs.com/docs/can.events.removed.html), and [attributes](http://canjs.com/docs/can.events.attributes.html) events. This allows you to\nteardown any behavior when the DOM is modified:\n\n```\n$(el).bind(\"removed\", function(){\n $(el).tooltip(\"teardown\");\n})\n```\n\nCanJS's live-binding also hooks into these same events. So if you remove\nan element with jQuery, CanJS will also teardown its bindings. This means that if\nyou were to call:\n\n```\n$(\"body\").empty();\n```\n\n### jQuery++\n\n[jQuery++](http://jquerypp.com/) adds a bunch of special events and other DOM\nutilties to jQuery. \n\n - DOM utilities\n - [animate](http://jquerypp.com/#animate) - Overwrites `jQuery.animate` to use CSS3 animations if possible.\n - [compare](http://jquerypp.com/#compare) - Compare the position of two elements in the page.\n - [range](http://jquerypp.com/#range) - Manipulate text ranges.\n - [within](http://jquerypp.com/#within) - Get the elements within a specified area.\n - Special events\n - [drag / drop](http://jquerypp.com/#drag) - drag drop events.\n - [hover](http://jquerypp.com/#hover) - hover events.\n - [key](http://jquerypp.com/#key) - get a string representation of the key pressed.\n - [resize](http://jquerypp.com/#resize) - listen to when an element changes size.\n - [swipe](http://jquerypp.com/#swipe) - mobile swipe events.\n\n\n## Server Side Rendering APIs\n\n### done-ssr\n\n[done-ssr](https://github.com/donejs/done-ssr) enables DoneJS applications to be\nserver-side rendered. Paired with [done-autorender](#section=section_done_autorender) \nit allows you to render the entire document from a single template.\n\n```\nvar http = require(\"http\");\nvar ssr = require(\"done-ssr\");\nvar render = ssr();\n\nvar server = http.createServer(function(request, response){\n render(request).pipe(response);\n});\n\nserver.listen(8080);\n```\n\nThe render function is called with a string url to render and returns a response\nobject that contains the html string that was rendered. Use any Node-based\nhttp framework with done-ssr.\n\nFor convenience we have published an [Express](http://expressjs.com/) middleware:\n\n```\nvar ssr = require(\"done-ssr-middleware\");\nvar app = require(\"express\")();\n\napp.use(ssr(\n config: __dirname + \"/package.json!npm\"\n));\n```\n\nAdditionally DoneJS has [done-serve](https://github.com/donejs/done-serve)\nwhich acts as a rendering front-end for your application. It will host static\ncontent, render your application, and proxy requests to another back-end server.\n\n```\ndone-serve --proxy http://localhost:7070 --port 8080\n```\n\n### done-autorender\n\n[done-autorender](https://github.com/donejs/autorender) is a Steal plugin that\nenables using a [can.stache](#section=section_can_stache) template as your application's entry point. Create a template like:\n\n```handlebars\n<html>\n<head>\n <title>app | {{page}}\n\n\n \n\n Hello {{name}}
\n\n