tagcrumbs 0.3.1

data/lib/tagcrumbs/resources/models/link.rb

@@ -0,0 +1,13 @@
+module Tagcrumbs
+  # A Placemark can contain many Links.
+  class Link < Model
+    can_be :created, :updated, :destroyed
+
+    writeable_attributes :url, :link_type    
+    readable_attributes :title, :created_at, :updated_at
+    
+    has_one :tagcrumb, :modifiable => true
+    
+
+  end
+end

data/lib/tagcrumbs/resources/models/location.rb

@@ -0,0 +1,13 @@
+module Tagcrumbs
+  # The current Location of the user. It can only be updated. This location is the default value for all queries that
+  # take your current location into account.
+  class Location < Model
+    can_be :updated
+    
+    writeable_attributes :latitude, :longitude
+    
+    has_one :user
+    has_one :city
+    
+  end
+end

data/lib/tagcrumbs/resources/models/model.rb

@@ -0,0 +1,148 @@
+module Tagcrumbs
+  # The base class for all Models that can be read, created, destroyed or updated.
+  
+  class Model < Resource
+    include Tagcrumbs::Accessors
+    include Validations
+    
+    attr_accessor :new_record
+    
+
+    def initialize(attributes ={})
+      reset!
+      
+      self.attributes = attributes      
+    end
+    
+    # Reset the object to a blank state
+    def reset!
+      super
+      self.new_record = true
+      @nodes = @nodes_updates = {}
+      @errors = Errors.new(self) # reset errors from server
+      restore!
+      
+      true
+    end
+    
+    # Is this a new record or was it loaded from the web service
+    def new_record?
+      self.new_record ? true : false
+    end
+    
+    # Save the object
+    def save
+      new_record? ? create : update
+    end
+    
+    # Create a new object by posting a representation of the resource to the create_url
+    def create
+      raise CreateImpossible unless can_be?(:created)
+      raise CreateURLMissing unless create_url.present?
+      return false unless new_record?
+      requestor.post(create_url, to_format)
+      handle_save_response
+    end
+    
+    # Update an existing object by puting a representation of the resource to the resource_url
+    def update
+      raise UpdateImpossible unless can_be?(:updated)
+      raise ResourceURLMissing unless resource_url.present?
+      return false if new_record?
+      requestor.put(resource_url, to_format)
+      handle_save_response
+    end
+    
+    # Remove an existing object from the server by sending a delete request to the server
+    def destroy
+      raise DestroyImpossible unless can_be?(:destroyed)
+      return false if new_record?
+      
+      requestor.delete(resource_url)
+      
+      true
+    end
+    
+    # Output the resource in the current active format
+    def to_format(format = Tagcrumbs.options[:format], options={})
+      case format
+        when :xml: to_xml(options)
+        when :json: to_json(options)
+      end
+    end
+    
+    # Return the object in a XML representation
+    def to_xml(options = {})
+      options.reverse_merge!(:modifiable_only => true)
+      Tagcrumbs::XmlBuilder.new(self).build(options)
+    end
+    
+    # Return the object in a JSON representation
+    def to_json(options = {})
+      options.reverse_merge!(:modifiable_only => true, :badgerfish => false)
+      Tagcrumbs::JsonBuilder.new(self).build(options)
+    end
+    
+
+    
+    # Load the attributes and has_one and has_many associations.
+    # The Resource attributes are loaded in the superclass.
+    def initialize_from_document(parser, format = Tagcrumbs.options[:format])
+      parser = super
+      
+      self.new_record = false
+      
+      if self.loaded? # only if there actually is content    
+        self.class.attributes.each do |name| # load all attributes
+          node = parser.get_node(name)
+
+          if node
+            node_parser = Parser.new_for_format(parser.get_node(name), parser.format)
+            self.nodes[name] = Node.new(name, node_parser.get_value, node_parser.get_attributes)
+          end
+        end
+        
+        self.class.has_one_associations_options.keys.each do |name| # load all has_one associations
+          has_one_element = parser.get_node(self.class.has_one_associations_options[name][:node_name])
+
+          if has_one_element
+            has_one_parser = Parser.new_for_format(has_one_element, parser.format)
+            
+            self.has_one_associations[name] = Tagcrumbs.class_by_type(has_one_parser.get_attribute('type')).new_from_document(has_one_element, parser.format)
+          end
+        end
+      
+        self.class.has_many_associations_options.keys.each do |name| # load all has_many associations
+          has_many_element = parser.get_node(self.class.has_many_associations_options[name][:node_name])  
+        
+          if has_many_element
+            self.has_many_associations[name] = Tagcrumbs::Array.new_from_document(has_many_element, parser.format)
+          end
+        end    
+      end
+      
+      parser
+    end
+    
+    # Just like new, but directly save the object to the webservice
+    def self.create(args={})
+      # TODO_SK: test this
+      model = new(args)
+      model.create
+      model
+    end
+    
+    private
+      # Handle the response after a create or update and set the errors if needed.
+      def handle_save_response
+        if requestor.response.code == '422'
+          errors.from_format(requestor.response.body, requestor.response_format)
+          false
+        else
+          initialize_from_document(requestor.response.body)
+          true
+        end
+      end
+
+  end
+end

