jlsuttles/microformats2-gem-ruby-interface.md

## microformats2-gem-ruby-interface.md

      
    Raw
  

              microformats2-gem-ruby-interface.md
            
          
    microformats2 gem ruby interface

The purpose of this document is to compare the current Ruby interfaces to the g5_hentry_consumer gem and the microformats2 gem.
Parsing A Document for Entries

g5_hentry_consumer

require "g5_hentry_consumer"

collection = G5HentryConsumer.parse(document, last_modified_at:  last_modified_at)
#=> G5HentryConsumer::HFeed instance

document must be a String containg a URL or a filepath
last_modified_at must be a DateTime object

microformats2

require "microformats2"

collection = Microformats2.parse(document) #=> Microformats2::Collection instance

document must be a String containing HTML, a URL, or a filepath.

Accessing Entries from Collection

g5_hentry_consumer

collection.entries #=> Array of G5HentryConsumer::HEntry instances
microformats2

# plural
collection.entries #=> Array of Microformats2::HEntry instances
# singular
collection.entry #=> collection.entries.first

HEntry is automagically defined when an .h-entry is found
Collection#enties and Collection#entry are automagically defined when an .h-entry is found.

Accessing Cards from Collection

g5_hentry_consumer

?
microformats2

# plural
collection.cards #=> Array of Microformats2::HCard instances
# singular
collection.card #=> collection.cards.first

HCard is automagically defined when an .h-card is found
Collection#cards and Collection#card are automagically defined when an .h-card is found.

Accessing Name String from Entry

g5_hentry_consumer

collection.entries.first.name #=> Array
collection.entries.first.name.first #=> "Jessica"
microformats2

# plurarl
collection.entries.first.names #=> Array
collection.entries.first.names.first #=> Microformats::Property::Text instance
collection.entries.first.names.first.to_s #=> "Jessica"
# singular
collection.entry.name #=> Microformats::Property::Text instance
collection.entry.name.to_s #=> "Jessica"

HEntry#names and HEntry#name are automagically defined when an .h-entry .p-name is found.

Accessing Nested Author HCard from Entry

g5_hentry_consumer

collection.entries.first.author.first #=> G5HentryConsumer::HCard instance
microformats2

# plural
collection.entries.first.authors #=> Array
collection.entries.first.authors.first #=> Microformats::Property::Text instance
collection.entries.first.authors.first.formats #=> Array
collection.entries.first.authors.first.formats.first #=> Microformats2::HCard instace
# singular
collection.entry.author #=> Microformats::Property::Text instance
collection.entry.author.format #=> Microformats2::HCard instace

HEntry#authors and HEntry#author are automagically defined when an .h-entry .p-author is found.
Property::Text#formats and Property::Text#format are manually defined and assigned when a .p-x.h-x is found (e.g., <span class="p-author h-card">…</span>).

Real World Example

Paraphrased from g5-configurator
g5_hentry_consumer

class Entry < ActiveRecord::Base
  FEED_URL = "http://g5-hub.herokuapp.com/"
  
  class << self
    def feed(file_or_url=FEED_URL)
      G5HentryConsumer.parse(file_or_url)
    end

    def consume_feed(file_or_url=FEED_URL)
      feed(file_or_url).entries.each do |hentry|
        find_or_create_from_hentry(hentry)
      end
    end
    
    def find_or_create_from_hentry(hentry)
      find_or_create_by_uid(hentry.bookmark) do |entry|
        entry.client_uid = hentry.content.first.uid # with nil handling
        entry.client_name = hentry.content.first.name.first # with nil handling
      end
    end
  end # class << self
end
microformats2

class Entry < ActiveRecord::Base
  FEED_URL = "http://g5-hub.herokuapp.com/"
  
  class << self
    def feed(html_or_file_or_url=FEED_URL)
      Microformats2.parse(file_or_url)
    end

    def consume_feed(html_or_file_or_url=FEED_URL)
      feed(file_or_url).entry.each do |hentry|
        find_or_create_from_hentry(hentry)
      end
    end
    
    def find_or_create_from_hentry(hentry)
      find_or_create_by_uid(hentry.uid) do |entry|
        # have to parse .e-content for microformats
        collection = Microformats2.parse(hentry.content)
        # collection.g5_client if we use vendor extension
        # collection.card if we use HCard
        entry.client_uid = collection.g5_client.uid.to_s # with nil handling
        entry.client_name = collection.g5_client.name.to_s # with nil handling
      end
    end
  end # class << self
end