=== Setup

Using distributed functionality with Mack is incredibly easy. The first thing we need to do is start the Mack ring 
server.

  mack_ring_server start
  
That's the glue that holds everything together. The ring server acts a registry/lookup agent so applications know where 
to find the services they are looking for.

In order to use the distributed functionality, you really need two applications. The first application will be serving 
the distributed object(s), routes, etc... and the second application will be using the distributed functionality. Both 
applications will need the mack-distributed gem. In the config/initializers/gems.rb add the following to both 
applications:

  gem.add "mack-distributed", :libs => "mack-distributed"

== Using Distributed Objects (Models)

Distributed objects are an easy way to share functionality across many different Mack applications. Whether it's a 
database model, or a bit of library code, it's easy to share and re-use.

=== Application #1 (Server)

Let's configure our 'server' application. This is where pretty much all the 'heavy lifting' is done. First we need setup 
our configuration file:

config/configatron/default.rb:
  # All distributed applications need to have a unique name so they can easily be identified for lookup.
  configatron.mack.distributed.app_name = 'my_cool_app'
  configatron.mack.distributed.share_objects = true

Let's assume that we have a simple User DataMapper model that looks something like this:

  class User
    include DataMapper::Resource

    property :id, Serial
    property :username, String
  end

It takes only one line of code to make that into a distributed object. We just need to include Mack::Distributable into 
the User class, like such:

  class User
    include Mack::Distributable
    include DataMapper::Resource

    property :id, Serial
    property :username, String
  end

Now, start your server:

  rake server

=== Application #2 (Client)

Here's where things get really cool. We don't have to do anything else to our second application to get it find and use 
our User model from the first application. When we add the mack-distributed gem, we've given it all the magic it needs 
to run.

Let's start up our console:

  rake console

Now, in our console we can do the following:

  user = Mack::Distributed::User.new
  user.username = "foobar"
  user.save

In the first application you'll see an insert into the users table in the logs. If you look in the database, you'll see 
that we've successfully created a new user.

=== How does it work?

When you include Mack::Distributable into a class it registers a proxy of that class with ring server. When another 
application makes a call to Mack::Distributed::<class_name> it looks up and finds that class in the ring server and 
returns the proxy object to you. 

=== Using Distributed Views
With distributed views, you can easily share views and layouts among different Mack Applications.
  
== Application #1 (Server)
config/configatron/default.rb:
  
  configatron.mack.distributed.site_domain = 'http://localhost:3001'
  configatron.mack.distributed.share_views = true
  configatron.mack.app_name = 'my_cool_app'

That's it.  When the server is started, the distributed view module will register a proxy with rinda ready for use by 
the client.

== Application #2 (Client)
To use distributed view, you need to specify a fully qualified distributed URI in the form of:
    distributed://app_name/path
so, let's say I want to render a page using a layout in application 1, I'd do:
    render(:action, "index", :layout => "distributed://my_cool_app/application")
The above code will render the index page using application.html layout that lives in the application #1 space.

You can also specify the distributed layout globally in the controller.  Example:

    class MyController
        include Mack::Controller
        
        layout "distributed://my_cool_app/application"
    end

All the actions in MyController will use the distributed layout

Now, to render a distributed view, you'd do the following:

    render(:distributed, "distributed://my_cool_app/admin/index")

---------

Enjoy!