hoshi

hoshi copied to clipboard

= Hoshi

== Summary

Hoshi is a library for creating real, first-class HTML/XML views. It is a generator, so unlike template libraries, you can take advantage of mixins, inheritance, and all the other wonderful features of Ruby's object system.

In addition to HTML5 and plain XML, Hoshi supports RSS2 and SVG, as well as some older standards like HTML4 and XHTML1. (If you need anything more specific, it is easy to extend, and if you want to contribute, patches are welcome.)

Hoshi is designed to: * Generate clean HTML/XML with minimal effort * Be simple, to avoid bugs and keep it easy to use, understand, and modify * Take full advantage of Ruby's object sytem * Be more readable and easier to write than bare HTML

It was initially inspired by (and partially modeled on) Markaby, but the implementation is more straightforward so the semantics are cleaner (e.g., no instance_eval, meaning scope inside blocks supplied to tags has no gotcha's).

See doc/LICENSE for the license, doc/examples for examples. See test/ for the tests, and run rake test to execute them. (The tests take a fraction of a second to execute.)

== Installation

You can install via rubygems,

gem install hoshi

or by downloading from github (http://github.com/pete/hoshi).

== Usage

These examples Also, there is a program included called html2hoshi (and associated lib/html2hoshi.rb; see Hoshi.from_html) that takes HTML as input and converts it to Ruby code using Hoshi.

=== Class-based

These should be fairly straightforward:

require 'hoshi'

class Trivial < Hoshi::View :html5 def show doctype html { head { title "Hello, world!" link rel: 'stylesheet', href: '/css/hoshi.css' }

    body {
      h1 "Hello, world!"
      p "This is a greeting to the world."
    }
  }
  render
end

end

puts Trivial.new.show

You can get a little more complicated:

require 'hoshi' require 'cgi'

module Layout def main_page(t) doctype html { head { title t script(type: 'text/javascript') { raw "alert("Hi, I'm some javascript, I suppose.");" } }

    body {
      h1 t, class: 'page_title'

      yield
    }
  }
end

def list_page(t)
  main_page(t) {
    ul {
      yield
    }
  }
end

end

class Fibonacci < Hoshi::View :xhtml1 include Layout

def list_page(n)
  super("Fibonacci: f(0)..f(#{n})") {
    fib_upto(n).map { |i| li i.to_s }
  }
  CGI.pretty(render)
end

private

def fib_upto n
  a = Array.new(n) 
  
  0.upto(n) { |i|
    a[i] = 
      if i < 2
        1
      else
        a[i - 1] + a[i - 2]
      end
  }

  a
end

end

puts Fibonacci.new.list_page(n)

=== Block-based

For simpler cases where you just need to produce a little markup. Useful for small scripts.

require 'hoshi'

str = Hoshi::View::HTML5.build { doctype html { head { title "Hello, world!" link rel: 'stylesheet', href: '/css/hoshi.css' }

  body {
    h1 "Hello, world!"
    p "This is a greeting to the world."
  }
}

}

puts str

== Bugs

There needs to be some work done on correcting the tags; I suspect I'm missing or miscategorizing some of them. If you come across a case where Hoshi emits invalid HTML/XML/etc., please let me know.

That's the only known bug likely to affect you. See doc/TODO for a more detailed roadmap.

== Credits

Author: Pete Elmore, Rekka Labs -- ( pete(a)debu.gs )

The initial design is pretty heavily indebted to: _why the lucky stiff's Markaby library

Simple block version: Nolan Darilek -- (nolan(a)thewordnerd.info)

Friends that have reported bugs: Lars Lethonen, opsangeles -- ( http://opsangeles.com/ ) Hunter, Spore Labs -- ( https://github.com/madhermit )

The guys that paid me to do the initial version: AT&T Interactive. (Now yp.com; they have changed names and owners.)

The company that covers development now: Rekka Labs -- http://rekka.io/ (Yes, you can hire us.)

Also, I guess I should credit Attractive Eighties Women (http://attractiveeightieswomen.com/), since I was blasting them the whole time I was developing this. Like, over and over. I couldn't stop listening.

== Home page

http://debu.gs/hoshi