Wunderbar: Easy HTML5 applications
Wunderbar makes it easy to produce valid HTML5, wellformed XHTML, Unicode (utf-8), consistently indented, readable applications.
Wunderbar was inspired by Jim Weirich's Builder, and provides the element id and class id syntax and based on the implementation from Markaby.
Wunderbar's JSON support is inspired by David Heinemeier Hansson's jbuilder.
A tutorial is under development.
Additional functionality is provided by extensions.
Overview
The premise of Wunderbar is that output of various types are typically formed by appending either a series of key/value pairs or simple values, and those operations should be optimized for. Appending a key/value pair is done via:
_key value
... and appending a simple value is done thus:
_ value
For HTML, key/value is used for element nodes, and simple values are used for text nodes. For JSON, key/value is used for Hashes and simple values are used for arrays. For text, simple values are output via puts, and key/value pairs are not used.
Nesting is performed using blocks.
The underscore method, when passed no arguments, returns an object that can be used to perform a number of special functions. Some of those functions are unique to the output method. Others like logging methods are common.
The underscore method when passed multiple arguments or a combination of arguments and a block may do other common functions, depending on the types of the arguments passed.
Question mark, exclamation mark, and underscore suffixes to the method name may modify the results.
Quick Start (HTML)
Simple element:
_br
Nested elements:
_div do
_hr
end
Element with text:
_h1 "My weblog"
Element with attributes:
_img src: '/img/logo.jpg', alt: 'site logo'
Element with both text and attributes:
_a 'search', href: 'http://google.com'
Element with boolean attributes:
_input 'Cheese', type: 'checkbox', name: 'cheese', checked: true
Element with boolean attributes (alternate form):
_input 'Cheese', :checked, type: 'checkbox', name: 'cheese'
Element with optional (omitted) attributes:
_tr class: nil
Text (markup characters are escaped):
_ "<3"
Text (may contain markup):
_{"<em>hello</em>!!!"}
Import of HTML/XML:
_[Nokogiri::XML "<em>hello</em>"]
Mixed content (autospaced):
_p do
_ 'It is a'
_em 'very'
_ 'nice day.'
end
Mixed content (space controlled):
_p! do
_ 'Source is on '
_a 'github', href: 'https://github.com/'
_ '.'
end
Insert blank lines between rows in the HTML produced:
_tbody do
_tr_ do
_td 1
end
_tr_ do
_td 2
end
_tr_ do
_td 3
end
end
Capture exceptions:
_body? do
raise NotImplementedError.new('page')
end
Class attribute shortcut (equivalent to class="front"):
_div.front do
end
Id attributes shortcut (equivalent to id="search"):
_div.search! do
end
Complete lists/rows can be defined using arrays:
_ul %w(apple orange pear)
_ol %w(apple orange pear)
_table do
_tr %w(apple orange pear)
end
Arbitrary iteration can be done over Enumerables:
_dl.colors red: '#F00', green: '#0F0', blue: '#00F' do |color, hex|
_dt color.to_s
_dd hex
end
Basic interface
A typical main program produces one or more of HTML, JSON, or plain text output. This is accomplished by providing one or more of the following:
_html do
code
end
_xhtml do
code
end
_json do
code
end
_text do
code
end
_websocket do
code
end
Arbitrary Ruby code can be placed in each. Form parameters are made available
as instance variables (e.g., @name
). Host environment (CGI, Rack, Sinatra)
values are accessible as methods of the _
object: for example _.headers
(CGI), _.set_cookie
(Rack), _.redirect
(Sinatra).
To append to the output produced, use the _
methods described below.
Example applications are in the tutorial.
Methods provided to Wunderbar.html
Invoking methods that start with a Unicode low line character ("_") will generate an HTML tag. As with builder, on which this library is based, these tags can have text content and attributes. Tags can also be nested. Logic can be freely intermixed.
Wunderbar knows which HTML tags need to be explicitly closed with separate end
tags (example: textarea
), and which should never be closed with separate end
tags (example: br
). It also takes care of HTML quoting and escaping of
arguments and text.
Suffixes after the tag name will modify the processing.
-
!
: turns off all special processing, including indenting -
?
: adds code to rescue exceptions and produce tracebacks -
_
: adds extra blank lines between this tag and siblings
The "_
" method serves a number of purposes. Calling it with a single
argument inserts markup, respecting indendation. Inserting markup without
regard to indendatation is done using "_ << text
". A number of other
convenience methods are defined:
-
_
: insert text with indentation matching the current output -
_!
: insert text without indenting -
_.post?
-- was this invoked via HTTP POST? -
_.system
-- invokes a shell command, captures stdin, stdout, and stderr -
_.submit
-- runs command (or block) as a deamon process -
_.xhtml?
-- output as XHTML?
The _.system
method takes an optional hash as its last parameter. This can be used to provide settings for the underlying
Process.spawn method.
For example: ._system('pwd',{ system_opts: { chdir: dir } , system_env: { 'FOO' => 'BAR' } })
Note that environment variable names must be provided as strings, not symbols.
Additional options that can be used with _.system
include:
-
:tag
- the HTML tag to be used for input/output; defaults topre
-
:bundlelines
- whether to process all the lines for a given output type (stderr, stdout, etc ) as part of single tag. If not specified, defaults totrue
forpre
tags andfalse
otherwise. Iffalse
, each line of output is processed separately.
Access to all of the builder defined methods (typically these end in an exclamation mark) and all of the Wunderbar module methods can be accessed in this way. Examples:
-
_.tag! :foo
: insert elements where the name can be dynamic -
_.comment! "text"
: add a comment -
_.error 'Log message'
: write a message to the server log
Underscores in element and attribute names are converted to dashes. To
disable this behavior, express attribute names as strings and use the _.tag!
method for element names.
XHTML differs from HTML in the escaping of inline style and script elements. XHTML will also fall back to HTML output unless the user agent indicates it supports XHTML via the HTTP Accept header.
In addition to the default processing of elements, text, and attributes, Wunderdar defines additional processing for the following:
-
_head
: insert meta charset utf-8 -
_svg
: insert svg namespace -
_math
: insert math namespace -
_coffeescript
: convert coffeescript to JS and insert script tag
Note that adding an exclamation mark to the end of the tag name disables this behavior.
If one of the attributes passed on the _html
declaration is :_width
, an
attempt will be made to reflow text in order to not exceed this line width.
This won't be done if it will affect what actually is displayed.
If none of the child elements for the html
element are either head
or
body
, then these tags will be created for you, and the relevant children
will be moved to the appropriate section. If the body contains a h1
element, and the head
doesn't contain a title
, a title element will be
created based on the text supplied to the first h1
element.
Methods provided to Wunderbar.json
Common operations are to return a Hash or an Array of values. Hashes are a series of name/value pairs, and Arrays are a series of values.
Wunderbar.json do
_content format_content(@message.content)
_ @message, :created_at, :updated_at
_author do
_name @message.creator.name.familiar
_email_address @message.creator.email_address_with_name
_url url_for(@message.creator, format: :json)
end
if current_user.admin?
_visitors calculate_visitors(@message)
end
_comments @message.comments, :content, :created_at
_attachments @message.attachments do |attachment|
_filename attachment.filename
_url url_for(attachment)
end
end
Invoking methods that start with a Unicode low line character ("_") will add a key/value pair to that hash. Hashes can also be nested. Logic can be freely intermixed.
The "_
" method serves a number of purposes.
-
calling it with multiple arguments will cause the first argument to be treated as the object, and the remainder as the attributes to be extracted
- Example:
_ File.stat('foo'), :mtime, :size, :mode
- Example:
-
calling it with a single Enumerable object and a block will cause an array to be returned based on mapping each objection from the enumeration against the block
- Example:
_([1,2,3]) {|n| n*n}
- Example:
-
arrays can be also be built using the
_
method:_ 1 _ 2
The _
method returns a proxy to the object being constructed. This is often
handy when called with no arguments. Examples:
_.sort!
_['foo'] = 'bar'
Methods provided to Wunderbar.text
Appending to the output stream is done using the _
method, which is
equivalent to puts
. The _
method returns an object which proxies the
output stream, which provides access to other useful methods, for example:
_.print 'foo'
_.printf "Hello %s!\n", 'world'
Methods provided to Wunderbar.websocket
WebSocket support requires em-websocket
to be installed.
A web socket is a bidrectional channel. _.send
or _.push
can be used to
send arbitrary strings. More commonly, the JSON array methods described above
can be all be used, the important difference is that the individual entries
are sent individually and as they are produced.
_.recv
or _.pop
can be used to receive arbitrary strings. More commonly,
_.subscribe
is used to register a block that is used as a callback.
_.system
will run an arbitrary command. Lines of output are sent across the
websocket as they are received as JSON encoded hashes with two values: type
is one of stdin
, stdout
or stderr
; and line
which contains the line
itself. If the command is an array, the elements of the array will be escaped
as Shell command arguments. Nested arrays may be used to hide elements from
the echoing of the command to stdin. Nil values are omitted.
Options to _websocket
are provided as a hash:
-
:port
will chose a port number, with the default being that an available one is picked for you. -
:sync
set tofalse
will cause the WebSocket server to be run as a daemon process. This defaults totrue
when run from the command line and tofalse
when run as CGI. -
buffer_limit
will limit the amount of entries retained and sent to new clients on open requests. Default is1
. A value of zero will disable buffering. A value ofnil
will result in unlimited buffering. Note: buffering is effectively unlimited until the first client connects.
Secure by default
Wunderbar will properly escape all HTML and JSON output, eliminating problems
of HTML or JavaScript injection. This includes calls to _
to insert text
directly. Unless nokogiri
was previously required (see optional
dependencies below), calls to insert markup
(_{...}
) will escape the markup.
Globals provided
-
$USER
- Host user id -
$PASSWORD
- Host password (if CGI and HTTP_AUTHORIZATION is passed through) -
$HOME
- Home directory -
$SERVER
- Server name -
$HOME
- user's home directory -
$HOST
- server host
Also, the following environment variables are set if they aren't already:
HOME
HTTP_HOST
LANG
REMOTE_USER
Finally, the default external and internal encodings are set to UTF-8.
Logging
-
_.debug
: debug messages -
_.info
: informational messages -
_.warn
: warning messages -
_.error
: error messages -
_.fatal
: fatal error messages -
_.log_level
=: set logging level (default::warn
) -
_.default_log_level
=: set, but don't override, log level -
_.logger
: return Logger instance
Command line options
When run from the command line, CGI name=value pairs can be specified. Additionally, the following options are supported:
-
--get
: HTML (HTTP GET) output is expected -
--post
: HTML (HTTP POST) output is expected -
--json
: JSON (XML HTTP Request) output is expected -
--html
: force HTML output -
--prompt
or--offline
: prompt for key/value pairs using stdin -
--debug
,--info
,--warn
,--error
,--fatal
: set log level -
--install=
path: produce an suexec-callable wrapper script -
--rescue
or--backtrace
cause wrapper script to capture errors
Optional dependencies
The following gems are needed based on what functions you use:
-
em-websocket
is required bywunderbar/websocket
-
kramdown
is required bywunderbar/markdown
-
ruby2js
adds support for scripts written as blocks -
sourcify
is required bywunderbar/opal
The following gems are required by extensions of the same name:
-
coderay
- syntax highlighting -
opal
- ruby to javascript compiler -
rack
- webserver interface -
sinatra
- DSL for creating web applications
The following gems, if installed, will produce cleaner and prettier output:
-
nokogiri
cleans up HTML fragments inserted via<<
and_{}
. -
nokogumbo
also cleans up HTML fragments inserted via<<
and_{}
. If this gem is available, it will be preferred over direct usage ofnokogiri
. -
escape
prettier quoting ofsystem
commands