143 lines
4.4 KiB
Markdown
143 lines
4.4 KiB
Markdown
# Sinatra Extension: StaticAssets
|
|
|
|
Gem *sinatra-static-assets* implements the following helpers methods:
|
|
|
|
* `image_tag`
|
|
* `stylesheet_link_tag`
|
|
* `javascript_script_tag`
|
|
* `link_tag`
|
|
|
|
To install it, run:
|
|
|
|
sudo gem install wbzyl-sinatra-static-assets -s http://gems.github.com
|
|
|
|
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
|
|
|
|
In HTML `<link>` and `<img>` tags have no end tag.
|
|
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
|
|
|
|
The default value of *closed* option is `false`.
|
|
|
|
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:
|
|
|
|
gem 'wbzyl-sinatra-static-assets'
|
|
require 'sinatra/static_assets'
|
|
|
|
Or, if subclassing `Sinatra::Base`, include helpers manually:
|
|
|
|
gem 'wbzyl-sinatra-static-assets'
|
|
require 'sinatra/static_assets'
|
|
|
|
class Summer < Sinatra::Base
|
|
helpers Sinatra::StaticAssets
|
|
# ...
|
|
end
|
|
|
|
|
|
## Miscellaneous stuff
|
|
|
|
1. The `examples` directory contains *summer* and *winter* applications.
|
|
|
|
2. In order to create a virual host add the following to */etc/hosts/*:
|
|
|
|
127.0.0.1 localhost.localdomain localhost hitch.local
|
|
|
|
3. TODO: write tests
|