data/lib/tagcrumbs/resources/models/picture.rb

@@ -0,0 +1,28 @@
+module Tagcrumbs
+  # Each User has a Picture associated with him/her.
+  # There is a default Picture for every user that can only be updated and not destroyed.
+  # However, an uploaded Picture of a User can be destroyed which will set the Picture
+  # to the default Picture again.
+  class Picture < Model
+    can_be :updated, :destroyed
+    
+    writeable_attributes :picture_file
+    readable_attributes :url, :small_thumbnail_url, :medium_thumbnail_url, :content_type, :created_at, :updated_at
+    
+    has_one :profile
+    
+    # Load a file from the local filesystem and set the attributes.
+    # Save the object to upload a new profile picture to the server.
+    def get_file(filename)
+      return if filename.blank?
+      
+      self.picture_file = {
+        :filename => File.basename(filename),
+        :mime_type => MIME::Types.type_for(filename).first.content_type,
+        :content => Base64.encode64(File.read(filename))
+      }
+    end
+    
+
+  end
+end

data/lib/tagcrumbs/resources/models/place.rb

@@ -0,0 +1,17 @@
+module Tagcrumbs
+  # The superclass for City, State and Country
+  # All of them contain a name and a permalink.
+  # The name is automatically translated into the locale that was set by the user 
+  # in the settings.
+  class Place < Model
+    readable_attributes :name, :permalink
+    
+    has_one :geoname
+    
+    def self.search(q, args={})
+      args.assert_valid_keys(:page, :per_page, :for)
+      
+      Array.load(Tagcrumbs.root.place_search_url, args.merge(:q => q))
+    end
+  end
+end

data/lib/tagcrumbs/resources/models/placemark.rb

@@ -0,0 +1,30 @@
+module Tagcrumbs
+  # The main object in the webservice. A Placemark describes a place on earth.
+  # It has many link, comments and can be recommended to your friends.
+  class Placemark < Tagcrumb
+    can_be :created, :updated, :destroyed
+    
+        
+    writeable_attributes   :name, :notes, :private, :latitude, :longitude, :tag_list, :guess_city, :address_attributes
+    readable_attributes   :created_at, :updated_at, :short_url, :permalink, :favorites_count
+    
+    has_one :user
+    has_one :city, :modifiable => true
+    has_one :address
+    
+    has_many :links
+    has_many :comments
+    has_many :recommendations
+    
+    # Find Placemarks by specifying find criteria.
+    def self.find(args={})
+      super(args.merge(:tagcrumb_type => :placemark))
+    end
+    
+    # Load suggested names, cities and tags that can be shown to the user on the creation of a new Placemark
+    def suggestions
+      Suggestions.load(Tagcrumbs.current_user.suggestions_url, {:latitude => self.latitude, :longitude => self.longitude}) if self.latitude.present? && self.longitude.present?
+    end
+    
+  end
+end

data/lib/tagcrumbs/resources/models/profile.rb

@@ -0,0 +1,16 @@
+module Tagcrumbs
+  # Each User has Profile. A Profile can only be updated, it is created automatically with a User and destroyed if the User
+  # decides to leave Tagcrumbs.
+  class Profile < Model
+    can_be :updated
+    
+    writeable_attributes :fullname, :about, :description
+    readable_attributes   :created_at, :updated_at
+    
+    has_one :user
+    has_one :city, :modifiable => true
+    has_one :picture
+    
+    has_many :profile_links
+  end
+end

data/lib/tagcrumbs/resources/models/profile_link.rb

@@ -0,0 +1,12 @@
+module Tagcrumbs
+  # Each User can set multiple ProfileLinks
+  # e.g. his Facebook account, blog, website etc.
+  class ProfileLink < Model
+    can_be :created, :updated, :destroyed
+    
+    writeable_attributes :url, :link_type
+    readable_attributes :created_at, :updated_at
+
+    has_one :profile
+  end
+end

data/lib/tagcrumbs/resources/models/root.rb

@@ -0,0 +1,19 @@
+module Tagcrumbs
+  # The Root Object that contains links to all other resources on tagcrumbs.com.
+  # It is used as the starting point for many other queries.
+  class Root < Model
+    has_one :you
+    has_one :location
+    
+    has_many :tagcrumbs
+    has_many :nearby_tagcrumbs
+    has_many :countries
+    
+    has_many :popular_countries
+    has_many :tags
+    has_many :users
+    
+    has_many :search
+    has_many :place_search
+  end
+end

