Skip to content

Latest commit

 

History

History
130 lines (93 loc) · 4.37 KB

README.md

File metadata and controls

130 lines (93 loc) · 4.37 KB
Raw

Put Stuff Here

Put Stuff Here is a minimalist, human-first templating system. Instead of writing something like {{article.title}} or <%= titles[i] %>, you just write Put title here. For example, given this data:

{
  "title": "Hello World!",
  "body": "This is an example.",
  "author": "Ben Syverson"
}

…and this template…

<h2> Put title here </h2>
<p>
     Put body here
</p>
<p>
– <em>  put author here  </em>
</p>

…the result will be:

<h2> Hello World! </h2>
<p>
     This is an example.
</p>
<p>
– <em>  Ben Syverson  </em>
</p>

To edit a live example, visit the main Put Stuff Here page.

Background

Put Stuff Here is so easy to understand that almost anyone can create or edit a template. This reduces the burden on web developers, and empowers less technical folks to make changes.

The result is more fluid collaboration and faster iterations. For example, a visual designer can create a template in WebFlow or another WYSIWYG editor, which can be dropped directly into your prototype.

Features

  • Very few features!
  • Easy to understand (for everyone).
  • Templates can be compiled to fast functions.
  • Templates can be fetched and cached from .html files, via fs() in Node.js or AJAX in the browser.
  • All values are HTML-escaped by default. To insert HTML, use this parenthetical: Put stuff (unescaped) here.

Parentheticals

Parentheticals will be applied as methods on the string; Given stuff = "Example", the output from: Put stuff (toLocaleUpperCase) here will be: EXAMPLE. But don’t do that. Leave case transformations to CSS.

The parenthetical API is provided to allow you to manipulate variables in your own application-specific way. For example, if you need to show a summary of an article, rather than exporting body and a separate variable, summary, you could export body, and extend String with:

String.prototype.summary = function() {
  return this.substr(0, 30) + "…";
}

Then, in your template, you could write: Put body (summary) here. Use this form sparingly, because it makes the template less readable and more complicated.

FAQ

Q: What about conditionals, loops, and transformations?
A: I strongly believe that these things belong in your application logic. When you mix logic into your template, you suddenly have many places to look for bugs. Logic-riddled templates are far less readable to non-technical people.

Q: How would you handle a list, then?
A: That’s up to you. I might run Put Stuff Here templates against each list item, and concatenate the result into a list variable. Then you could write Put list (unescaped) here in the parent template.

Q: So you only support one magic phrase?
A: Right now, the only supported format is Put stuff here, but support is coming for Insert stuff and Stuff goes here. I would love to get support for other languages—feel free to send a pull request.

Q: I need to have the phrase "Put X here" in my template. How do I escape it?
A: Do you really need it in your template? If so, insert a newline (\n) or HTML tag somewhere in the phrase:

Put
something here.

Or: Put <!-- --> something here.

Put Stuff Here will only expand a phrase if it’s in one contiguous line. The linebreak or comment will of course be ignored by the browser.

Examples

Put Stuff Here can be used in Node, the browser, or via Browserify.

var psh = require('putstuffhere').shared();

// Fetch template.html from this directory.
psh.getTemplateFunction('template.html', function(err, func) {
	var locals = { title: "Hello World" };
	console.log( func(locals) );
});
var psh = require('putstuffhere');

// Compile a string literal directly
var func = psh.compileText('<p>Put title here</p>');
var locals = { title: "Hello World" };
console.log( func(locals) );
<script src="lib/ajax.js" type="text/javascript" charset="utf-8"></script>
<script src="lib/queue.js" type="text/javascript" charset="utf-8"></script>
<script src="lib/putstuffhere.js" type="text/javascript" charset="utf-8"></script>
<script type="text/javascript">
		var psh = PutStuffHere.shared();
		var func = psh.compileText('<p>Put title here</p>');
		var locals = { title: "Hello World" };
		console.log( func(locals) );
</script>

License

See LICENSE.md for the full MIT license.