Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Template loader for Serenade.js
JavaScript
Branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
README.md

README.md

Spanq - Serenade.js Template Loader

"Here in Castle Anthrax, we have but one punishment for setting alight the grail-shaped beacon: you must tie her down on a bed and Spanq her."

Spanq is a super simple template loader for the most-excellent Serenade.js framework.

What does it do?

  • Loads inline templates and ones linked with src="..."
  • Can load templates asynchronously...or not. Whatever gets your motor running.
  • Load all templates in one fell swoop, or just the ones you want.
  • ...like I said, it's super simple. That's about it.

About

This was inspired by ICanHaz.js but no code was taken from it. But you could think of this as ICanHaz for Serenade.js

Compatibility

Pretty much any browser that Serenade intends to support. (That means IE7+)

Introduction

For more information on Serenade's templating, check the project page.

(All examples assume that you have Serenade.js loaded and ready to go)

The Hello World Example:

<script id="template1" type="text/x-serenade">
  h1 "Hello World"
</script>

Then in our app code...

var templateElement = document.getElementById('template1');
Spanq(templateElement);

//Now that 'template1' is registered in Serenade's views...

var element = Serenade.view('template1').render();
document.body.appendChild(element);

Grab All Templates

Now, that's a lot of code just to register one little template, right? Most often, you'll just want to load every template in you page. I mean, if you didn't intend to use it, why would it be in your HTML?

//Your favorite DOMReady check[1]...

Spanq();

//All views present and accounted for, cap'n
//[1]My fav: https://github.com/ded/domready

That's it. No, really. Every Serenade template inside a script tag will now be registered in Serenade. Just make sure of two things when defining templates:

  1. Each script tag has a unique ID. That ID becomes the view's name.
  2. The "type" attribute is "text/x-serenade"

Remote Loading

Now, if you're building a decent-sized app, you aren't going to want 200+ lines of template code cluttering up your main document. How do we fix this?

You just stick your view in a file and load it with src=""

<script id="template2" type="text/x-serenade" src="/tmpl/template2"></script>

Seriously? Yep. Any templates (script tags) with a src attribute are loaded when you call Spanq() too.

Only once everything loads will the script continue.

"But if it doesn't continue until all templates are loaded, doesn't that block the browser?"

Why, yes it does! It uses synchronous XMLHttpRequests. Maybe you find that necessary, but other times we need...

Async Remote Loading!

Gee! That sounds complicated.

Nope! Just pass a callback to Spanq.

Spanq(function(/*no args*/) {

  //They're all here

});

Now you can access all your views once they're loaded without blocking the rest of the browser.

Tip: This technique can be used even if you don't load your templates with src. It will probably speed up your page load (a little).

Pick Your Poison

If you want to select specific templates to load, just pass it a NodeList or similar (or a real array of elements).

So say we want to load all template tags with the class of spanqMe...

var selectedTemplates = document.getElementsByClassName('spanqMe');

Spanq(selectedTemplates);

Tip: You can also do this in an async style too. Just pass the selected element list as the first argument and a callback as the second argument:

Spanq(selectedTemplates, function() {});

...And there you go. As long as they all have unique ID's and a type of "text/x-serenade" you should be good.

Other Stuff Someone Might Care About

Caching templates

When you link to a script/template with src="..." your browser immediately retrieves it. Then when Spanq runs through and loads everything, it's loaded again. Yeah, I'm really sorry, but that's how it has to be.

How do we fix that?

It would be very wise if you sent some cache headers whenever it's first loaded, so that once Spanq runs through, it will just get a nice 304 (not modified) and load instantly from the cache. Problem solved.

"What MIME type should my server send my templates as?"

text/plain. Even though you're loading with a script tag, it's not Javascript code. If you forget, it's no big deal because Spanq overrides it to ensure the browser sees text/plain.

"What happens if my template ID's aren't unique and/or dont have type="text/x-serenade"?

First of all...Whassa matta wichyou? Second, this is what happens:

  • Anything that's not "text/x-serenade" is just ignored.
  • If multiple templates have the same ID, either the last one on the list will win or Serenade will get angry. Either way, it's not my problem.

"May I copy/modify Spanq?"

Please do! Just give me some cred.

You could actually modify my code to work with the template engine of your choice by changing just a few lines.

Anything else?

Nope. Enjoy!

License

Spanq is licensed under the MIT license.

While Spanq is dependent on Serenade.js, it isn't associated in any way.

Something went wrong with that request. Please try again.