Guides
Tutorials
Pop Tags

Creating New Tags

Roll your own Pop Tags with modular javascript.

Webpops extension engine is based on the CommonJS module standard. Each extension is a CommonJS module stored in the extensions folder, exporting a set of functions or values.

The PopTags engine makes it easy to take advantage of this in your templates. Here's a simple extension that makes a new Pop Tag available in your templates that renders “Hello, World” .

/extensions/hello.js

exports.world = function(){
 
return"Hello, World!";
};

In a CommonJS module you always have access to an exports object, and any key you add to that object will be exported when your module is loaded. In this case we export a simple function, always returning “Hello, World!”, by the key world.

You can also load a module in another javascript file like so:

var hello = require("hello");

hello
.world()// "Hello, World!"

The name of the module (“hello”) is based on the filename hello.js.

This name can be used to require the extension in a PopTags template as well. PopTags has a special syntax for calling functions from an extension:

<pop:[name-of-module]:[name-of-function]>

Using the world function in our hello module from a template would look like this:

<h1><pop:hello:world/></h1>

This template would then output <h1>Hello, World!</h1>.

Creating Nested Tags

Rather than returning a simple string to be rendered, extensions can also return more complex objects to the template engine. This is useful when you want to make a series of new tags available to the template. Here’s an example of returning a person object and using it from the template:

/extensions/example.js

exports.person = {
  name: "Bender",
  organization: "Futurama"
};

Now a template could use this extension like this:

<pop:example:person wrap="div" class="person">
  <h2><pop:name /></h2>
  <p><pop:organization /></p>
</pop:example:person>

And the final output would be:

<div class="person">
  <h2>Bender</h2>
  <p>Futurama</p>
</div>

When an extension method returns an object, it exposes each key of the object as a tag on it’s own. Note that once we’ve opened op the scope of the <pop:example:person> tag, we no longer need the :example prefix to access the inner tags.

Returning Collections

Returning an array from an extension method triggers PopTags normal handling of collections. Here’s an example:

/extensions/example.js

exports.persons = [
  {name: "Bender", organization: "Futurama"},
  {name: "Agent Smith", organization: "The Matrix"}
]

When used by a template like this:

<pop:example:persons wrap="dl">
  <dt><pop:name/></dt>
  <dd><pop:organization/></dd>
</pop:example:persons>

It outputs:

<dl>
  <dt>Bender</dt>
  <dd>Futurama</dd>
  <dt>Agent Smith</dt>
  <dd>The Matrix</dd>
</dl>

Extensions and HTML Escaping

Any string returned to your templates will be HTML escaped by default. To return HTML, wrap it in an object with an HTML property like this:

/extensions/example.js

exports.hello = {
  html: "<h1>Hello, World!</h1>"
};

Calling <pop:example:hello/> would output <h1>Hello, World!</h1>.

Continue to Options »