Permatime Plugin
================
Permatime is a website that allows you to share any point in time with people in different time zones. 
Permatime urls are easily readable in emails or documents. 
See http://permatime.com for more information

This gives an easy way to generate permatime urls from times for use within rails views,
and (coming soon) make a globally-friendly maintenance page.


Installation and configuration
==============================
1) install the plugin
  ./script/plugin install git://github.com/red56/permatime_plugin.git


all other configuration is optional:
2) for advanced usage you need the tzinfo gem (http://tzinfo.rubyforge.org/)
(this gem changes regularly to keep up with timezone updates)

3) for monkeypatching (read 'Usage in rails views' below) 
add the following in an initializer (e.g. config/initializers/permatime.rb)
Time.send :include, PermatimeTimeMonkeypatcher

4) For the maintenance page when your application is offline...
(based on Mike Clark's Recipe in Advanced Rails Recipes and his weblog)

 You should at a minimum customize the maintenance page with the name of the app and your twitter id if you have one:
   /app/views/layouts/maintenance.html.erb
 
 This replaces capistrano's vanilla maintenance page - and requires config of your web/proxy server (apache, nginx etc) to serve up this maintenance page
 when it exists (thus ignoring the whole of your webapp if available).  This is not covered here, but you've probably already done this.
  


Usage in rails views
====================
Out of the box it gives you a permatime helper so that you can do the following in any rails view:

  <%= link_to nil, permatime %> 
which will generate a linked permatime url for the current date and time.

  <%= link_to nil, permatime(@mymodel.created_at) %> 
which will generate a linked permatime url for the creationdate of a particular model instance.

If instead of permatime(@mymodel.created_at), you prefer the style @mymodel.created_at.permatime 
then you need to include the following in an initialization file (e.g. create config/initializers/permatime.rb)
  Time.send :include, PermatimeTimeMonkeypatcher
 
You can set a title for the permatime:
  permatime(@mymodel.created_at, :title=>'Interesting event')

You can also set the time using individual setters
  permatime(:year=>2008, :month=>12, :day=>25, hour=>00, minutes=>01, :title="Check the stockings")

You can also set the time explicitly (you may also name what timezone that time should be treated as, the zone info in the time is ignored)
  permatime(:year=>2008, :time=>Time.mktime(2008,12,25,00,01), :title="Check the stockings", :timezone=>'Europe/Finland')
 
Or if you you can create a timestamp-based permatime (see http://permatime.com/about)
  permatime(Time.now.to_i)
or
  permatime(:timestamp=>Time.now.to_i)
  
  
Usage for maintenance page (capistrano)
=======================================
 you can adjust the maintenance page by editing
   /app/views/layouts/maintenance.html.erb

 you can preview (locally on your dev machine) the maintenance page using:
   rake preview_maintenance
    or
  UNTIL="16:00 MST" REASON="a database upgrade" rake preview_maintenance
   
 you can make your website just display the maintenance page using:
   cap deploy:web:disable
        or, if you want to specify how long and why, then:
   UNTIL="16:00 MST" REASON="a database upgrade" cap deploy:web:disable
 
 you can reverse this using:
   cap deploy:web:enable
   


Advanced Usage
==============
The above permatimes are UTC/GMT timezones. It would be more readable for some of your readers 
if you put the permatimes into a timezone they are likely to understand, 
e.g. US/Pacific, Asia/Mumbai, Asia/China, Australia/Sydney, Europe/Paris
 (the choice of timzone depends of course on what is most familiar to your viewers).

So, if you have installed the tzinfo gem, you can then set the timezone when you use permatime helper:
(Without the tzinfo gem, this will issue a warning, and issue a UTC/GMT timezone, unless you explicitly specify a time )
 
  permatime(:timezone=>"US/Pacific")


Copyright (c) 2008 Tim Diggins, released under the MIT license