Hypertemplate

Hypertemplate is a template engine for hypermedia resources. It provides a single DSL to generate different representations. This version supports json and xml generation (you can add other media types easily).

Configuring

If you are using Restfulie, there is no need to configure it, simply check the DSL.

The lib provide hooks for:

Just put require "hypertemplate/hook/[sinatra|rails|tilt]" on your app. See the integration tests for hook samples.

Hypertemplate DSL

products {
  link "order", orders_url, "type" => "application/xml"
  @products.each do |prod|
    product {
      link   :self,  product_url(prod)
      id prod.id
      name prod.name
      price prod.price
    }
  end
}

Generates the following representations:

JSON

{"products":
    {"link":[
        {"type":"application/xml",
         "rel":"order",
         "href":"http://localhost:3000/orders"}],
    "product":[
        {"link":
            [{"rel":"self",
              "href":"http://localhost:3000/products/2",
              "type":"application/json"}],
             "id":2,
             "name":"Rest Training (20h)",
             "price":"800.0"},
        {"link":
            [{"rel":"self",
              "href":"http://localhost:3000/products/3",
              "type":"application/json"}],
             "id":3,
             "name":"Modern Software architecture and Design (20h)",
             "price":"800.0"}
        ]
    }
}

XML

<?xml version="1.0"?>
<products>
  <link type="application/xml" rel="order" href="http://localhost:3000/orders"/>
  <product>
    <link rel="self" href="http://localhost:3000/products/2" type="application/xml"/>
    <id>2</id>
    <name>Rest Training (20h)</name>
    <price>800.0</price>
  </product>
  <product>
    <link rel="self" href="http://localhost:3000/products/3" type="application/xml"/>
    <id>3</id>
    <name>Modern Software architecture and Design (20h)</name>
    <price>800.0</price>
  </product>
</products>

Other features

  • You can declare recipes once and reuse it later (see Hypertemplate::Recipes)
  • You can extend Hypertemplate::Builder::Base to support a custom media type.
  • You can customize the DSL entrypoint helpers, used by the hooks (see Hypertemplate::Builder::HelperTest)

Want to know more?

Please check the unit tests, you can see a lot of richer samples, including tests for the hooks.

This library was extracted from Restfulie, then forked from Tokamak. See LICENSE.txt

A more complex example

order {
  link "self", order_url(@order)
  link "payment", order_payments_url(@order), "type" => "application/xml"
  link "calendar", order_calendar_url(@order), "type" => "text/calendar"
  address @order.address
  price @order.price
  state @order.state
  payments {
    @order.payments.each do |p|
      payment do 
        value  p.value
        state  p.state
      end
    end
  }
  items {
    @order.items.each do |i|
      item do
        id     i.product.id
        name   i.product.name
        price  i.product.price
        quantity  i.quantity
      end
    end
  }
}

Testing with Rails and Rspec

In order to test Hypertemplate with Rails and RSpec, you have to invoke

render_views

in your controller specs.

Questions? Help?

Compatibility

Hypertemplate can be used within Restfulie and its DSL is backward compatible with Tokamak 1.1.0 ~ 1.1.5.