microformats 0.1 → 0.3

data/README.rdoc

@@ -1,4 +1,6 @@
-= MICROFORMATS
+= Microformats
+
+<b>STILL IN DEVELOPMENT, IT SHOULD WORK, BUT USE AT YOUR OWN RISK!</b>
 
 <em>Created by Chris Powers, September 11, 2010</em>
 
@@ -11,7 +13,7 @@ the new HTML5 Microdata standard.
 
 By using microformats, you are opening your data up to Google
 and other consumers for easy and intelligent consumption. In
-the future, Google plans on consuming microdata and making it
+the future, Google plans on making consumed microdata
 directly searchable, which yields all sorts of new potential
 for relevant results.
 
@@ -21,27 +23,33 @@ Install the Microformats gem as usual:
 
   gem install microformats
 
-== Usage: Vcards
+== Getting Started
+
+To use Microformats, first include the Microformats::Helper
+mixin into your view layer, like this in Rails:
+
+  # in app/helpers/application_helper.rb
+  module Application Helper
+    include Microformats::Helpers
+  end
+
+== Usage: vCards and Addresses
 
 You can easily markup a person and/or organization using the
-'vcard' helper method. This will use both the hCard Microformat
-and the http://www.data-vocabulary.org/Person/ microdata.
+<tt>vcard</tt> helper method. This will use both the hCard Microformat
+and the http://www.data-vocabulary.org/Person microdata.
 
-<strong>PLEASE NOTE:</strong> These two microdata standards do
+<b>PLEASE NOTE:</b> These two microdata standards do
 not support the same fields. For example, hCard gives a person
 telephone numbers and email addresses. The Person microdata only
-gives organizations a single telephone number and has no knowledge
-of emails. It does, however, have a photo field, which is missing
-from hCard.
+gives organizations a single telephone number and has no support
+for email.
 
-To use it, first include the Microformats::Helper mixin into your view
-layer, like this in Rails:
+vCards can embed addresses using the Microformats::Vcard#address
+method, which gives you a block to run with a new
+Microformats::Address object.
 
-  module Application Helper
-    include Microformats::Helpers
-  end
-
-Then, you can do something like this in your view (using ERB here):
+EXAMPLE (using ERB):
 
   <% vcard do |card| %>
     <%= card.photo "/images/me.jpg", :size => '200x300' %>
@@ -52,7 +60,7 @@ Then, you can do something like this in your view (using ERB here):
     <%= card.email "me@mydomain.com", :type => 'Home' %>
 
     I work at <%= card.company "Acme Co." %>
-    <% vcard_address(:type => 'Work') do |adr| %>
+    <% card.address(:type => 'Work') do |adr| %>
       <%= adr.street "123 Main" %>
       <%= adr.city "Chicago" %>, <%= adr.state 'IL' %> <%= adr.zip '60010' %>
     <% end %>
@@ -62,16 +70,16 @@ Then, you can do something like this in your view (using ERB here):
 This will output the following markup:
 
   <div class='vcard' itemscope='itemscope' itemtype='http://data-vocabulary.org/Person'>
-    <img itemprop='photo' src='/images/me.jpg' width='200' height='300' />
+    <img class='photo' itemprop='photo' src='/images/me.jpg' width='200' height='300' />
     <span class='fn' itemprop='name'>John Doe</span>
     <a class='url' href='http://mydomain.com' itemprop='url'>Visit my Site</a>
-    <span class='tel'><span class='type'>Home</span> 999.888.7766</span>
-    <span class='tel'><span class='type'>Work</span> 111.222.3344</span>
-    <span class='email'><span class='type'>Home</span> me@mydomain.com</span>
+    <span class='tel'><span class='type'><span class='value-title' title='Home'></span></span>999.888.7766</span>
+    <span class='tel'><span class='type'><span class='value-title' title='Work'></span></span> 111.222.3344</span>
+    <a class='email' href='mailto:me@mydomain.com'><span class='value-title' title='Home'></span>me@mydomain.com</span>
 
     I work at <span class='org' itemprop='affiliation'>Acme Co.</span>
     <div class='adr' itemscope='itemscope' itemtype='http://data-vocabulary.org/Address'>
-      <span class='type'>Work</span>
+      <span class='type'><span class='value-title' title='Work'></span></span>
       <span class='street-address' itemprop='street-address'>123 Main</span>
       <span class='locality' itemprop='locality'>Chicago</span>, <span class='region' itemprop='region'>IL</span> <span class='postal-code' itemprop='postal-code'>60010</span>
     </div>
@@ -81,7 +89,7 @@ This will output the following markup:
 While these helper methods default to using <span> tags
 (and <a> tags as appropriate), you can easily customize
 the tag used for any given piece of microdata by using the
-<tt>:tag</tt> options:
+<tt>:tag</tt> option:
 
   <%= card.name "John Doe", :tag => :h1 %>
 
@@ -93,3 +101,47 @@ currently on, so this is a quick way to do this in Rails:
 
   <%= card.download_link request.request_uri %>
 
