View provides a uniform interface for using templates with jQuery. When template engines register themselves, you are able to:

• Use views with jQuery extensions after, append, before, html, prepend, replaceWith, text.
• Template loading from html elements and external files.
• Synchronous and asynchronous template loading.
• Deferred Rendering.
• Template caching.
• Bundling of processed templates in production builds.
• Hookup jquery plugins directly in the template.

Use

When using views, you're almost always wanting to insert the results of a rendered template into the page. jQuery.View overwrites the jQuery modifiers so using a view is as easy as:

$("#foo").html('mytemplate.ejs',{message: 'hello world'})

This code:

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

  <h2><%= message %></h2>

• Renders it with {message: 'hello world'}, resulting in:

  <div id='foo'>"<h2>hello world</h2></div>

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

  <div id='foo'><h2>hello world</h2></div>

jQuery Modifiers

You can use a template with the following jQuery modifiers:

after	$('#bar').after('temp.jaml',{});
append	$('#bar').append('temp.jaml',{});
before	$('#bar').before('temp.jaml',{});
html	$('#bar').html('temp.jaml',{});
prepend	$('#bar').prepend('temp.jaml',{});
replaceWith	$('#bar').replaceWidth('temp.jaml',{});
text	$('#bar').text('temp.jaml',{});

You always have to pass a string and an object (or function) for the jQuery modifier to user a template.

Template Locations

View can load from script tags or from files.

From Script Tags

To load from a script tag, create a script tag with your template and an id like:

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

Render with this template like:

$("#foo").html('recipes',recipeData)

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

From File

You can pass the path of a template file location like:

$("#foo").html('templates/recipes.ejs',recipeData)

However, you typically want to make the template work from whatever page they are called from. To do this, use // to look up templates from JMVC root:

$("#foo").html('//app/views/recipes.ejs',recipeData)

Finally, the [jQuery.Controller.prototype.view controller/view] plugin can make looking up a thread (and adding helpers) even easier:

$("#foo").html( this.view('recipes', recipeData) )

Packaging Templates

If you're making heavy use of templates, you want to organize them in files so they can be reused between pages and applications.

But, this organization would come at a high price if the browser has to retrieve each template individually. The additional HTTP requests would slow down your app.

Fortunately, steal.views can build templates into your production files. You just have to point to the view file like:

steal.views('path/to/the/view.ejs');

Asynchronous

By default, retrieving requests 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:

$("#foo").html('recipes',recipeData, function(result){
  this.fadeIn()
});

The callback function will be called with the result of the rendered template and 'this' will be set to the original jQuery object.

Deferreds (3.0.6)

If you pass deferreds to $.View or any of the jQuery modifiers, the view 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.

$('#todos').html("todos.ejs",Todo.findAll());

Just Render Templates

Sometimes, you just want to get the result of a rendered template without inserting it, you can do this with $.View:

var out = $.View('path/to/template.jaml',{});

Preloading Templates

You can preload templates asynchronously like:

$.get('path/to/template.jaml',{},function(){},'view');

Supported Template Engines

JavaScriptMVC comes with the following template languages:

• EmbeddedJS

  <h2><%= message %></h2>

• JAML

  h2(data.message);

• Micro

  <h2>{%= message %}</h2>

• jQuery.Tmpl

  <h2>${message}</h2>

The popular Mustache template engine is supported in a 2nd party plugin.

Using other Template Engines

It's easy to integrate your favorite template into $.View and Steal. Read how in jQuery.View.register.

Constructor

Looks up a template, processes it, caches it, then renders the template with data and optional helpers. With StealJS, views are typically bundled in the production build. This makes it ok to use views synchronously like:

$.View("//myplugin/views/init.ejs",{message: "Hello World"})

If you aren't using StealJS, it's best to use views asynchronously like:

$.View("//myplugin/views/init.ejs",
       {message: "Hello World"}, function(result){
  // do something with result
})

new $.View(view, data, helpers, callback) -> String