sinatra-static-assets/README.markdown

210 lines
6.2 KiB
Markdown
Raw Normal View History

2009-11-23 22:28:59 +00:00
# Sinatra Extension: StaticAssets
2009-06-01 17:53:37 +00:00
Gem *sinatra-static-assets* implements the following helpers methods:
* `image_tag`
* `stylesheet_link_tag`
* `javascript_script_tag`
2009-09-14 11:35:24 +00:00
* `link_to`
2009-06-01 17:53:37 +00:00
To install it, run:
2009-10-19 19:47:08 +00:00
sudo gem install sinatra-static-assets -s http://gemcutter.org
2009-06-01 17:53:37 +00:00
All these methods are simple wrappers around the `url_for` method
from the [sinatra-url-for](http://github.com/emk/sinatra-url-for/) gem.
## When will you need it?
Whenever you use the
[Passenger module for Apache2](http://www.modrails.com/documentation/Users%20guide%20Apache.html#deploying_rack_to_sub_uri)
or use `Rack::URLMap` to dispatch an application to
sub URI.
Example: Suppose that we already have a virtual host `hitch.local`
and two Sinatra applications that live in
`/home/me/www/summer` and `/home/me/www/winter`
directories, respectively.
We want our Sinatra applications to be accessible from
the following sub URI:
http://hitch.local/summer
and
http://hitch.local/winter
To configure Apache2 and Passenger to serve our applications
we need to create a new configuration file with the following content:
<VirtualHost *:80>
ServerName hitch.local
DocumentRoot /srv/www/hitch.local
RackBaseURI /summer
RackBaseURI /winter
</VirtualHost>
and a link to the applications directories in `/srv/www/hitch.local`:
ln -s /home/me/www/summer/public /srv/www/hitch.local/summer
ln -s /home/me/www/winter/public /srv/www/hitch.local/winter
After restarting an Apache2 server and visiting, for example, the first
application at `http://hitch.local/summer` we see that links to
images, stylesheets and javascripts are broken.
The hitch here is that in Sinatra applications we usually refer to
images/stylesheets/javascripts with absolute URI:
/images/tatry1.jpg /stylesheets/app.css /javascripts/app.js
That setup **works** whenever we are running applications locally.
The absolute URI above tells a browser to request images
(stylesheets and javascripts) from:
http://localhost:4567/images/tatry1.jpg
which in turn, tells a server to send a file:
/home/me/www/summer/public/images/tatry1.jpg
The `public` directory is the default directory where static files
should be served from.
So, the `/images/tatry1.jpg` picture will be there and will be served
unless we had changed that default directory.
But these absolute URIs do not work when, for example,
the *summer* application is dispatched to `/summer` sub URI.
As a result the images are at:
http://hitch.local/summer/images/tatry1.jpg
but we request them from:
http://hitch.local/images/tatry1.jpg
And this **does not work** because there is no application
dispatched to *images* sub URI.
The recommended way to deal with an absolute URI
is to use a helper method that automatically converts
`/images/tatry1.jpg` to `/summer/images/tatry1.jpg`
for application dispatched to `/summer` sub URI.
In the above example you can simply remove the `<img>`
HTML tag and replace it with a Ruby inline code like this:
<%= image_tag("/images/tatry1.jpg", :alt => "Błyszcz, 2159 m") %>
See also, [How to fix broken images/CSS/JavaScript URIs in sub-URI
deployments](http://www.modrails.com/documentation/Users%20guide%20Apache.html#sub_uri_deployment_uri_fix)
## Usage examples
2009-11-23 22:28:59 +00:00
In HTML (and HTML5) `<link>` and `<img>` tags have no end tag.
2009-06-01 17:53:37 +00:00
In XHTML, on the contrary, these tags must be properly closed.
We can choose the appropriate behaviour with *closed* option:
image_tag "/images/tatry1.jpg", :alt => "Błyszcz, 2159 m", :closed => true
2009-11-23 22:28:59 +00:00
The default value of *closed* option is `false`. We can change the default value with:
enable :xhtml
We can pass mutliple stylesheets or scripts:
2009-06-01 17:53:37 +00:00
stylesheet_link_tag "/stylesheets/screen.css", "/stylesheets/summer.css", :media => "projection"
javascript_script_tag "/javascripts/jquery.js", "/javascripts/summer.js", :charset => "iso-8859-2"
link_to "Tatry Mountains Rescue Team", "/topr"
In order to use include the following in a Sinatra application:
2009-10-19 19:07:23 +00:00
gem 'sinatra-static-assets'
2009-06-01 17:53:37 +00:00
require 'sinatra/static_assets'
Or, if subclassing `Sinatra::Base`, include helpers manually:
gem 'sinatra-url-for'
2009-06-05 18:37:10 +00:00
require 'sinatra/url_for'
2009-10-19 19:07:23 +00:00
gem 'sinatra-static-assets'
2009-06-01 17:53:37 +00:00
require 'sinatra/static_assets'
class Summer < Sinatra::Base
2009-06-05 18:37:10 +00:00
helpers Sinatra::UrlForHelper
2009-11-23 22:28:59 +00:00
register Sinatra::StaticAssets
2009-06-01 17:53:37 +00:00
# ...
end
## Dispatching reusable Sinatra applications
With the latest version of Sinatra it is possible to build
reusable Sinatra applications. This means that multiple Sinatra applications
can be run in isolation and co-exist peacefully with other Rack
based applications. Subclassing `Sinatra::Base` creates such a
reusable application.
The `example` directory contains two reusable Sinatra applications:
*rsummer*, *rwinter* and a rackup file `rconfig.ru` which
2009-08-31 12:34:05 +00:00
dispatches these applications to `/summer` and `/winter` sub URI:
2009-06-02 09:41:10 +00:00
$LOAD_PATH.unshift('rsummer')
require 'summer'
$LOAD_PATH.unshift('rwinter')
require 'winter'
map '/summer' do
run Sinatra::Summer.new
end
map '/winter' do
run Sinatra::Winter.new
end
2009-06-02 09:41:10 +00:00
Run `rconfig.ru` file with:
rackup -p 3000 rconfig.ru
2009-06-02 09:48:06 +00:00
This file could **also** be used to deploy to virtual host's root with
Passenger.
2009-06-02 09:41:10 +00:00
To this end, create an Apache2 configuration file with the following
content:
<VirtualHost *:80>
ServerName hitch.local
DocumentRoot /srv/www/hitch.local
</VirtualHost>
2009-06-02 09:41:10 +00:00
Next, create directories required by Passenger:
mkdir /srv/www/hitch.local/{public,tmp}
2009-06-02 09:49:13 +00:00
and, finally, copy `config.ru` into `/srv/www/hitch.local` and
2009-06-02 09:41:10 +00:00
update `LOAD_PATH` in the copied file.
With everything in place, after restarting Apache2,
the applications are accessible from the
http://hitch.local/summer
and
http://hitch.local/winter
respectively.
2009-06-01 17:53:37 +00:00
## Miscellaneous stuff
2009-06-02 09:51:53 +00:00
1\. The `examples` directory contains *summer* and *winter* applications.
2009-06-01 17:53:37 +00:00
2009-06-02 09:51:53 +00:00
2\. In order to create a virual host add the following to */etc/hosts/*:
2009-06-01 17:53:37 +00:00
2009-06-02 09:51:53 +00:00
127.0.0.1 localhost.localdomain localhost hitch.local
2009-10-21 17:43:32 +00:00
or, read [editing /etc/hosts is waste of my
time](http://www.taylorluk.com/articles/2009/08/12/hey-pac-man-sup-subdomains).