Basics
Templates can be loaded using Web::load(filename). ruby-web loads .rb files as ruby, and assumes everything else is an erb template. Below is a short guide to erb templating:
<% ... %>
Evaluate ruby code.
<%= ... %>
Evaluate the enclosed ruby code and print the output.
<%%, %%>
Print out literal <%% or %%>.
The ruby-web interpreter will open a connection to the webserver and load the first
command-line argument using Web::load. In a script, one can include additional files using Web::load.
In a ruby script, one can also open a Web::Connection using Web::open. This is not
recommended, but is documented here for use in unsupported server environments.
Web::load( filename )
Given 'filename.ext' as filename, load using the handler Web::config[:load_suffix][:ext]. Returns value from handler.
Web::include( filename )
Loads filename, and returns output. Intended for use with Web::filter.
Web::connection
Return current Web::Connection.
Web::open(options)
Handle a web request. Use this method when running the ruby-web libraries
outside of the ruby-web interpreter and outside of Web::load.
#!/usr/bin/ruby
require 'web'
Web::open do |connection|
Web::write "Hello"
cgi.write "World"
end
Guide to options (defaults are in parenthesis):
:unbuffered
flag whether output should(n't) be buffered. (false)
:cgd
pass in a CGD driver
:out
set the output stream to the given IO ($stdout).
:raw_post_data
set the raw_post_data to the given IO ($stdin).
:request
pass in the request hash
:session
set the session to the given hash (Web::Session).
:env
pass in the ENV variables
:path_info
path_info is the part of the query that is after the script,
i.e. the path_info.html in /script_name.rb/path_info.html (Web::env[:path_info])
:document_root
Document root of website. (Web::env[:document_root])
:script_name
Script name, ie /script_name.rb in /script_name.rb/path_info.html (Web::env[:script_name])
Web Variables
Variables directly submitted by the client are parsed into hashes of { name => [ multiple, values ] } :
Web::get
Web::post
Web::cookie
These hashes are merged together into Web::request, which also is a hash of { name => [ multiple, values ] }.
Web[param] is a convenience method to return single values.
File uploads are parsed into Web::Upload objects, with the following methods:
Web::Upload#content_type
The browser-submitted content-type of the upload.
Web::Upload#local_path
The path to the tempfile containing the upload.
Web::Upload#open { |f| ... }
Yields the tempfile IO object, with the pointer at the beginning of the file
Web::Upload#original_filename
The browser-submitted filename of the upload.
Web::Upload#read
Returns the contents of the upload
Web::Upload#save(some_path)
Saves the contents of the tempfile to some_path
Environment variables are copied into a case-insensitive, duck-typing hash (eg Web::env[:script_name])
Reference
Web[key]
Convenience method to access values within Web::request.
If the key is array-style, aka 'param[]', the value is
returned as an array. Otherwise, value is joined with ","
and returned as a string. If Web::request[key] is an array
of Web::Upload objects, then the first value of the array is
returned.
Web[key] = value
Convenience method to set values within Web::request.
If value is not an array, sets key to [value].
Web::cookie
Access cookies sent by the client.
Web::env
ENV variables, scoped to the request, returned in a case-insensitive hash
Web::get
Access parameters passed on the url.
Web::info
Display information about the execution enviroment to the client.
Web::key?(key)
Test whether Web::cookie, Web::get, or Web::post contain the given key.
Web::keys
Return set of the keys of Web::cookie, Web::get, and Web::post.
Web::local
A hash scoped to the current web connection.
Similar to Request scope in the Java Servlet API.
Web::post
Access parameters submitted via a form posting.
Web::request
Convenience array. Combines Web::get, Web::post, and Web::cookie into one hash. If the same key is passed in Web::get and Web::post, Web::env['request_method'] is used to choose which takes priority.
Web::raw_post_data
An IO object containing the raw post data from the request.
Web::session
Session values.
Output Functions
Web << output
Write output to the browser.
Web::clear
Reset output buffer. Fails if headers have been sent.
Web::close
Flushes the output and, if applicable, saves the session.
Web::flush
Send header to the client, and flush any buffered output
Web::puts(output)
Write output to the browser with line breaks.
Web::write(output)
Write output to the browser.
Web::send_file( filename )
This method will replace the contents of the output buffer
with the content read from the given filename.
If the Content-Type header has not already been set,
it will guess an appropriate mime-type from the extension of the file.
Web::send_lib_file( relative_filename )
Using Web::send_file(filename), sends the contents of a file
from the ruby lib to the client. Filename is relative to the file of Kernel::caller.
This method is intended to help the distribution of web applications as normal ruby libraries.
# sends ".../ruby/site_lib/1.8/web/resources/logo.gif" to the client
Web::send_lib_file( 'resources/logo.gif' )
Web::unbuffered?
Returns whether output buffering is being used. By default, output is buffered.
Web::filter
Start an output buffer. aka Web::ob_start. Yields content for filtering before being written out:
Web::filter do |content|
# ... filter content
end
Web::ob_flush
Flush (send) the output buffer
Web::ob_clean
Erase and discard contents of the output buffer
Web::ob_end_clean
Erase contents of output buffer, and discard the buffer itself
Web::ob_end_flush
Flush (send) the output buffer and discard the buffer itself
Web::ob_get_clean
Get current buffer contents and delete current output buffer
Web::ob_get_contents
Return the contents of the output buffer
Web::ob_get_flush
Flush the output buffer, return it as a string and turn off output buffering
Web::ob_get_length
Return the length of the output buffer
Web::ob_get_level
Return the nesting level of the output buffering mechanism
Web::ob_list_handlers
List all output handlers in use
Utility Functions
Web::escape(string)
URL-encode a string. (from cgi.rb)
url_encoded_string = Web::escape("'Stop!' said Fred")
# => "%27Stop%21%27+said+Fred"
Web::escape_element(string, *elements)
Escape only the tags of certain HTML elements in string. Takes an element or elements or array of elements. Each element is specified by the name of the element, without angle brackets. This matches both the start and the end tag of that element. The attribute list of the open tag will also be escaped (for instance, the double-quotes surrounding attribute values). (from cgi.rb)
print Web::escape_element('<BR><A HREF="url"></A>', "A", "IMG")
# "<BR><A HREF="url"></A>"
print Web::escape_element('<BR><A HREF="url"></A>', ["A", "IMG"])
# "<BR><A HREF="url"></A>"
Web::escape_html(string)
Escape special characters in HTML, namely &\"<> (from cgi.rb)
Web::escape_html('Usage: foo "bar" <baz>')
# => "Usage: foo "bar" <baz>"
Web::get_mime_type(filename)
Guess the mimetype for the filename from the file extension.
Web::lib_file_contents( filename )
Get the contents of a file in the ruby libraries. Filename is relative to Kernel::caller
template = Web::lib_file_contents('resources/template.html')
Web::lib_filename( resource )
This function is for apps that want to store resources with the source files in the ruby lib directories. Filename is relative to Kernel::caller
Web::lib_filename('resources/logo.gif')
# => ".../ruby/site_lib/1.8/web/resources/logo.gif"
Web::rfc1123_date(time)
Make RFC1123 date string
Web::rfc1123_date(Time.now) # => Sat, 01 Jan 2000 00:00:00 GMT
Web::unescape(string)
URL-decode a string. (from cgi.rb)
string = Web::unescape("%27Stop%21%27+said+Fred")
# => "'Stop!' said Fred"
Web::unescape_element(string, *elements)
Undo escaping such as that done by Web::escape_element. (from cgi.rb)
print Web::unescape_element(
Web::escapeHTML('<BR><A HREF="url"></A>'), "A", "IMG")
# "<BR><A HREF="url"></A>"
print Web::unescape_element(
Web::escapeHTML('<BR><A HREF="url"></A>'), ["A", "IMG"])
# "<BR><A HREF="url"></A>"
Web::unescape_html(string)
Unescape a string that has been HTML-escaped (from cgi.rb)
Web::unescape_html("Usage: foo "bar" <baz>")
# => "Usage: foo \"bar\" <baz>"
Configuration
Config directives are set using Web::config[:directive] = value. If desired, config directives can be set within 'site_lib/x.x/web/site-config.rb'.
Below is a list of available config directives:
:load_suffix
:load_suffix contains a hash of handlers for different file extensions. You can then control the behavior of Web::load:
Web::config[:load_suffix][:amrita] = lambda do |scriptname|
#...handle amrita templates...
end
:load_suffix by default will load .rb and .erb files appropriately.
Everything else is loaded using ruby-web's default templating.
:load_path
:load_path is an array of directories, searched by Web::load when it has been given a relative path to load.
:error_style
Controls how exceptions are handled. Valid values include :development, :production, or :custom. :development prints a full stacktrace, :production prints a more abbreviated message. :custom allows one to defined their own handler using Web::config[:error_handler]
:multipart_progress_hook
Allows one to pass a lambda that will be called as a multipart upload is read. The lambda is called with 2 arguments: the total number of bytes, and the number of bytes read so far. Probably only useful to AJAX implementations.