+== Usage: Calendars and Events
+
+Calendars with many events can be represented using the
+Microformats::Calendar and Microformats::Event classes.
+This employs the hCal and hEvent microformats along with the
+http://www.data-vocabulary.org/Event microdata.
+
+<b>NOTE:</b> An Event can use a nested vCard to represent
+its location information.
+
+EXAMPLE:
+
+  <% vcalendar :id => "my_calendar" do |cal| %>
+    <h1>Upcoming Events</h1>
+    <% cal.event do |event| %>
+      <h2><%= event.url(event.name("Happy Hour"), :href => "http://meetup.com/happyhour") %></h2>
+      <%= event.photo "/images/happy_hour.jpg", :size => "250x150" %>
+      <%= event.description "Come hang out with us for half price drinks at lots of fun!" %>
+      <span class='time_range'>
+        From <%= event.starts_at "October 30, 2010 at 7:30PM" %> -
+        <%= event.ends_at "October 30, 2010 at 10:00PM", :text => "10:00PM" %>
+      </span>
+      <% event.location do |card| %>
+        <%= card.url(card.company("Frank's Bar", :is_company => true), :href => "http://franksbar.com") %>
+        <% card.address do |adr| %>
+          <%= adr.street "784 N Main St" %><br />
+          <%= adr.city "Chicago" %>, <%= adr.state "IL" %> <%= adr.zip "60016" %>
+        <% end %>
+      <% end %>
+    <% end %>
+    <!-- More events could be added... -->
+  <% end %>
+
+== Resources
+
+* http://www.data-vocabulary.org
+* http://microformats.org
+
+== Care to Help?
+
+There are still a lot of standards that need to be implemented into
+this library, including but not limited to: Events, Products, Reviews,
+Organizations. I will continue to work on these, but I'd be happy to
+accept pull requests!

data/Rakefile

@@ -1,6 +1,6 @@
 require 'rubygems'
 require 'rake'
-# require 'rake/rdoctask'
+require 'rake/rdoctask'
 # require 'rake/gempackagetask'
 # require 'rcov/rcovtask'
 # require 'date'
@@ -12,4 +12,16 @@ task :default => :spec
 
 Spec::Rake::SpecTask.new do |t|
   t.warning = true
-end
+end
+
+namespace :doc do
+  desc "Generate documentation for the gem."
+  Rake::RDocTask.new("gem") { |rdoc|
+    rdoc.rdoc_dir = 'doc'
+    rdoc.title    = "Microformats"
+    rdoc.options << '--line-numbers' << '--inline-source'
+    rdoc.options << '--charset' << 'utf-8'
+    rdoc.rdoc_files.include('README.rdoc')
+    rdoc.rdoc_files.include('lib/**/*.rb')
+  }
+end

data/lib/address.rb

@@ -1,32 +1,97 @@
 class Microformats::Address
+  include Microformats::FormattingHelpers
+
+  def initialize(template)
+    @template = template
+    @default_tag = :span
+  end
+
+  # You can directly initialize and run this class, but it's easier
+  # to use the Microformats::Helpers#vaddress helper method or the
+  # Microformats::Vcard#address method.
+  #
+  # OPTIONS:
+  # * :type - A string that specifies the type of address('home', 'work', etc)
+  # * :tag - The HTML wrapper element (defaults to :div)
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  def run(opts = {}, &block)
+    type = opts[:type] ? self.type(opts.delete(:type)) : nil
+    opts[:class] = combine_class_names('adr', opts[:class])
+    opts[:itemscope] = 'itemscope'
+    opts[:itemtype] = 'http://data-vocabulary.org/Address'
+    opts[:tag] ||= :div
+    concat_tag(opts) do
+      concat type if type
+      block.call(self)
+    end
+  end
+
+  # Outputs markup for the type of address ('work', 'home', etc.)
+  # There will be no visible text unless provided with the :text option.
+  #
+  # <em>NOTE: You get this for free with the :type option of
+  # Microformats::Helpers#vaddress, Microformats::Vcard#address and #run methods.</em>
+  #
+  # OPTIONS
+  # * :text - String, the text you want displayed as a text node (default is '')
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  def type(str, opts = {})
+    inner = content_tag('', :class => 'value-title', :title => str)
+    text = opts.delete(:text) || ''
+    content_tag(inner + text, merge_html_attrs({:class => 'type'}, opts))
+  end
+
+  # Outputs the passed string as a street address.
+  #
+  # OPTIONS
+  # * :tag - The HTML wrapper element (defaults to :span)
+  # * Any other passed options will be treated as HTML attributes.
+  #
   def street(str, opts = {})
-    content_tag(opts[:tag] || :span, str, :class => 'street-address', :itemprop => 'street-address')
+    content_tag(str, merge_html_attrs({:class => 'street-address', :itemprop => 'street-address'}, opts))
   end
 
+  # Outputs the passed string as a city.
+  #
+  # OPTIONS
+  # * :tag - The HTML wrapper element (defaults to :span)
+  # * Any other passed options will be treated as HTML attributes.
+  #
   def city(str, opts = {})
-    content_tag(opts[:tag] || :span, str, :class => 'locality', :itemprop => 'locality')
+    content_tag(str, merge_html_attrs({:class => 'locality', :itemprop => 'locality'}, opts))
   end
 
+  # Outputs the passed string as a state.
+  #
+  # OPTIONS
+  # * :tag - The HTML wrapper element (defaults to :span)
+  # * Any other passed options will be treated as HTML attributes.
+  #
   def state(str, opts = {})
-    content_tag(opts[:tag] || :span, str, :class => 'region', :itemprop => 'region')
+    content_tag(str, merge_html_attrs({:class => 'region', :itemprop => 'region'}, opts))
   end
 
+  # Outputs the passed string as a postal code.
+  #
+  # OPTIONS
+  # * :tag - The HTML wrapper element (defaults to :span)
+  # * Any other passed options will be treated as HTML attributes.
+  #
   def zip(str, opts = {})
