ruby script/plugin install git://github.com/dancroak/subdomain-fu.git

Installation
============

SubdomainFu is available both as a traditional plugin and a GemPlugin. To install it as a traditional plugin (Rails 2.1 or later):

  script/plugin install git://github.com/mbleigh/subdomain-fu.git

To use it as a GemPlugin, add it to your environment.rb:

  config.gem 'mbleigh-subdomain-fu', :source => "http://gems.github.com", :lib => "subdomain-fu"

Examples
========

SubdomainFu works inside of Rails's URL Writing mechanisms to provide an easy and seamless way to link and otherwise understand cross-subdomain routing. You can use the :subdomain option both in named and non-named routes as well as in generated resources routes.

Let's say my domain is 'intridea.com'. Here are some examples of the use of the :subdomain option:

url_for(:controller => "my_controller", 
        :action => "my_action", 
        :subdomain => "awesome") # => http://awesome.intridea.com/my_controller/my_action

Now let's say I'm at http://awesome.intridea.com/ and I want back to the root.
Specifying "false" will remove any current subdomain:

users_url(:subdomain => false)  # => http://intridea.com/users

Note that this plugin does not honor the :only_path notion of routing when doing so would go against the intent of the command. For example, if I were at http://intridea.com again:

users_path(:subdomain => "fun") # => http://fun.intridea.com/users
users_path(:subdomain => false) # => /users

In this way you can rest assured that you will never misdirect your links to the same subdomain when you meant to change it.

Configuration
=============

You may need to configure SubdomainFu based on your development setup. The configuration required is:

tld_size
--------

A hash for each environment of the size of the top-level domain name. (something.com = 1, localhost = 0, etc.)

SubdomainFu.tld_size = 1 # sets for current environment
SubdomainFu.tld_sizes = {:development => 0,
                         :test => 0,
                         :production => 1} # set all at once (also the defaults)

mirrors
-------

Mirrors are the subdomains that are equivalent to no subdomain (i.e. they 'mirror') the usage of the root domain.

SubdomainFu.mirrors = %w(www site we) # Defaults to %w(www)

preferred_mirror
----------------

SubdomainFu also understands the notion of a 'preferred mirror', that is, if you always want your links going to 'www.yourdomain.com' instead of 'yourdomain.com', you can set the preferred mirror like so:

SubdomainFu.preferred_mirror = "www"

Now when you create a link to a false subdomain

There is currently no advanced documentation for this plugin.