data/lib/tagcrumbs/resources/models/settings.rb

@@ -0,0 +1,14 @@
+module Tagcrumbs
+  # Each user has a Settings object that can be updated
+  class Settings < Model
+    can_be :updated
+    
+    readable_attributes :created_at, :updated_at 
+    writeable_attributes :locale, :unit_system, :notification_fan, :notification_recommendation, :newsletter, :facebook_new_placemark_feed, 
+                         :facebook_new_favorite_feed, :facebook_new_comment_feed
+    
+    
+    has_one :user
+
+  end
+end

data/lib/tagcrumbs/resources/models/state.rb

@@ -0,0 +1,14 @@
+module Tagcrumbs
+  # A State is a Place and connects Countries and Cities.
+  class State < Place
+    
+    has_one :country
+    has_many :cities
+    
+    # Search a State by name
+    def self.search(q, args={})
+      super(q, args.merge(:for => :state))
+    end
+    
+  end
+end

data/lib/tagcrumbs/resources/models/subscription.rb

@@ -0,0 +1,13 @@
+module Tagcrumbs
+  # A Subscription is used to get updates of Placemarks
+  class Subscription < Model
+    can_be :created, :updated, :destroyed
+    
+    readable_attributes :created_at, :updated_at
+    
+    has_one :user
+    has_one :tagcrumb, :modifiable => true
+    
+    
+  end
+end

data/lib/tagcrumbs/resources/models/suggestions.rb

@@ -0,0 +1,11 @@
+module Tagcrumbs
+  # Suggestions is a Model that is used to load the name, tag and city suggestions from the web service.
+  class Suggestions < Model
+    has_many :recommended_tags
+    has_many :popular_tags
+    
+    has_many :names
+    
+    has_many :cities
+  end
+end

data/lib/tagcrumbs/resources/models/tag.rb

@@ -0,0 +1,6 @@
+module Tagcrumbs
+  # A single Tag.
+  class Tag < Model
+    readable_attributes :name
+  end
+end

data/lib/tagcrumbs/resources/models/tagcrumb.rb

@@ -0,0 +1,58 @@
+module Tagcrumbs
+  # Tagcrumb is the superclass for Placemark and Favorite, they are both a "Tagcrumb" as well
+  class Tagcrumb < Model
+    # Find Tagcrumbs by specifying filter criteria.
+    def self.find(args={})
+      args.assert_valid_keys(
+                             :from, # from: you, friends, fans, recommendations, everybody, user
+                             :username, # name of the user
+                             :tags, # comma separates tag list
+                             :tagcrumb_type, # Placemarks, Favorite or both?
+                             :city, :state, :country, :middle_of_nowhere, # filter by the place hierarchy
+                             :within, # within a certain radius
+                             :latitude, :longitude, # per default within is the current location, can be overwritten with latitude and longitude
+                             :bbox, # everything between a bounding box
+                             :since, :until, # filter by time
+                             :per_page, :page, :sort, :order # filter options
+                            )
+
+      Array.load(Tagcrumbs.root.tagcrumbs_url, typecast_and_validate_query_parameters(args))
+    end
+    
+    # Use a fulltext search to find Tagcrumbs.
+    # This is different from "finding" by filter criteria
+    def self.search(args={})
+      args.assert_valid_keys(:q, :from, :l, :w, :page, :per_page)
+      
+      Array.load(Tagcrumbs.root.search_url, typecast_and_validate_query_parameters(args))
+    end
+    
+    
+    def self.typecast_and_validate_query_parameters(args)
+      query_args = {}
+      
+      args.each do |key, value|
+        query_args[key] = case key
+          when :from, :w: value.to_sym
+          when :tagcrumb_type: value.to_s.capitalize
+          when :since, :until: value.iso8601
+          else
+            value
+        end
+
+        Tagcrumbs.validate(key, query_args[key])
+      end
+      
+      query_args
+    end
+    
+
+  end
+end
+
+
+
+
+
+
+

data/lib/tagcrumbs/resources/models/user.rb