-    content_tag(opts[:tag] || :span, str, :class => 'postal-code', :itemprop => 'postal-code')
+    content_tag(str, merge_html_attrs({:class => 'postal-code', :itemprop => 'postal-code'}, opts))
   end
   alias_method :postal_code, :zip
 
+  # Outputs the passed string as a country.
+  #
+  # OPTIONS
+  # * :tag - The HTML wrapper element (defaults to :span)
+  # * Any other passed options will be treated as HTML attributes.
+  #
   def country(str, opts = {})
-    content_tag(opts[:tag] || :span, str, :class => 'country-name', :itemprop => 'country-name')
+    content_tag(str, merge_html_attrs({:class => 'country-name', :itemprop => 'country-name'}, opts))
   end
 
-  def content_tag(tag, content, opts={})
-    attrs = opts.inject([]) do |out, tuple|
-      k,v = tuple
-      out << "#{k}='#{v}'"
-    end
-    attr_string = attrs.sort.join(' ')
-    open_tag = attr_string == '' ? tag : "#{tag} #{attr_string}"
-    "<#{open_tag}>#{content}</#{tag}>"
-  end
 end

data/lib/calendar.rb

@@ -0,0 +1,40 @@
+class Microformats::Calendar
+  include Microformats::FormattingHelpers
+
+  def initialize(template)
+    @template = template
+    @default_tag = :span
+  end
+
+  # You can directly initialize and run this class, but it's easier
+  # to use the Microformats::Helpers#vcalendar helper method.
+  #
+  # OPTIONS:
+  # * :tag - The HTML wrapper element (defaults to :div)
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  def run(opts = {}, &block)
+    opts[:class] = combine_class_names('vcalendar', opts[:class])
+    opts[:tag] ||= :div
+    concat_tag(opts) do
+      block.call(self)
+    end
+  end
+
+  # Creates a vEvent with the given options and a block.
+  #
+  # OPTIONS:
+  # * :tag - The HTML wrapper element (defaults to :div)
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  # EXAMPLE:
+  #   <% calendar.event :id => 'my_event' do |event| %>
+  #     This event is called <%= event.name "Cool Event" %>.
+  #   <% end %>
+  #
+  def event(opts = {}, &block)
+    ev = Microformats::Event.new(@template)
+    opts[:class] = combine_class_names('vevent', opts[:class])
+    ev.run(opts, &block)
+  end
+end

data/lib/event.rb

