wbzyl-sinatra-static-assets 0.0.8 → 0.0.9

data/README.markdown

@@ -1,91 +1,107 @@
-# *StaticAssets* Sinatra Extension 
+# Sinatra Extension: StaticAssets  
 
-To install it, run:
+Gem *sinatra-static-assets* implements the following helpers methods:
+
+* `stylesheet_link_tag`
+* `javascript_script_tag`
+* `image_tag`
+* `link_tag`
+
+To install it, run from the command line:
 
     sudo gem install wbzyl-sinatra-static-assets -s http://gems.github.com
 
-To use, include it in a Sinatra application:
+All methods are simple wrappers around the `url_for` method
+from the [sinatra-url-for](http://github.com/emk/sinatra-url-for/).
 
-    require 'rubygems'
-    gem 'wbzyl-sinatra-static-assets'
-    require 'sinatra/static_assets'
+## When will you need it?
 
-## When you will need this gem?
+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.
 
-In short, whenever two or more applications are deployed to sub-URI
-with Phussion Passenger.
+Suppose that we already have a virtual host `hitch.local`
+and two Sinatra application which live in 
+`/home/me/www/summer` and `/home/me/www/winter` 
+directories, respectively.
+We want our Sinatra applications to be accessible from the URLs: 
+`http://hitch.local/summer` and `http://hitch.local/winter`.
 
-This means, that we want these applications to be mounted
-under one host, `http://example.org` in the example below:
+To configure Apache2 and Passenger to serve our applications
+we create a new configuration file with the content:
 
-    http://example.org/app1
-    http://example.org/app2
-    ...
-    http://example.org/tests/app3
-    http://example.org/secret/app3
-    ...
+    <VirtualHost *:80>
+      ServerName hitch.local
+      DocumentRoot /srv/www/hitch.local
+      
+      RackBaseURI /summer
+      RackBaseURI /winter
+    </VirtualHost>
 
-See Phusion Passenger users guide, [Deploying a Rack-based Ruby 
-application](http://www.modrails.com/documentation/Users guide Apache.html#_deploying_a_rack_based_ruby_application),
-Deploying to a sub URI.
+and link 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
 
-*How to fix broken images/CSS/JavaScript URIs in sub-URI deployments*
+After restarting the 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.
 
-Some people experience broken images and other broken static assets
-when they deploy their application to a sub-URI
-(i.e. http://mysite.com/railsapp/). The reason for this usually is
-that you used a static URI for your image in the views. This means
-your img source probably refers to something like /images/foo.jpg. The
-leading slash means that it's an absolute URI: you're telling the
-browser to always load http://mysite.com/images/foo.jpg no matter
-what. The problem is that the image is actually at
-http://mysite.com/railsapp/images/foo.jpg. There are two ways to fix
-this.
+The hitch here is that in Sinatra apps we usually refer to
+images/stylesheets/javascripts with absolute URI:
 
-The second and highly recommended way is to always use Rails helper
-methods to output tags for static assets. These helper methods
-automatically take care of prepending the base URI that you've
-deployed the application to. For images there is `image_tag`, for
-JavaScript there is `javascript_include_tag` and for CSS there is
-`stylesheet_link_tag`. In the above example you would simply remove the
-`<img>` HTML tag and replace it with inline Ruby like this:
+    /images/tatry1.jpg    /stylesheets/app.css    /javascripts/app.js
 
-    <%= image_tag("foo.jpg") %>
+That setup **works** whenever we are running applications locally.
+The absolute URI above tells browser to load images 
+(stylesheets and javascripts) from:
 
-This will generate the proper image tag to
+    http://localhost:4567/images/tatry1.jpg
 
-    $RAILS_ROOT/public/images/foo.jpg 
+which in turn refer to:
 
-so that your images will always work
-no matter what sub-URI you've deployed to.
+    /home/me/www/summer/public/images/tatry1.jpg
 
-## Deploying to a sub URI
+And this is the **correct** directory with the default setup of Sinatra
+application.
 
-Add to */etc/hosts*:
+But these absolute URIs do not work whenever, for example,
+the *summer* application is dispatched to sub URI.
+Now, images are at:
 
-    127.0.0.1       localhost.localdomain localhost sinatra.local
+    http://hitch.local/summer/images/tatry1.jpg
 
-Sym link the application:
+but we request images from:
 
-    ln -s ~/public_git/forks/sinatra-static-assets/examples/app1/public /srv/www/sinatra/app1
-    ln -s ~/public_git/forks/sinatra-static-assets/examples/app2/public /srv/www/sinatra/app2
+    http://hitch.local/images/tatry1.jpg
 
-Add to */etc/httpd/conf.d/sinatra.conf*
+And this **does not work** beacause there is no application 
+dispatched to *images* sub URI.
 
-    <VirtualHost *:80>
-      ServerName sinatra.local
-      DocumentRoot /srv/www/sinatra
-    
-      RackBaseURI /app1
-      RackBaseURI /app2
-    </VirtualHost>
+The recommended way to cope with broken links is to use helper
+methods which automatically take of *prepending* 
+the *RackBaseURI* that we have dispatched application to.
 
-Now, goto to `http://sinatra.local/app1` or `http://sinatra.local/app2`.
+In the above example you would simply remove the `<img>` HTML tag 
+and replace it with inline Ruby 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
+
+To use, include it in a Sinatra application:
+
+    require 'rubygems'
+    gem 'wbzyl-sinatra-static-assets'
+    require 'sinatra/static_assets'
 
 
-## TODO
+## Miscellaneous stuff
 
-1. Append a timestamp to the URI to better facilitate HTTP
-   caching. For more information, see the Rails API docs.
+[UNIX] To create virual host, add to */etc/hosts*:
 
+    127.0.0.1       localhost.localdomain localhost hitch.local

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 0
 :minor: 0
-:patch: 8
+:patch: 9

data/examples/summer/config.ru

@@ -0,0 +1,4 @@
+require 'summer'
+
+use Rack::ShowExceptions
+run Sinatra::Application

data/examples/summer/public/javascripts/app.js

@@ -0,0 +1 @@
+/* summer: app.js */

data/examples/{app1/app1.rb → summer/summer.rb}

@@ -1,9 +1,8 @@
 # -*- coding: utf-8 -*-
 
-require 'rubygems'
 require 'sinatra'
 
-gem 'sinatra-static-assets'
+gem 'wbzyl-sinatra-static-assets'
 require 'sinatra/static_assets'
 
 get "/?" do

data/examples/{app1 → summer}/views/layout.erb

@@ -2,8 +2,8 @@
 <html>
   <head>
     <meta http-equiv="content-type" content="text/html; charset=utf-8">
-    <%= stylesheet_link_tag "/stylesheets/app1.css" %>
-    <%= javascript_script_tag "/javascripts/app1.js" %>
+    <%= stylesheet_link_tag "/stylesheets/app.css" %>
+    <%= javascript_script_tag "/javascripts/app.js" %>
 
     <title><%= @title %></title>
   </head>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: wbzyl-sinatra-static-assets
 version: !ruby/object:Gem::Version 
-  version: 0.0.8
+  version: 0.0.9
 platform: ruby
 authors: 
 - Wlodek Bzyl
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-05-31 00:00:00 -07:00
+date: 2009-06-01 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -64,24 +64,6 @@ extra_rdoc_files:
 files: 
 - TODO
 - VERSION.yml
-- examples/app1/app1.rb
-- examples/app1/config.ru
-- examples/app1/public/images/tatry1.jpg
-- examples/app1/public/javascripts/app1.js
-- examples/app1/public/stylesheets/app1.css
-- examples/app1/public/stylesheets/src/bronzed_olive.png
-- examples/app1/tmp/always_restart.txt
-- examples/app1/views/index.erb
-- examples/app1/views/layout.erb
-- examples/app2/app2.rb
-- examples/app2/config.ru
-- examples/app2/public/images/tatry2.jpg
-- examples/app2/public/javascripts/app2.js
-- examples/app2/public/stylesheets/app2.css
-- examples/app2/public/stylesheets/src/skating.png
-- examples/app2/tmp/always_restart.txt
-- examples/app2/views/index.erb
-- examples/app2/views/layout.erb
 - examples/mapp1/config.ru
 - examples/mapp1/mapp.rb
 - examples/mapp1/public/images/tatry1.jpg
@@ -101,7 +83,24 @@ files:
 - examples/mapp2/views/layout.erb
 - examples/mapp2/views/mapp.erb
 - examples/mconfig.ru
-- examples/sinatra.conf
+- examples/summer/config.ru
+- examples/summer/public/images/tatry1.jpg
+- examples/summer/public/javascripts/app.js
+- examples/summer/public/stylesheets/app.css
+- examples/summer/public/stylesheets/src/bronzed_olive.png
+- examples/summer/summer.rb
+- examples/summer/tmp/always_restart.txt
+- examples/summer/views/index.erb
+- examples/summer/views/layout.erb
+- examples/winter/app2.rb
+- examples/winter/config.ru
+- examples/winter/public/images/tatry2.jpg
+- examples/winter/public/javascripts/app2.js
+- examples/winter/public/stylesheets/app2.css
+- examples/winter/public/stylesheets/src/skating.png
+- examples/winter/tmp/always_restart.txt
+- examples/winter/views/index.erb
+- examples/winter/views/layout.erb
 - lib/sinatra/static_assets.rb
 - test/sinatra_static_assets_test.rb
 - test/test_helper.rb
@@ -136,7 +135,7 @@ summary: Sinatra extension providing helper methods to output tags for static as
 test_files: 
 - test/test_helper.rb
 - test/sinatra_static_assets_test.rb
-- examples/app2/app2.rb
+- examples/summer/summer.rb
 - examples/mapp2/mapp.rb
 - examples/mapp1/mapp.rb
-- examples/app1/app1.rb
+- examples/winter/app2.rb

data/examples/app1/config.ru

@@ -1,7 +0,0 @@
-# run with:  thin --rackup config.ru -p 4567 start
-
-require 'app1'
-
-use Rack::ShowExceptions
-use Rack::Static, :urls => ["/stylesheets", "/javascripts", "/images"], :root => "public"
-run Sinatra::Application

data/examples/app1/public/javascripts/app1.js

@@ -1 +0,0 @@
-/* app1.js */

data/examples/sinatra.conf

@@ -1,18 +0,0 @@
-<VirtualHost *:80>
-  ServerName sinatra.local
-  DocumentRoot /srv/www/sinatra
-
-  RackBaseURI /app1
-  RackBaseURI /app2
-
-  #<Location /app1>
-  #  PassengerAppRoot /path-to-app1-root
-  #</Location> 
-  #
-  #    or
-  #
-  #<Directory /app1>
-  #  PassengerAppRoot /path-to-app1-root
-  #</Directory> 
-
-</VirtualHost>