@@ -0,0 +1,101 @@
+module Tagcrumbs
+  # The main actor in the webservice.
+  class User < Model
+    readable_attributes :username, :created_at, :updated_at
+    
+    has_one :profile
+    has_one :picture
+    has_one :settings
+    has_one :location
+    has_one :suggestions
+    
+    has_many :tagcrumbs
+    has_many :placemarks
+    has_many :favorites
+     
+    has_many :profile_links
+    
+    has_many :fanships
+    has_many :friendships
+
+    has_many :recommendations
+    has_many :received_recommendations
+    
+    has_many :filters
+    
+    has_many :comments
+    has_many :links
+    has_many :subscriptions
+    
+    has_many :tags
+    has_many :places
+    
+    has_many :activities
+    
+    has_many :tagcrumbs_friends
+    has_many :tagcrumbs_fans
+    
+    # An array of all friends of a User (people the user is following)
+    def friends
+      array = []
+      
+      friendships.each_page do |page|
+        array += page.map{|f| f.friend}
+      end
+      
+      array
+    end
+    
+    # An array of all fans of a User (people that follow this user)
+    def fans
+      array = []
+      
+      fanships.each_page do |page|
+        array += page.map{|f| f.fan}
+      end
+      
+      array      
+    end
+    
+    # The friendship with a specific user
+    def friendship_with(user)
+      f = Friendship.new
+      f.reload("/#{self.username}/friends/#{user}")      
+    rescue Net::HTTPServerException => error
+      f.requestor.response.code == '404' ? nil : (raise error) # not found
+    end
+    
+    # Is this user friend with user?
+    def friend_with?(user)
+      friendship_with(user) ? true : false
+    end
+    
+    # The fanship with a specific user
+    def fanship_with(user)
+      Fanship.load("/#{self.username}/fans/#{user}")
+    rescue Net::HTTPServerException => error
+      self.requestor.response.code == '404' ? nil : (raise error) # not found  
+    end
+    
+    # Is this user a fan of user?
+    def fan_of?(user)
+      fanship_with(user) ? true : false
+    end
+    
+    
+    # Search a User by name or email
+    def self.search(q, args={})
+      Array.load(Tagcrumbs.root.users_url, args.merge(:u => q))
+    end
+    
+    # Load a User by its username
+    def self.find_by_username(username)
+      User.load("/#{username}")
+    end
+    
+    def to_s
+      self.username
+    end
+    
+  end
+end

data/lib/tagcrumbs/resources/models/user_recommendation.rb

@@ -0,0 +1,18 @@
+module Tagcrumbs
+  # A Recommendation of a Placemark between two Users
+  class UserRecommendation < Model
+    can_be :created
+    
+    readable_attributes :created_at, :updated_at
+    writeable_attributes :message
+    
+    has_one :user
+    has_one :tagcrumb, :modifiable => true
+    has_one :recommended_user, :modifiable => true
+    
+    
+    def create_url
+      Tagcrumbs.current_user.recommendations_url # has to be overwritten
+    end
+  end
+end

data/lib/tagcrumbs/resources/resource.rb

@@ -0,0 +1,76 @@
+module Tagcrumbs
+  # Superclass for all other Resources
+  class Resource
+    attr_accessor :resource_url, :loaded
+    attr_writer :requestor
+    attr_reader :properties
+    
+    def initialize
+      reset!
+    end
+    
+    # Clean up the state of the model and make it blank again
+    def reset!      
+      self.resource_url = nil
+      self.loaded = false
+      self.properties = {}
+      
+      true
+    end
+    
+    # Is the Resource loaded or is it just a stub and the attributes still need to be loaded from the web?
+    def loaded?
+      self.loaded ? true : false
+    end
+    
+    # A requestor that is auto-generated if needed to make requests to the webservice
+    def requestor
+      @requestor ||= Requestor.new
+    end
+       
+    # Reset the Resource, reload the data from the web and initialize it again from the document
+    def reload(url = nil)
+      self.requestor.get(url || resource_url)
+      initialize_from_document(requestor.response.body, requestor.response_format)
+      true
+    end
+    
+    # Set the properties and automatically set the resource_url
+    def properties=(properties)
+      self.resource_url = properties['xlink:href'] if properties['xlink:href']       
+      @properties = properties.with_indifferent_access
+    end
+    
+    # Load a Resource from a URL with optional query parameters
+    # The correct Resource class is automatically determined.
+    def self.load(path, query_string = {}, requestor_options={})
+      requestor = Requestor.new(requestor_options)
+      requestor.get(path, query_string)
+      
+      resource = new_from_document(requestor.response.body, requestor.response_format)
+    end
+    
+    # Create a new Resource from a document.
+    # The correct Resource class is automatically determined.
+    def self.new_from_document(document, format = Tagcrumbs.options[:format])
+      parser = Parser.new_for_format(document, format) 
+
+      resource = Tagcrumbs.class_by_type(parser.get_attribute('type')).new
+      resource.initialize_from_document(parser, format)
+      
+      resource
+    end
+    
+    # Initialize the object with data from the document
+    def initialize_from_document(document, format = Tagcrumbs.options[:format])      
+      parser = Parser.new_for_format(document, format)
+      reset!
+      
+      self.loaded = parser.node_loaded?
+      self.properties = parser.get_attributes || {}
+      
+      parser
+    end
+    
+  end
+end