@@ -0,0 +1,156 @@
+class Microformats::Event
+  include Microformats::FormattingHelpers
+
+  def initialize(template)
+    @template = template
+    @default_tag = :span
+  end
+
+  # You can directly initialize and run this class, but it's easier
+  # to use the Microformats::Helpers#vevent helper method or the
+  # Microformats::Calendar#event method.
+  #
+  # OPTIONS:
+  # * :tag - The HTML wrapper element (defaults to :div)
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  def run(opts = {}, &block)
+    opts[:class] = combine_class_names('vevent', opts[:class])
+    opts[:itemscope] = 'itemscope'
+    opts[:itemtype] = 'http://data-vocabulary.org/Event'
+    opts[:tag] ||= :div
+    concat_tag(opts) do
+      block.call(self)
+    end
+  end
+
+  # Marks up an event's name.
+  #
+  # OPTIONS:
+  # * :tag - The HTML wrapper element (defaults to :span)
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  def name(str, opts={})
+    content_tag(str, merge_html_attrs({:itemprop => 'summary', :class => 'summary'}, opts))
+  end
+
+  # Marks up the event's URL. By default, it will output an <a> tag using
+  # the passed in string as both the href and the text. If the :href option
+  # is passed, then the string argument is treated as text.
+  #
+  # OPTIONS:
+  # * :href - If passed, the string argument will be treated as the text node.
+  # * :tag - The HTML wrapper element (defaults to :span)
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  # EXAMPLES:
+  #   event.url('http://google.com') #=> <a class='url' href='http://google.com' itemprop='url'>http://google.com</a>
+  #   event.url('Google', :href => 'http://google.com') #=> <a class='url' href='http://google.com' itemprop='url'>Google</a>
+  #   event.url('http://google.com', :tag => :span) #=> <span class='url' itemprop='url'>http://google.com</span>
+  #
+  def url(str, opts = {})
+    if opts[:href]
+      content_tag(str, merge_html_attrs({:tag => :a, :class => 'url', :itemprop => 'url'}, opts))
+    elsif opts[:tag]
+      content_tag(str, merge_html_attrs({:class => 'url', :itemprop => 'url'}, opts))
+    else
+      content_tag(str, merge_html_attrs({:tag => :a, :class => 'url', :href => str, :itemprop => 'url'}, opts))
+    end
+  end
+
+  # Marks up the event photo as an <img> tag. Takes the image URL as the first argument.
+  #
+  # OPTIONS
+  # * :size - Pass a string with WIDTHxHEIGHT like "200x100" in lieu of the :width and :height options.
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  def photo(str, opts = {})
+    if size = opts.delete(:size)
+      opts[:width], opts[:height] = size.split('x')
+    end
+    content_tag(nil, merge_html_attrs({:tag => :img, :class => 'photo', :itemprop => 'photo', :src => str}, opts))
+  end
+
+  # Marks up an event's description.
+  #
+  # OPTIONS:
+  # * :tag - The HTML wrapper element (defaults to :span)
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  def description(str, opts={})
+    content_tag(str, merge_html_attrs({:itemprop => 'description', :class => 'description'}, opts))
+  end
+
+  # Marks up the event's start time/date. Accepts either a Time object
+  # or a time String as the first argument. By default, the text node
+  # will be the date and time output like "Oct 20, 2010 at 7:30PM", but
+  # this can be overridden by the :text option.
+  #
+  # OPTIONS:
+  # * :text - String, will be displayed as the text node.
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  def starts_at(time_or_str, opts={})
+    if time_or_str.is_a?(String)
+      time = Time.parse(time_or_str)
+      encoded_time = encode_time(time)
+      humanized_time = opts.delete(:text) || time_or_str
+    else
+      encoded_time = encode_time(time_or_str)
+      humanized_time = opts.delete(:text) || humanize_time(time_or_str)
+    end
+    inner_span = content_tag('', :class => 'value-title', :title => encoded_time)
+    content_tag(inner_span + humanized_time, merge_html_attrs({:tag => :time, :itemprop => 'startDate', :class => 'dtstart', :datetime => encoded_time}, opts))
+  end
+
+  # Marks up the event's end time/date. Accepts either a Time object
+  # or a time String as the first argument. By default, the text node
+  # will be the date and time output like "Oct 20, 2010 at 7:30PM", but
+  # this can be overridden by the :text option.
+  #
+  # OPTIONS:
+  # * :text - String, will be displayed as the text node.
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  def ends_at(time_or_str, opts={})
+    if time_or_str.is_a?(String)
+      time = Time.parse(time_or_str)
+      encoded_time = encode_time(time)
+      humanized_time = opts.delete(:text) || time_or_str
+    else
+      encoded_time = encode_time(time_or_str)
+      humanized_time = opts.delete(:text) || humanize_time(time_or_str)
+    end
+    inner_span = content_tag('', :class => 'value-title', :title => encoded_time)
+    content_tag(inner_span + humanized_time, merge_html_attrs({:tag => :time, :itemprop => 'endDate', :class => 'dtend', :datetime => encoded_time}, opts))
+  end
+
+  # Marks up an event's category name.
+  #
+  # OPTIONS:
+  # * :tag - The HTML wrapper element (defaults to :span)
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  def category(str, opts = {})
+    content_tag(str, merge_html_attrs({:itemprop => 'eventType', :class => 'category'}, opts))
+  end
+
+  # Creates a vCard with the given options and a block to represent
+  # the event's location.
+  #
+  # OPTIONS:
+  # * :tag - The HTML wrapper element (defaults to :div)
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  # EXAMPLE:
+  #   <% event.location :id => 'my_location' do |card| %>
+  #     We will be meeting at the <%= card.company "Obtiva" %> office.
+  #   <% end %>
+  #
+  def location(opts = {}, &block)
+    card = Microformats::Vcard.new(@template)
+    opts[:class] = combine_class_names('location', opts[:class])
+    card.run(opts, &block)
+  end
+
+end

data/lib/formatting_helpers.rb

@@ -0,0 +1,57 @@
+# These are all internal methods used for formatting, no need
+# to use any of them explicitly.
+#
+module Microformats::FormattingHelpers # :nodoc:
+  def content_tag(content, opts={}) # :nodoc:
+    tag = opts.delete(:tag) || @default_tag
+    attrs = opts.inject([]) do |out, tuple|
+      k,v = tuple
+      out << "#{k}='#{v}'" if v
+      out
+    end
+    attr_string = attrs.sort.join(' ')
+    open_tag = attr_string == '' ? tag : "#{tag} #{attr_string}"
+    if [:img].include?(tag)
+      "<#{open_tag} />"
+    else
+      "<#{open_tag}>#{content}</#{tag}>"
+    end
+  end
+
+  def concat_tag(opts={}) # :nodoc:
+    tag = opts.delete(:tag) || @default_tag
+    attrs = opts.inject([]) do |out, tuple|
+      k,v = tuple
+      out << "#{k}='#{v}'"
+    end
+    attr_string = attrs.sort.join(' ')
+    open_tag = attr_string == '' ? tag : "#{tag} #{attr_string}"
+    concat "<#{open_tag}>\n"
+    yield
+    concat "</#{tag}>\n"
+  end
+
+  def merge_html_attrs(base_attrs, overriding_attrs) # :nodoc:
+    classes = combine_class_names(base_attrs.delete(:class), overriding_attrs.delete(:class))
+    attrs = base_attrs.merge(overriding_attrs)
+    attrs[:class] = classes unless classes == ''
+    attrs
+  end
+
+  def concat(str) # :nodoc:
+    @template.concat(str)
+  end
+
+  def encode_time(t) # :nodoc:
+    t.strftime("%Y-%m-%dT%H:%M%z").gsub(/00$/, ":00")
+  end
+
+  def humanize_time(t) # :nodoc:
+    t.strftime("%b %d, %Y at %I:%M%p").gsub(/\s0/, ' ')
+  end
+
+  def combine_class_names(*classes) # :nodoc:
+    str = classes.flatten.compact.sort.join(' ').gsub(/\s+/, ' ')
+    (str =~ /\w/) ? str : nil
+  end
+end

data/lib/helpers.rb

@@ -1,21 +1,74 @@
+# Include this file into your view layer. For example, in Rails:
+#
+#   module ApplicationHelper
+#     include Microformats::Helpers
+#   end
+#
 module Microformats::Helpers
