can

<!DOCTYPE html>  <html lang="en"> <head> <meta charset="utf-8"> <title>CanJS - can-ejs</title> <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"> <link rel="stylesheet" type="text/css" href="./static/bundles/bit-docs-site/static.css"> <link rel="shortcut icon" sizes="16x16 24x24 32x32 48x48 64x64" href="/docs/images/canjs_favicon.ico"> <link rel="apple-touch-icon" sizes="57x57" href="../docs/images/canjs_favicon_57x57.png"> <link rel="apple-touch-icon-precomposed" sizes="57x57" href="../docs/images/canjs_favicon_57x57.png"> <link rel="apple-touch-icon" sizes="72x72" href="../docs/images/canjs_favicon_72x72.png"> <link rel="apple-touch-icon" sizes="114x114" href="../docs/images/canjs_favicon_114x114.png"> <link rel="apple-touch-icon" sizes="120x120" href="../docs/images/canjs_favicon_128x128.png"> <link rel="apple-touch-icon" sizes="144x144" href="../docs/images/canjs_favicon_144x144.png"> <link rel="apple-touch-icon" sizes="152x152" href="../docs/images/canjs_favicon_152x152.png"> <meta content="yes" name="apple-mobile-web-app-capable"> <meta name="apple-mobile-web-app-status-bar-style" content="white-translucent"> <script> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-2302003-11', 'auto'); ga('send', 'pageview'); </script> </head> <body> <input type="checkbox" id="nav-trigger" class="nav-trigger"/> <label for="nav-trigger">Menu</label> <div id="everything"> <div id="left" class="column"> <div class="top-left"> <div class="brand"> <div class="logo"> <a href="../index.html" alt="CanJS"></a> <div class="dropdown project-dropdown"> <a href="https://donejs.com/">DoneJS</a> <a href="http://stealjs.com/">StealJS</a> <a href="http://jquerypp.com/">jQuery ++</a> <a href="https://funcunit.com/">FuncUnit</a> <a href="http://documentjs.com/">DocumentJS</a> </div> </div> <div class="version"> <div class="version-number"> 3.0.0 </div> <div class="dropdown version-dropdown"> <a href="https://v2.canjs.com">2.3.27</a> </div> </div> </div> <div class="search-bar"> <p>   </p> </div> </div> <div class="bottom-left"> <div class="social-side-container"> <ul class="social-side"> <li> <a class="header-mobile github" href="https://github.com/canjs/canjs" target="_blank"><img class="social-icon-small" src="../docs/images/github.png">Github</a> </li> <li> <a class="header-mobile twitter" href="https://twitter.com/canjs" target="_blank"><img class="social-icon-small" src="../docs/images/twitter.png">Twitter</a> </li> </ul> <ul class="social-side"> <li> <a class="header-mobile" href="https://gitter.im/canjs/canjs" target="_blank">Chat</a> </li> <li> <a class="header-mobile" href="http://forums.donejs.com/c/canjs" target="_blank">Forum</a> </li> </ul> </div> <ul> <li class=" "> <a class="page" href="guides.html" title="Welcome to CanJS! These guides are here to help you develop and improve your relationship with CanJS. After all, picking a JavaScript framework is a commitment. We want CanJS to be the framework you marry. This page helps you know how advance through the different stages of this relationship:"> Guides </a> </li> <li class=" "> <a class="page" href="can-core.html" title="The best, most hardened and generally useful libraries in CanJS."> Core </a> </li> <li class=" "> <a class="page" href="can-ecosystem.html" title="Useful libraries that extend or add important features to the core collection."> Ecosystem </a> </li> <li class=" "> <a class="page" href="can-infrastructure.html" title="Utility libraries that power the core and ecosystem collection."> Infrastructure </a> </li> <li class=" parent expanded"> <a class="page" href="can-legacy.html" title="Former libraries that we still accept patches for, but are not under active development."> Legacy </a> <ul> <li class="current parent expanded"> <a class="module" href="can-ejs.html" title="EJS provides live ERB-style client-side templates."> can-ejs </a> <ul> <li> <span>tags</span> <ul> <li class=" "> <a class="function" href="can-ejs/tags.scriptlet.html" title=""> <% CODE %> </a> </li> <li class=" "> <a class="function" href="can-ejs/tags.escaped.html" title=""> <%= CODE %> </a> </li> <li class=" "> <a class="function" href="can-ejs/tags.unescaped.html" title=""> <%== CODE %> </a> </li> <li class=" "> <a class="function" href="can-ejs/tags.comment.html" title=""> <%# CODE %> </a> </li> </ul> </li> <li> <span>methods</span> <ul> <li class=" "> <a class="function" href="can-ejs/methods.from.html" title="Return a template loaded from an element."> from </a> </li> </ul> </li> </ul> </li> <li class=" "> <a class="module" href="can-list.html" title=""> can-list </a> </li> <li class=" "> <a class="module" href="can-map.html" title="Create observable objects."> can-map </a> </li> <li class=" "> <a class="module" href="can-map-backup.html" title=""> can-map-backup </a> </li> <li class=" "> <a class="module" href="can-map-define.html" title="Defines the type, initial value, get, set, remove, and serialize behavior for attributes of a Map."> can-map-define </a> </li> <li class=" "> <a class="module" href="can-view-href.html" title="Sets an element's href attribute so that it's url will set the specified attribute values on can-route."> can-view-href </a> </li> </ul> </li> </ul> </div> </div> <div id="right" class="column"> <div class="top-right"> <div class="top-right-top"> <ul class="top-right-bitovi"> <li class="dropdown"> <a href="http://bitovi.com" class="bitovi icon-bits">Bitovi</a> <ul class="dropdown-menu"> <li><a href="http://bitovi.com">Bitovi.com</a></li> <li><a href="http://bitovi.com/blog/">Blog</a></li> <li><a href="http://bitovi.com/consulting/">Consulting</a></li> <li><a href="http://bitovi.com/training/">Training</a></li> <li><a href="http://bitovi.com/open-source/">Open Source</a></li> </ul> </li> </ul> <div class="brand"> <div class="logo"> <a href="../index.html" alt="CanJS"></a> </div> </div> <ul class="top-right-links"> <li> <a href="https://gitter.im/canjs/canjs">Chat</a> </li> <li> <a href="http://forums.donejs.com/c/canjs">Forum</a> </li> <li> <a class="github-button nav-social" href="https://github.com/canjs/canjs" data-count-href="/canjs/canjs/stargazers" data-count-api="/repos/canjs/canjs#stargazers_count">Star</a> </li> <li> <a href="https://twitter.com/canjs" class="twitter-follow-button nav-social" data-show-count="true" data-show-screen-name="false">Follow @canjs</a><script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script> </li> </ul> </div> <div class="breadcrumb"> <li><a href="../index.html">CanJS</a></li> / <li><a href="can-legacy.html">Legacy</a></li> / <li><a href="can-ejs.html">can-ejs</a></li> <li class="breadcrumb-dropdown">/ <a> On this page</a> <ul class="on-this-page"></ul> </li> <div class="nav-toggle" title="Back to top"></div> </div> </div> <div class="bottom-right"> <article> <section class="title"> <div class="page-type"> <h1>can-ejs</h1> <div>module</div> </div> <section class="description"> <p>EJS provides <strong>live</strong> ERB-style client-side templates.</p> </section> </section> <section class="on-this-page-table"> </section> <section class="title-footer"> <ul class="title-social"> <li> <a class="npm-button" href="https://www.npmjs.com/package/can-ejs"> <img src="https://img.shields.io/badge/npm%20package-3.0.0-brightgreen.svg" alt="npm package badge" /> </a> </li> <li> <a class="github-button nav-social" href="https://github.com/canjs/can-ejs" data-count-href="/canjs/can-ejs/stargazers" data-count-api="/repos/canjs/can-ejs#stargazers_count">Star</a> </li> </ul> <ul class="title-links">  <li><a href="//github.com/canjs/can-ejs/tree/v3.0.0/doc/can-ejs.md">source</a></li>   </ul> </section> <section class='warnings'> <div class='deprecated warning'> <h3>Deprecated 2.1</h3> <div class='signature-wrapper'> <p>EJS is incompatible with <a href="can-component.html" title="Create a custom element that can be used to manage widgets or application logic.">can-component</a> and should be avoided for new projects. Projects using EJS should consider switching to <a href="can-stache.html" title="Live binding Mustache and Handlebars-compatible templates.">can-stache</a>.</p> </div> </div> </section> <div class="signature"> <h2 class="signature-title"> <code>ejs( template )</code> </h2> <p>Returns <code>template</code> compiled to a renderer function.</p> <pre><code class="language-js">var ejs = require("can-ejs"); var renderer = ejs("<h1><%= message %></h1>"); var frag = renderer({message: "Hello World"}); frag //-> <h1>Hello World</h1> document.body.appendChild(frag); </code></pre> <div class="parameters"> <h3 class="parameters-title">Parameters</h3> <ol> <li><b>template</b> <code>{String}</code>: <p>The content of the mustache template.</p> </li> </ol> </div> <div class="returns"> <h3 class="returns-title">Returns</h3> <p> <code>{function(Any)}</code>: <p>A function that renders the ejs template into a live documentFragment given data.</p> </p> </div> </div> <div class="signature"> <h2 class="signature-title"> <code>new ejs(options)</code> </h2> <p>Creates an EmbeddedJS template instance. This form can be used to render a string.</p> <pre><code class="language-js">var ejs = require("can-ejs"); var ejsInstance = new ejs({ text: "<h1><%= message %></h1>" }); var string = ejsInstance.render({message: "Hello World"}); string //-> "<h1>Hello World</h1>" </code></pre> </div> <section class="body"> <h2>Basic Example</h2> <p>The following renders a Teacher's name and students into an element. First, create a teacher template in a script tag like:</p> <pre><code><script type='text/ejs' id='teacherEJS'> <h2 class='<%= teacher.grade < 'c'? "good" : "bad" %>'> <%= teacher.name %> </h2> <ul> <% for(var i =0; i< teacher.students.length; i++){ %> <li><%= teacher.students[i].name %></li> <% } %> </ul> </script> </code></pre> <p>Notice the magic tags? Those are things that look like <code><% %></code> and <code><%= %></code>. Code between <code><% %></code> is run and the return value of code between <code><%= %></code> is inserted into the page.</p> <p>Next, create a teacher and render the template:</p> <pre><code>var teacher = { name : "Mr. Smith", grade : "a", students : [ {name : "Suzy"}, {name : "Payal"}, {name : "Curtis"}, {name : "Alexis"} ] }; var template = ejs.from("teacherEJS"); document.getElementById('teacher') .appendChild( template(teacher) ) </code></pre> <p>This results in HTML like:</p> <pre><code><div id='teachers'> <h2 class='good'> Mr. Smith </h2> <ul> <li>Suzy</li> <li>Payal</li> <li>Curtis</li> <li>Alexis</li> </ul> </div> </code></pre> <p>This is nice, but what if we change properties of the teacher?</p> <h2>Basic Live Binding Example</h2> <p>EJS sets up live templating binding when a <a href="can-map.html" title="Create observable objects.">can-map</a>'s properties are read via <a href="can-map.prototype.attr.html" title="Get or set properties on a Map.">attr</a> within a magic tag. To make this template respond to changes in the teacher data, first rewrite the template to use the attr method to read properties and <code>list( observeList, cb(item, i) )</code> to iterate through a list like:</p> <pre><code><script type='text/ejs' id='teacherEJS'> <h2 class='<%= teacher.attr('grade') < 'c'? "good" : "bad" %>'> <%= teacher.attr('name') %> </h2> <ul> <% list(teacher.students, function(student){ %> <li><%= student.attr('name') %></li> <% }) %> </ul> </script> </code></pre> <p><strong>Note:</strong> The end of this page discusses why using <code>list</code> is helpful, but it does nothing fancy.</p> <p>Next, turn your teacher into a <code>new CanMap(object)</code> and pass that to the template:</p> <pre><code>var teacher = new CanMap({ name : "Mr. Smith", grade : "a", students : [ {name : "Suzy"}, {name : "Payal"}, {name : "Curtis"}, {name : "Alexis"} ] }); var template = ejs.from("teacherEJS"); document.getElementById('teacher') .appendChild( template(teacher) ); </code></pre> <p>Finally, update some properties of teacher and slap your head with disbelief ...</p> <pre><code>teacher.attr('name',"Prof. Snape") teacher.attr('grade','f+') teacher.attr('students').push({ name : "Harry Potter" }) </code></pre> <p>... but don't slap it too hard, you'll need it for building awesome apps.</p> <h2>Demo</h2> <p>The following demo shows an EJS template being rendered with observable data. It demonstrates live binding to attributes. The template and all data properties are editable, so experiment!</p> <div class='iframe_wrapper' data-iframe-src='can/view/ejs/doc/demo.html' data-iframe-height='1020'></div> ## Magic Tags <p>EJS uses 5 types of tags:</p> <p><strong><code><%= CODE %></code></strong> - Runs JS Code and writes the <em>escaped</em> result into the result of the template.</p> <p>The following results in the user seeing "my favorite element is <blink>BLINK<blink>" and not <blink>BLINK</blink>.</p> <pre><code> <div>my favorite element is <%= '<blink>BLINK</blink>' %>.</div> </code></pre> <p><strong><code><%== CODE %></code></strong> - Runs JS Code and writes the <em>unescaped</em> result into the result of the template.</p> <p>The following results in "my favorite element is <B>B</B>.". Using <code><%==</code> is useful for sub-templates.</p> <pre><code> <div>my favorite element is <%== '<B>B</B>' %>.</div> </code></pre> <p><strong><code><%% CODE %></code></strong> - Writes <% CODE %> to the result of the template. This is very useful for generators.</p> <pre><code> <%%= 'hello world' %> </code></pre> <p><strong><code><%# CODE %></code></strong> - Used for comments. This does nothing.</p> <pre><code> <%# 'hello world' %> </code></pre> <h2>Live Binding</h2> <p>EJS allows live binding by wrapping magic tag content within a function. When <code>attr()</code> is called to update an observable object, these functions are executed to return the new value.</p> <pre><code>// Suppose an observable "foo": var foo = new CanMap({ bar: 'baz' }); // Suppose also, the above observable is passed to our view: <%= foo.attr('bar') %> // EJS locates the magic tag and turns the above into: function() { return foo.attr('bar'); } // As "foo" is updated using attr(), this function is called again to // render the view with the new value. </code></pre> <p>This means that each function tag has a closure will reference variables in it's parent functions. This can cause problems if you don't understand closures in JavaScript. For example, the following binding does not work:</p> <pre><code><% for(var i =0; i < items.attr('length'); i++){ %> <li><%= items[i].attr('name') %></li> <% } %> </code></pre> <p>This is because it gets turned into:</p> <pre><code><% for(var i =0; i < items.attr('length'); i++){ %> LIVEBIND( function() { return items[i].attr('name') ) <% } %> </code></pre> <p>When the wrapping function is called again, <code>i</code> will not be the index of the item, but instead be items.length.</p> <p>The <a href="can-list.prototype.each.html" title="Call a function on each element of a List.">can-list::each</a> method on all observable lists should be used to iterate through it:</p> <pre><code><% items.each(function(item){ %> <li><%= item.attr('name') %></li> <% }) %> </code></pre> <h2>Advanced Live Binding</h2> <p>Once you get the hang of how EJS works, it makes live-binding of complex calculations possible. The following extends a [can.Model.List] to suppot a <code>completed</code> method that returns the total number of completed items in the list. It can be used in a template like:</p> <pre><code><h2><%= todos.complete() %> Complete Todos </h2> </code></pre> <p>And implemented like:</p> <pre><code>Todo.List = List.extend({ completed: function() { var count = 0; this.attr('length'); this.each(function(i, todo) { if(this.attr('completed')) { count++; } }); return count; } }); </code></pre> <p><code>completed</code> listens on changes to the list (via <code>this.attr('length')</code>) and each item's <code>'completed'</code> property. EJS keeps track of which observe/attribute pairs are called by <code>.complete()</code>. If they change, EJS will automatically unbind.</p> <h2>Element Callbacks</h2> <p>If a function is returned by the <code><%= %></code> or <code><%== %></code> magic tags within an element’s tag like:</p> <pre><code><div <%= function( element ) { element.style.display = 'none' } %> > Hello </div> </code></pre> <p>The function is called back with the HTMLElement as the first argument. This is useful to initialize functionality on an element within the view. This is so common that EJS supports ES5 arrow functions that get passed the NodeList wrapped element. Using jQuery, this lets you write the above callback as:</p> <pre><code><div <%= (el) -> el.hide() %> > Hello </div> </code></pre> <p>This technique is commonly used to add data, especially model instances, to an element like:</p> <pre><code><% todos.each( function( todo ) { %> <li <%= (el) -> el.data( 'todo', todo ) %>> <%= todo.attr( 'name' ) %> </li> <% } ) %> </code></pre> <p>jQuery’s <code>el.data( NAME, data )</code> adds data to an element. If your library does not support this, can provides it as <code>can.data( NodeList, NAME, data )</code>. Rewrite the above example as:</p> <pre><code><% todos.each( function( todo ) { %> <li <%= (el) -> can.data( el, 'todo', todo ) %>> <%= todo.attr( 'name' ) %> </li> <% } ) %> </code></pre> </section> <script type="text/javascript"> var docObject = {"src":{"path":"node_modules/can-ejs/doc/can-ejs.md"},"description":"EJS provides __live__ ERB-style client-side templates. \n","type":"module","title":"","types":[{"type":"function","returns":{"types":[{"type":"undefined"}]},"params":[]}],"name":"can-ejs","parent":"can-legacy","package":{"_args":[[{"raw":"can-ejs@3.0.0","scope":null,"escapedName":"can-ejs","name":"can-ejs","rawSpec":"3.0.0","spec":"3.0.0","type":"version"},"/Users/kevin/dev/canjs"]],"_from":"can-ejs@3.0.0","_id":"can-ejs@3.0.0","_inCache":true,"_location":"/can-ejs","_nodeVersion":"5.10.1","_npmOperationalInternal":{"host":"packages-16-east.internal.npmjs.com","tmp":"tmp/can-ejs-3.0.0.tgz_1476834650562_0.9794722062069923"},"_npmUser":{"name":"justinbmeyer","email":"justin@bitovi.com"},"_npmVersion":"3.8.3","_phantomChildren":{},"_requested":{"raw":"can-ejs@3.0.0","scope":null,"escapedName":"can-ejs","name":"can-ejs","rawSpec":"3.0.0","spec":"3.0.0","type":"version"},"_requiredBy":["/"],"_resolved":"https://registry.npmjs.org/can-ejs/-/can-ejs-3.0.0.tgz","_shasum":"8637319f3c1cf932c21d9f5ab87802c23e07a1db","_shrinkwrap":null,"_spec":"can-ejs@3.0.0","_where":"/Users/kevin/dev/canjs","author":{"name":"Bitovi","email":"justin@bitovi.com","url":"http://bitovi.com"},"browser":{"transform":["cssify"]},"browserify":{"transform":["cssify"]},"dependencies":{"can-compute":"^3.0.0","can-legacy-view-helpers":"^0.5.0","can-observation":"^3.0.0","can-util":"^3.0.1"},"description":"legacy EJS layer for canjs","devDependencies":{"can-list":"^3.0.0-pre.9","can-map":"^3.0.0-pre.14","cssify":"^0.6.0","documentjs":"^0.4.2","donejs-cli":"^0.7.0","generator-donejs":"^0.7.0","jshint":"^2.9.1","steal":"^0.16.0","steal-qunit":"^0.1.4","steal-tools":"^0.16.1","testee":"^0.2.4"},"directories":{},"dist":{"shasum":"8637319f3c1cf932c21d9f5ab87802c23e07a1db","tarball":"https://registry.npmjs.org/can-ejs/-/can-ejs-3.0.0.tgz"},"gitHead":"f20a03a9463b4a93d294e1ff7ae39029c32d730b","homepage":"https://canjs.com/2.3/docs/can.ejs.html","keywords":["CanJS","MVVM"],"main":"dist/cjs/can-ejs","maintainers":[{"name":"daffl","email":"daff@neyeon.de"},{"name":"designbyonyx","email":"ryan.wheale@gmail.com"},{"name":"justinbmeyer","email":"justin@bitovi.com"}],"name":"can-ejs","optionalDependencies":{},"readme":"ERROR: No README data found!","scripts":{"build":"node build.js","develop":"can-serve --static --develop --port 8080","document":"documentjs","jshint":"jshint can-ejs.js --config","postversion":"git push --tags && git checkout master && git branch -D release && git push","preversion":"npm test && npm run build","release:major":"npm version major && npm publish","release:minor":"npm version minor && npm publish","release:patch":"npm version patch && npm publish","release:pre":"npm version pre && npm publish","test":"npm run jshint && npm run testee","testee":"testee test/test.html --browsers firefox","version":"git commit -am \"Update dist for release\" && git checkout -b release && git add -f dist/"},"system":{"main":"can-ejs","ext":{"ejs":"src/system"},"configDependencies":["live-reload"],"npmIgnore":["documentjs","testee","generator-donejs","donejs-cli","steal-tools"],"npmAlgorithm":"flat"},"version":"3.0.0"},"deprecated":[{"version":"2.1","description":"EJS is incompatible with [can-component] and should\nbe avoided for new projects. Projects using EJS should consider\nswitching to [can-stache].\n"}],"signatures":[{"code":"ejs( template )","description":"\n\nReturns `template` compiled to a renderer function.\n\n```js\nvar ejs = require(\"can-ejs\");\nvar renderer = ejs(\"<h1><%= message %></h1>\");\nvar frag = renderer({message: \"Hello World\"});\nfrag //-> <h1>Hello World</h1>\n\ndocument.body.appendChild(frag);\n```\n","params":[{"types":[{"type":"String"}],"name":"template","description":"The content of the mustache template.\n"}],"returns":{"types":[{"type":"function","returns":{"types":[{"type":"undefined"}]},"params":[{"types":[{"type":"Any"}]}]}],"description":"A function that renders the ejs template into\na live documentFragment given data.\n"}},{"code":"new ejs(options)","description":"\n\nCreates an EmbeddedJS template instance. This form can be used\nto render a string.\n\n```js\nvar ejs = require(\"can-ejs\");\nvar ejsInstance = new ejs({\n\ttext: \"<h1><%= message %></h1>\"\n});\nvar string = ejsInstance.render({message: \"Hello World\"});\nstring //-> \"<h1>Hello World</h1>\"\n```\n","params":[]}],"_curReturn":{"types":[{"type":"function","returns":{"types":[{"type":"undefined"}]},"params":[{"types":[{"type":"Any"}]}]}],"description":"A function that renders the ejs template into\na live documentFragment given data.\n"},"comment":" ","pathToRoot":".."}; </script> </article> <footer><p>CanJS is part of <a href="http://donejs.com" target="_blank">DoneJS</a>. Created and maintained by the core <a href="https://donejs.com/About.html#section=section_Team" target="_blank">DoneJS team</a> and <a href="http://bitovi.com" target="_blank">Bitovi</a>. <strong>Currently 3.0.0.</strong></p></footer> </div> </div> </div> <script> steal = { instantiated: { "bundles/bit-docs-site/static.css!$css" : null } }; </script> <script type='text/javascript' data-main="bit-docs-site/static" src="./static/node_modules/steal/steal.production.js"></script> <script async defer src="https://buttons.github.io/buttons.js"></script> </body> </html>