can.view

  • function
 

Utilities for loading, processing, rendering, and live-updating of templates.

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.

var frag = can.view(
    "/contact.ejs",
    {first: "Justin", last: "Meyer"},
    {
        fullName: function(first, last){
            return first +" "+ last
        }
    });
    
document.getElementById('contacts').appendChild(frag)

Parameters

  1. idOrUrl {String | Object}

    The URL of a template or the id of a template embedded in a script tag or an object containing a url property for the URL to load and an engine property for the view engine (mustache or ejs) if it can't be infered from the file extensions or script tag type.

  2. data {Object}

    Data to render the template with.

  3. helpers {Object<String,function()>}

    An object of named local helper functions.

Returns

{documentFragment}

The rendered result of the template converted to html elements 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.

var renderer = can.view("/contact.ejs");

var frag = renderer(
    {first: "Justin", last: "Meyer"},
    {
        fullName: function(first, last){
            return first +" "+ last
        }
    })
    
document.getElementById('contacts').appendChild(frag)

Parameters

  1. idOrUrl {String}

    The URL of a template or the id of a template embedded in a script tag.

Returns

{renderer(data, helpers)}

A renderer function that can render the template into a documentFragment.

Use

can.view( idOrUrl, data, helpers ) loads template content from an element, a url or a string, renders it with data, and converts it to a documentFragment so it can be easily and efficiently inserted into the DOM.

document.getElementById('person')
  .appendChild( can.view('person.ejs', {name: "Justin" } ) )

This code:

  1. Loads the template a 'mytemplate.ejs'. It might look like:

    <h2><%= name %></h2>

  2. Renders it with {message: 'hello world'}, resulting in a documentFragment that contains:

    <h2>Justin</h2>

  3. Inserts the result into the foo element. Foo might look like:

    <div id='person'><h2>Justin</h2></div>

Loading Templates

can.view can load templates from a url or from a script.

Loading templates from a script tag

To load from a script tag, create a script tag with:

  • the template contents within the script tag
  • an id
  • a type attribute that specifies the type of template

For example:

<script type='text/ejs' id='recipesEJS'>
  <% for(var i=0; i < recipes.length; i++){ %>
    <li><%=recipes[i].name %></li>
  <%} %>
</script>

Render with this template like:

document.getElementById('recipes')
  .appendChild( can.view('recipesEJS', recipeData ) )

Notice we passed the id of the element we want to render.

Loading templates from a url

To load from a url, simply pass the location of the template to can.view. The location of the template needs an extension that matches the type of template:

document.getElementById('recipes')
  .appendChild( can.view('templates/recipes.ejs', recipeData ) )

Note: If you are using RequireJS, the URL will be relative to its baseUrl.

Creating templates from strings

Create a template for a given id programmatically using can.view.<engine>(id, template):

can.view.ejs('myViewEJS', '<h2><%= message %></h2>');
can.view('myViewEJS', { message : 'Hello EJS' });
// -> <h2>Hello EJS</h2>

It is also possible to get a nameless renderer function when creating a template from a string:

var renderer = can.view.ejs('<strong><%= message %></strong>');
renderer({
  message : 'Message form EJS'
}); // -> <strong>Message from EJS</strong>

renderer = can.view.mustache('<strong>{{message}}</strong>');
renderer({
  message : 'Message form Mustache'
}); // -> <strong>Message from Mustache</strong>

Supported Template Engines

CanJS supports the following live template languages:

Rendering to strings and sub-templates

To render to a string, use can.view.render(idOrUrl, data) like:

var str = can.view.render("/templates/recipe.ejs",{recipe: recipe});

To convert that rendered string into a live documentFragment, use frag.

To render a can.EJS sub-template within another template, use render like:

<% $.each(recipes, function(i, recipe){ %>
  <li><%== can.view.render("/templates/recipe.ejs",{
             recipe: recipe
           }) %>
  </li>
<% }) %>

Asynchronous Loading

By default, retrieving templates is done synchronously. This is fine because [StealJS] packages view templates with your JS download.

However, some people might not be using StealJS or want to delay loading templates until necessary. If you have the need, you can provide a callback paramter like:

can.view('recipes',recipeData, function(frag){
  document.getElementById('recipes')
    .appendChild(frag)
});

The callback function will be called with the result of the rendered template.

Deferreds

If you pass deferreds to can.view it will wait until all deferreds resolve before rendering the view. This makes it a one-liner to make a request and use the result to render a template.

The following makes a request for todos in parallel with the todos.ejs template. Once todos and template have been loaded, it with render the view with the todos.

can.view('recipes', Todo.findAll() , function(frag){
  document.getElementById('recipes')
    .appendChild(frag)
})