-  # FIXME: Figure out how to make this non-Rails specific
-  # i.e. not rely on using concat
-  def vcard(&block)
-    concat "<div class='vcard' itemscope='itemscope' itemtype='http://data-vocabulary.org/Person'>\n"
-    block.call(Microformats::Vcard.new)
-    concat "</div>\n"
+  # Creates a vCard with the given options and a block.
+  #
+  # OPTIONS:
+  # * :tag - The HTML wrapper element (defaults to :div)
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  # EXAMPLE:
+  #   <% vcard :id => 'my_vcard' do |card| %>
+  #     Hello, my name is <%= card.name "Chris" %>!
+  #   <% end %>
+  #
+  def vcard(opts = {}, &block)
+    card = Microformats::Vcard.new(self)
+    card.run(opts, &block)
   end
 
-  # FIXME: Figure out how to make this non-Rails specific
-  # i.e. not rely on using concat
-  def vcard_address(opts = {}, &block)
-    address = Microformats::Address.new
-    type = opts[:type] ? address.content_tag(:span, opts[:type], :class => 'type') : nil
-    concat "<div class='adr' itemscope='itemscope' itemtype='http://data-vocabulary.org/Address'>\n"
-    concat type if type
-    block.call(address)
-    concat "</div>\n"
+  # Creates a vAddress with the given options and a block.
+  #
+  # OPTIONS:
+  # * :type - A string that specifies the type of address('home', 'work', etc)
+  # * :tag - The HTML wrapper element (defaults to :div)
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  # EXAMPLE:
+  #   <% vaddress :type => 'work', :id => 'my_adr' do |adr| %>
+  #     I live at <%= adr.street "123 Main St" %>.
+  #   <% end %>
+  #
+  def vaddress(opts = {}, &block)
+    address = Microformats::Address.new(self)
+    address.run(opts, &block)
   end
 
+  # Creates a vEvent with the given options and a block.
+  #
+  # OPTIONS:
+  # * :tag - The HTML wrapper element (defaults to :div)
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  # EXAMPLE:
+  #   <% vevent :id => 'my_event' do |event| %>
+  #     This event is called <%= event.name "Cool Event" %>.
+  #   <% end %>
+  #
+  def vevent(opts = {}, &block)
+    event = Microformats::Event.new(self)
+    event.run(opts, &block)
+  end
+
+  # Creates a vCalendar with the given options and a block.
+  #
+  # OPTIONS:
+  # * :tag - The HTML wrapper element (defaults to :div)
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  # EXAMPLE:
+  #   <% vcalendar :id => 'my_cal' do |cal| %>
+  #     <% cal.event :id => 'my_event' do |event| %>
+  #       This event is called <%= event.name "Cool Event" %>.
+  #     <% end %>
+  #   <% end %>
+  #
+  def vcalendar(opts = {}, &block)
+    cal = Microformats::Calendar.new(self)
+    cal.run(opts, &block)
+  end
 end

data/lib/microformats.rb

@@ -2,6 +2,11 @@ module Microformats
 
 end
 
+require 'time'
+
+require 'formatting_helpers'
 require 'vcard'
 require 'address'
+require 'calendar'
+require 'event'
 require 'helpers'

data/lib/vcard.rb

@@ -1,70 +1,177 @@
 class Microformats::Vcard
-  def initialize
+  include Microformats::FormattingHelpers
+
+  # You can directly initialize and runthis class, but it's easier
+  # to use the Microformats::Helpers#vcard helper method.
+  def initialize(template)
+    @template = template
     @default_tag = :span
   end
 
+  # You can directly initialize and runthis class, but it's easier
+  # to use the Microformats::Helpers#vcard helper method.
+  #
+  # OPTIONS:
+  # * :tag - The HTML wrapper element (defaults to :div)
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  def run(opts = {}, &block)
+    opts[:class] = combine_class_names('vcard', opts[:class])
+    opts[:itemscope] = 'itemscope'
+    opts[:itemtype] = 'http://data-vocabulary.org/Person'
+    opts[:tag] ||= :div
+    concat_tag(opts) do
+      block.call(self)
+    end
+  end
+
+  # Marks up a person's name.
+  #
+  # OPTIONS:
+  # * :tag - The HTML wrapper element (defaults to :span)
+  # * Any other passed options will be treated as HTML attributes.
+  #
   def name(str, opts = {})
-    content_tag(opts[:tag] || :span, str, :class => 'fn', :itemprop => 'name')
+    content_tag(str, merge_html_attrs({:class => 'fn', :itemprop => 'name'}, opts))
   end
 
+  # Marks up a company name. If this vCard represents a company
+  # rather than an individual person that works at a company, set
+  # the :is_company option to true.
+  #
+  # OPTIONS:
+  # * :is_company - Boolean, true if this is a company vCard (defaults to false)
+  # * :tag - The HTML wrapper element (defaults to :span)
+  # * Any other passed options will be treated as HTML attributes.
+  #
   def company(str, opts = {})
-    content_tag(opts[:tag] || :span, str, :class => 'org', :itemprop => 'affiliation')
+    classes = opts.delete(:is_company) ? 'fn org' : 'org'
+    content_tag(str, merge_html_attrs({:class => classes, :itemprop => 'affiliation'}, opts))
   end
   alias_method :organization, :company
 
