Skip to content

Commit

Permalink
Fixed formating, and updated to not include github gem instructions.
Browse files Browse the repository at this point in the history
  • Loading branch information
technicalpickles authored and Michael Bleigh committed Jan 18, 2010
1 parent 69cdcd1 commit 0508904
Showing 1 changed file with 23 additions and 27 deletions.
50 changes: 23 additions & 27 deletions README.rdoc
Expand Up @@ -12,9 +12,9 @@ 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:
To use it as a gem, add it to your config/environment.rb:

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


== Examples
Expand All @@ -26,21 +26,21 @@ option both in named and non-named routes as well as in generated resources rout
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
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
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
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.
Expand All @@ -49,11 +49,9 @@ same subdomain when you meant to change it.

You have access to current_subdomain and current_domain methods.

current_subdomain - returns all subdomains.
Example for the URL http://awesome.website.stuff.example.com current_subdomain will return "awesome.website.stuff"
[current_subdomain] returns all subdomains. For the URL http://awesome.website.stuff.example.com, it will return "awesome.website.stuff"

current_domain - returns all subdomains except for the subdomain, including the TLD.
Example for the URL http://awesome.website.stuff.example.com current_subdomain will return "website.stuff.example.com"
[current_domain] returns all subdomains except for the subdomain, including the TLD. For the URL http://awesome.website.stuff.example.com, it will return "website.stuff.example.com"

If what you really want is the entire domain, then use <tt>request.domain</tt> in
your controllers. The purpose of current_domain is to only strip off the first
Expand All @@ -69,41 +67,39 @@ configuration required is:
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)
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)
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"
SubdomainFu.preferred_mirror = "www"

Now when you create a link with subdomain => false in the options the subdomain
Now when you create a link with <tt>:subdomain => false</tt> in the options the subdomain
will default to the preferred mirror.

== Routing

SubdomainFu can also work within Rails' routing for subdomain-specific routes. For instance, if you only wanted your administrative tools available in the "admin" subdomain you could add this to your routes.rb file:
SubdomainFu can also work within Rails' routing for subdomain-specific routes. For instance, if you only wanted your administrative tools available in the "admin" subdomain you could add this to your <tt>config/routes.rb</tt> file:

map.with_options :conditions => {:subdomain => 'admin'} do |admin|
admin.resources :posts
admin.resources :users
end
map.with_options :conditions => {:subdomain => 'admin'} do |admin|
admin.resources :posts
admin.resources :users
end

In addition to specifying a string, you could also specify <tt>false</tt> to
require no subdomain (this includes mirrors that you've set up such as www)
or a regular expression to match a range of subdomains.
In addition to specifying a string, you could also specify <tt>false</tt> to require no subdomain (this includes mirrors that you've set up such as www) or a regular expression to match a range of subdomains.

== Resources

Expand Down

0 comments on commit 0508904

Please sign in to comment.