Overview

Example Neapolitan Document

Here is an example Neapolitan template, ‘vanilla.np’:

output: vanilla.html

--- erb rdoc

= Yummy Vanilla

Hi <%= name %>,

I know you want some of that yummy stuff.

--- coderay.ruby

  %{v a n i l l a}.each do |letter|
    puts "Give me a #{letter}!"
  end

  puts "What's that spell?"

--- liquid html

<quote>
  {{ yield }}
</quote>

--- textile

|                | 2009 | 2010 |
| Has Vanilla?   |  No  | Yes! |

As you can see. It's all _fun_ and _games_ here.

Loading the Library

Require the library.

require 'neapolitan'

Reading a Neapolitan File

To load our example template, we can either pass a File object to the Template initializer.

path = "vanilla.np"

template = Neapolitan::Template.new(File.new(path))

Or we can use the shortcut file method.

template = Neapolitan.file(path)

Rendering Data Sources

Neapolitan uses Malt on the backend. Malt supports a three separate ways to pass data into a template.

The most obvious data source is a Hash.

data = {:name=>"Tom"}

text = template.render(data).to_s

text.assert =~ /Hi Tom/

Templates can also be rendered given a Binding.

name = "Huck"

text = template.render(binding).to_s

text.assert =~ /Hi Huck/

Lastly, they can be rendered with the scope of any other type of Object, including an instance of a Struct.

scope = Struct.new(:name).new("Becky")

text = template.render(scope).to_s

text.assert =~ /Hi Becky/

FAQ

How do I limit the section formats that can be used?

There are two methods that can be used to limit the formats that of a Neapolitan template, namely, #select and #reject.

After creating a Template object, use the #select and/or the #reject methods to filter out any unwanted formats.

template = Neapolitan.file('example.np')

template.reject{ |format| %w{liquid}.include?(format) }

template.render(:name=>"Tom")

These methods can be used for more aggressive validation by raising an error.

template = Neapolitan.file('example.np')

template.reject do |format|
  raise TypeError if %w{liquid}.include?(format)
  false
end

expect TypeError do
  template.render(:name=>"Tome")
end

Why should template formats be listed before markup format?

Consider what happens if have a document section proccessed by RDoc before applying templating such as ERB:

= Example

Hi, <%= name %>

The result never ends up utilizing ERB properly because RDoc transformed the document into:

<h1>Example</h1>

Hi, &lt;%= name &gt;

Therefore you should always list the template format before markup formats. Of course usually template formats are not used on section by section basis in anycase, so this won’t be an issue, but it’s good to know just in case.

Table of Contents

Overview

Example Neapolitan Document

Loading the Library

Reading a Neapolitan File

Rendering Data Sources

FAQ