+  # Marks up the person's URL. By default, it will output an <a> tag using
+  # the passed in string as both the href and the text. If the :href option
+  # is passed, then the string argument is treated as text.
+  #
+  # OPTIONS:
+  # * :href - If passed, the string argument will be treated as the text node.
+  # * :tag - The HTML wrapper element (defaults to :span)
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  # EXAMPLES:
+  #   card.url('http://google.com') #=> <a class='url' href='http://google.com' itemprop='url'>http://google.com</a>
+  #   card.url('Google', :href => 'http://google.com') #=> <a class='url' href='http://google.com' itemprop='url'>Google</a>
+  #   card.url('http://google.com', :tag => :span) #=> <span class='url' itemprop='url'>http://google.com</span>
+  #
   def url(str, opts = {})
     if opts[:href]
-      content_tag(:a, str, :href => opts[:href], :class => 'url', :itemprop => 'url')
+      content_tag(str, merge_html_attrs({:tag => :a, :class => 'url', :itemprop => 'url'}, opts))
     elsif opts[:tag]
-      content_tag(opts[:tag], str, :class => 'url', :itemprop => 'url')
+      content_tag(str, merge_html_attrs({:class => 'url', :itemprop => 'url'}, opts))
     else
-      content_tag(:a, str, :class => 'url', :href => str, :itemprop => 'url')
+      content_tag(str, merge_html_attrs({:tag => :a, :class => 'url', :href => str, :itemprop => 'url'}, opts))
     end
   end
 
+  # Marks up the vCard photo as an <img> tag. Takes the image URL as the first argument.
+  #
+  # OPTIONS
+  # * :size - Pass a string with WIDTHxHEIGHT like "200x100" in lieu of the :width and :height options.
+  # * Any other passed options will be treated as HTML attributes.
+  #
   def photo(str, opts = {})
-    image_tag(str, opts.merge(:itemprop => 'photo'))
+    if size = opts.delete(:size)
+      opts[:width], opts[:height] = size.split('x')
+    end
+    content_tag(nil, merge_html_attrs({:tag => :img, :class => 'photo', :itemprop => 'photo', :src => str}, opts))
   end
 
+  # Marks up a phone number, takes the phone number as a string.
+  #
+  # OPTIONS
+  # * :type - A string that specifies the type of phone number ('home', 'work', etc)
+  # * :tag - The HTML wrapper element (defaults to :span)
+  # * Any other passed options will be treated as HTML attributes.
+  #
   def phone(str, opts = {})
-    type = opts[:type] ? content_tag(:span, opts[:type], :class => 'type') + ' ' : ''
-    content_tag(opts[:tag] || :span, type + str, :class => 'tel')
+    type = if opts[:type].to_s != ''
+      type_inner_span = content_tag('', :class => 'value-title', :title => opts.delete(:type))
+      content_tag(type_inner_span, :class => 'type')
+    else
+      ''
+    end
+    content_tag(type + str, merge_html_attrs({:class => 'tel'}, opts))
   end
 
+  # Marks up an email address, takes the email as a string.
+  #
+  # OPTIONS
+  # * :type - A string that specifies the type of phone number ('home', 'work', etc)
+  # * :tag - The HTML wrapper element (defaults to :a)
+  # * Any other passed options will be treated as HTML attributes.
+  #
   def email(str, opts = {})
-    type = opts[:type] ? content_tag(:span, opts[:type], :class => 'type') + ' ' : ''
+    opts[:tag] ||= :a
+    type = if opts[:type].to_s != ''
+      type_inner_span = content_tag('', :class => 'value-title', :title => opts.delete(:type))
+      content_tag(type_inner_span, :class => 'type')
+    else
+      ''
+    end
     if opts[:tag] == :a
-      content_tag(:a, type + str, :class => 'email', :href => "mailto:#{str}")
+      content_tag(type + str, merge_html_attrs({:class => 'email', :href => "mailto:#{str}"}, opts))
     else
-      content_tag(opts[:tag] || :span, type + str, :class => 'email')
+      content_tag(type + str, merge_html_attrs({:class => 'email'}, opts))
     end
   end
 
+  # Accepts latitude and longitude as arguments. It will only output a
+  # visible text node if you provide the :text option.
+  #
+  # OPTIONS
+  # * :text - String, the text will be be displayed inside the 'geo' wrapper
+  #
+  def coordinates(lat, lng, opts = {})
+    lat_meta = content_tag('', :tag => :meta, :itemprop => 'latitude', :content => lat)
+    lng_meta = content_tag('', :tag => :meta, :itemprop => 'longitude', :content => lng)
+    lat_span = content_tag(content_tag('', :class => 'value-title', :title => lat), :class => 'latitude')
+    lng_span = content_tag(content_tag('', :class => 'value-title', :title => lng), :class => 'longitude')
+    text = opts[:text] || ''
+    content_tag(lat_meta + lng_meta + lat_span + lng_span + text, :class => 'geo', :itemprop => 'geo', :itemscope => 'itemscope', :itemtype => 'http://data-vocabulary.org/Geo')
+  end
+
+  # Outputs a link to h2vx.com that will let the user download the vcard
+  # at the passed URL.
+  #
+  # OPTIONS
+  # * :text - The link text (default is "Download vCard")
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  # EXAMPLE
+  #   <%# In Rails, request.request_uri returns the URL of this page %>
+  #   <%= card.download_link request.request_uri %>
+  #
   def download_link(url, opts = {})
     str = opts.delete(:text) || "Download vCard"
     new_url = "http://h2vx.com/vcf/" + url.gsub("http://", '')
