# Hpreserve

by Matthew Lyon <[email protected]>

## DESCRIPTION:

Hpreserve is a humane, eval-safe template system built atop the Hpricot DOM manipulation library. Its primary goal is to not require an interpreter to preview a design in a browser. The designer provides their own sample data which is replaced by the template parser at runtime.

Unlike similar DOM-replacement libraries lilu and Amrita, Hpreserve does not rely on matching DOM IDs to variable names, recognizing that DOM IDs often have semantic meaning in their own right. Rather, templates are driven by custom attributes on DOM elements that are removed at runtime.

## FEATURES/PROBLEMS:

  • Content Replacement: elements with a “content” attribute will have their contents replaced with the equivalent variable. Namespaced variables are available to the template using ‘.’ to separate the namespaces.

  • Content Replacement with Collections: if the variable for an element’s content attribute returns an Array, the element’s first child node will be used as a template for iterating over the content of the array. While iterating, the current item in the array is made available as a variable specified by the parent element’s “local” attribute:

    ‘<ul content=’album.songs’ local=‘song’><li content=‘song.name’>Song Name</li></ul>‘

    TODO: Currently, no attempt is made to prevent this local context variable naame from clobbering an equivalent variable name elsewhere in the variable namespace.

  • Partial Includes: Since this huge productivity booster can be replicated in Textmate (and presumably other decent html editors), elements with an “include” tag have their content replaced by the given variable. You may provide a default ‘root’ in the variable namespace with “include_base=”. Variable substitution is performed on the given value, and a default is available:

    ‘<div include=’sectionsection.name_sidebar | sidebar’></div>‘

    This would render f.e. ‘blog_sidebar’ if ‘section.name’ resolved to ‘blog’. If this value returns empty (that is, there is no ‘blog_sidebar’) it will render the default ‘sidebar’ instead.

  • Filters: given by an element’s “filter” attribute and specified using a syntax similar to the “style” attribute in HTML, filters operate on the node itself, either modifying the element’s contents or altering the element’s properties. Filter directives are separated by semi-colons, they may be given arguments after a colon, and multiple arguments are separated by commas:

    ‘<a filter=’capitalize; link_to: thingthing.link; truncate: 30, …‘>text</a>`

  • Planned Features include more sophisticated controls for iterating over an array variable, and methods for escaping html entities in variables, including an option to do this automatically.

## SYNOPSIS:

template = File.open('example.html')
variables = {'name' => 'value'}
Hpreserve::Parser.render(template, variables)

## REQUIREMENTS:

  • Hpricot

  • Rspec, if you wish to run the spec suite

## LICENSE:

Copyright © 2008 Matt Lyon

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.