-    content_tag(:a, str, :href => new_url, :type => 'text/directory')
-  end
-
-  def content_tag(tag, content, opts={})
-    attrs = opts.inject([]) do |out, tuple|
-      k,v = tuple
-      out << "#{k}='#{v}'"
-    end
-    attr_string = attrs.sort.join(' ')
-    open_tag = attr_string == '' ? tag : "#{tag} #{attr_string}"
-    if [:img].include?(tag)
-      "<#{open_tag} />"
-    else
-      "<#{open_tag}>#{content}</#{tag}>"
-    end
+    content_tag(str, merge_html_attrs({:tag => :a, :href => new_url, :type => 'text/directory'}, opts))
   end
 
-  def image_tag(src, opts={})
-    if size = opts.delete(:size)
-      opts[:width], opts[:height] = size.split('x')
-    end
-    opts[:src] = src
-    content_tag(:img, nil, opts)
+  # Opens a new block for a nested vAddress.
+  #
+  # OPTIONS:
+  # * :type - A string that specifies the type of address('home', 'work', etc)
+  # * :tag - The HTML wrapper element (defaults to :div)
+  # * Any other passed options will be treated as HTML attributes.
+  #
+  # EXAMPLE:
+  #   <% card.address :type => 'work', :id => 'my_adr' do |adr| %>
+  #     I live at <%= adr.street "123 Main St" %>.
+  #   <% end %>
+  #
+  def address(opts = {}, &block)
+    adr = Microformats::Address.new(@template)
+    adr.run(opts, &block)
   end
 end

metadata

@@ -1,12 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: microformats
 version: !ruby/object:Gem::Version 
-  hash: 9
+  hash: 13
   prerelease: false
   segments: 
   - 0
-  - 1
-  version: "0.1"
+  - 3
+  version: "0.3"
 platform: ruby
 authors: 
 - Chris Powers
@@ -31,14 +31,13 @@ files:
 - CHANGELOG.rdoc
 - LICENSE
 - Rakefile
-- lib/microformats.rb
 - lib/address.rb
+- lib/calendar.rb
+- lib/event.rb
+- lib/formatting_helpers.rb
 - lib/helpers.rb
+- lib/microformats.rb
 - lib/vcard.rb
-- spec/address_spec.rb
-- spec/helpers_spec.rb
-- spec/spec_helper.rb
-- spec/vcard_spec.rb
 has_rdoc: true
 homepage: http://github.com/chrisjpowers/microformats
 licenses: []

data/spec/address_spec.rb

@@ -1,57 +0,0 @@
-require 'spec_helper'
-
-describe Microformats::Address do
-  before(:each) do
-    @address = Microformats::Address.new
-  end
-  
-  describe "street" do
-    it "should wrap the string with street-address" do
-      @address.street("123 Main").should == "<span class='street-address' itemprop='street-address'>123 Main</span>"
-    end
-    
-    it "should use the given tag" do
-      @address.street("123 Main", :tag => :strong).should == "<strong class='street-address' itemprop='street-address'>123 Main</strong>"
-    end
-  end
-  
-  describe "city" do
-    it "should wrap the string with locality" do
-      @address.city("Chicago").should == "<span class='locality' itemprop='locality'>Chicago</span>"
-    end
-    
-    it "should use the given tag" do
-      @address.city("Chicago", :tag => :strong).should == "<strong class='locality' itemprop='locality'>Chicago</strong>"
-    end
-  end
-  
-  describe "state" do
-    it "should wrap the string with region" do
-      @address.state("IL").should == "<span class='region' itemprop='region'>IL</span>"
-    end
-    
-    it "should use the given tag" do
-      @address.state("IL", :tag => :strong).should == "<strong class='region' itemprop='region'>IL</strong>"
-    end
-  end
-  
-  describe "zip" do
-    it "should wrap the string with postal-code" do
-      @address.zip("60085").should == "<span class='postal-code' itemprop='postal-code'>60085</span>"
-    end
-    
-    it "should use the given tag" do
-      @address.zip("60085", :tag => :strong).should == "<strong class='postal-code' itemprop='postal-code'>60085</strong>"
-    end
-  end
-  
-  describe "country" do
-    it "should wrap the string with country-name" do
-      @address.country("USA").should == "<span class='country-name' itemprop='country-name'>USA</span>"
-    end
-    
-    it "should use the given tag" do
-      @address.country("USA", :tag => :strong).should == "<strong class='country-name' itemprop='country-name'>USA</strong>"
-    end
-  end
-end

data/spec/helpers_spec.rb

@@ -1,52 +0,0 @@
-require 'spec_helper'
-
-describe Microformats::Helpers do
-  class MyTester
-    include Microformats::Helpers
-    
-    def concat(str)
-      @output ||= ''
-      @output << str
-    end
-    
-    def output
-      @output
-    end
-  end
-  
-  before(:each) do
-    @tester = MyTester.new
-  end
-  
-  describe "vcard" do
-    it "should wrap a block in a vcard div" do
-      @tester.should_receive(:do_something)
-      @tester.vcard do
-        @tester.do_something
-      end
-      @tester.output.should == "<div class='vcard' itemscope='itemscope' itemtype='http://data-vocabulary.org/Person'>\n</div>\n"
-    end
-  end
-  
-  describe "vcard_address" do
-    context "with type" do
-      it "should wrap the block in an adr div and output the type" do
-        @tester.should_receive(:do_something)
-        @tester.vcard_address :type => 'Work' do
-          @tester.do_something
-        end
-        @tester.output.should == "<div class='adr' itemscope='itemscope' itemtype='http://data-vocabulary.org/Address'>\n<span class='type'>Work</span></div>\n"
-      end
-    end
-    
-    context "without type" do
-      it "should wrap the block in an adr div" do
-        @tester.should_receive(:do_something)
-        @tester.vcard_address do
-          @tester.do_something
-        end
-        @tester.output.should == "<div class='adr' itemscope='itemscope' itemtype='http://data-vocabulary.org/Address'>\n</div>\n"
-      end
-    end
-  end
-end

data/spec/spec_helper.rb

@@ -1 +0,0 @@
-require File.join(File.dirname(__FILE__), '..', 'lib', 'microformats.rb')

data/spec/vcard_spec.rb

@@ -1,110 +0,0 @@
-require 'spec_helper'
-
-describe Microformats::Vcard do
-  before(:each) do
-    @vcard = Microformats::Vcard.new
-  end
-  
-  describe "name" do
-    it "should wrap a string with fn class, default to span" do
-      @vcard.name("John Doe").should == "<span class='fn' itemprop='name'>John Doe</span>"
-    end
-    
-    it "should use the given tag" do
-      @vcard.name("John Doe", :tag => :strong).should == "<strong class='fn' itemprop='name'>John Doe</strong>"
-    end
-  end
-  
-  describe "company" do
-    it "should wrap a string with org class, default to span" do
-      @vcard.company("Acme Co.").should == "<span class='org' itemprop='affiliation'>Acme Co.</span>"
-    end
-    
-    it "should use the given tag" do
-      @vcard.company("Acme Co.", :tag => :strong).should == "<strong class='org' itemprop='affiliation'>Acme Co.</strong>"
-    end
-  end
-  
-  describe "url" do
-    it "should default to a tag with url class, using the URL for text and href" do
-      @vcard.url("http://google.com").should == "<a class='url' href='http://google.com' itemprop='url'>http://google.com</a>"
-    end
-    
-    it "should use given href" do
-      @vcard.url('Google', :href => "http://google.com").should == "<a class='url' href='http://google.com' itemprop='url'>Google</a>"
-    end
-    
-    it "should use given tag" do
-      @vcard.url('http://google.com', :tag => :strong).should == "<strong class='url' itemprop='url'>http://google.com</strong>"
-    end
-  end
-  
-  describe "photo" do
-    it "should create an image tag using the passed string as the src, adding itemprop photo" do
-      @vcard.photo("/images/me.png").should == "<img itemprop='photo' src='/images/me.png' />"
-    end
-    
-    it "should use :size option to set width and height" do
-      @vcard.photo("/images/me.png", :size => "200x100").should == "<img height='100' itemprop='photo' src='/images/me.png' width='200' />"
-    end
-    
-    it "should pass through options" do
-      @vcard.photo("/images/me.png", :height => 100, :width => 200).should == "<img height='100' itemprop='photo' src='/images/me.png' width='200' />"
-    end
-    
-  end
-  
-  describe "phone" do
-    it "should wrap string with a tel class" do
-      @vcard.phone('123.456.7890').should == "<span class='tel'>123.456.7890</span>"
-    end
-    
-    it "should add a type span if given" do
-      out = @vcard.phone('123.456.7890', :type => 'Work')
-      out.should == "<span class='tel'><span class='type'>Work</span> 123.456.7890</span>"
-    end
-    
-    it "should use the given tag" do
-      out = @vcard.phone('123.456.7890', :type => 'Work', :tag => :strong)
-      out.should == "<strong class='tel'><span class='type'>Work</span> 123.456.7890</strong>"
-    end
-  end
-  
-  describe "email" do
-    it "should wrap string with a email class" do
-      @vcard.email('john@doe.com').should == "<span class='email'>john@doe.com</span>"
-    end
-    
-    it "should add a type span if given" do
-      out = @vcard.email('john@doe.com', :type => 'Work')
-      out.should == "<span class='email'><span class='type'>Work</span> john@doe.com</span>"
-    end
-    
-    it "should use the given tag" do
-      out = @vcard.email('john@doe.com', :type => 'Work', :tag => :strong)
-      out.should == "<strong class='email'><span class='type'>Work</span> john@doe.com</strong>"
-    end
-    
-    it "should use mailto if using an 'a' tag" do
-      out = @vcard.email('john@doe.com', :type => 'Work', :tag => :a)
-      out.should == "<a class='email' href='mailto:john@doe.com'><span class='type'>Work</span> john@doe.com</a>"
-    end
-  end
-  
-  describe "download_link" do
-    it "should output a link to h2vx.com using the passed url" do
-      out = @vcard.download_link('mydomain.com/page')
-      out.should == "<a href='http://h2vx.com/vcf/mydomain.com/page' type='text/directory'>Download vCard</a>"
-    end
-    
-    it "should strip the protocol from a passed url" do
-      out = @vcard.download_link('http://mydomain.com/page')
-      out.should == "<a href='http://h2vx.com/vcf/mydomain.com/page' type='text/directory'>Download vCard</a>"
-    end
-    
-    it "should use :text option as text node if present" do
-      out = @vcard.download_link('mydomain.com/page', :text => "Download Me Now")
-      out.should == "<a href='http://h2vx.com/vcf/mydomain.com/page' type='text/directory'>Download Me Now</a>"
-    end
-  end
-end