tagcrumbs-tagcrumbs 0.3.1

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

@@ -0,0 +1,19 @@
+module Tagcrumbs
+  # Activites are automatically created when other actions are performed on the website or with the webservice.
+  # They cannot be created or modified manually. However, it is possible to destroy an activity if you don't
+  # want it to be in your activity stream.
+  # The user of the activity is the actor who performed the activity, the subject is the social thing the action was performed upon.
+  # Sometimes there also is a secondary subject. The creation of a comment sets the subject to the comment and the secondary subject
+  # will be the placemark on which the comment was created.
+  # The event_type attribute shows what action happened and if a resource was modified or created.
+  class Activity < Model
+    can_be :destroyed
+    
+    readable_attributes :event_type, :created_at, :updated_at
+    
+    has_one :user
+    has_one :subject
+    has_one :secondary_subject
+    
+  end
+end

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

@@ -0,0 +1,16 @@
+module Tagcrumbs
+  # Addresses are associated to Placemarks. They cannot be created or destroyed manually.
+  # They can only be updated. An address will be destroyed if the associated Placemark is
+  # destroyed.
+  #
+  # The city field contains a string that describes the city as it would stand in an address.
+  # It must not - but can - be the same as the associated city of the Placemark.
+  class Address < Model
+    can_be :updated
+    
+    writeable_attributes :street_address, :postal_code, :city, :state, :country
+    
+    has_one :tagcrumb
+    
+  end
+end

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

@@ -0,0 +1,13 @@
+module Tagcrumbs
+  # A City somewhere on this planet. It has a name and a geoname and you can get more information about it with the geonames web service.
+  # It belongs to a state and a state belongs to a country, so that you can find out the associated admin areas.
+  class City < Place    
+    has_one :state
+    
+    # Search for a city by handing a string.
+    def self.search(q, args={})
+      super(q, args.merge(:for => :city))
+    end
+    
+  end
+end

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

@@ -0,0 +1,12 @@
+module Tagcrumbs
+  # Comments can be created on Placemarks. They can be destroyed for a certain timespan, afterwards it is no longer
+  # possible to destroy them.
+  class Comment < Model
+    can_be :created, :destroyed
+    
+    readable_attributes :created_at, :updated_at
+    writeable_attributes :text
+    
+    has_one :tagcrumb, :modifiable => true
+  end
+end

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

@@ -0,0 +1,15 @@
+module Tagcrumbs
+  # A Country is a Place and has a name. It contains many states and the states contain many cities.
+  # You can filter Tagcrumbs by country. You can find out more information about the country by querying the geonames webservice.
+  
+  class Country < Place
+  
+    has_many :states
+    
+    # Search a country by a string
+    def self.search(q, args={})
+      super(q, args.merge(:for => :country))
+    end
+    
+  end
+end

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

@@ -0,0 +1,12 @@
+module Tagcrumbs
+  # A Fanship is the association between a User and a Fan.
+  # It cannot be created or destroyed, it only shows who is "following" you.
+  class Fanship < Model
+    
+    readable_attributes :created_at, :updated_at
+    
+    has_one :user
+    has_one :fan
+    
+  end
+end

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

@@ -0,0 +1,22 @@
+module Tagcrumbs
+  # Instead of creating a brand new Placemark you can create a Favorite instead of a Placemark that is somewhere nearby
+  # and describes the place already that you wanted to describe.
+  
+  # If you set subscribe to true you will automatically subscribe to updates of this Placemark.
+  class Favorite < Tagcrumb
+    can_be :created, :updated, :destroyed
+        
+    writeable_attributes  :tag_list, :private, :subscribe
+    readable_attributes   :created_at, :updated_at
+    
+    has_one :user
+     
+    has_one :tagcrumb, :modifiable => true
+    
+    # Find favorites and pass in additional filter options. The options are documented in Tagcrumb.
+    def self.find(args={})
+      super(args.merge(:tagcrumb_type => :favorite))
+    end
+    
+  end
+end

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

@@ -0,0 +1,32 @@
+module Tagcrumbs
+  # A Filter is a saved set of "find" criterias that can be easily accessed by a user multiple times later on.
+  # == Filter criteria:
+  # private: 
+  #   - true: only show private Placemarks
+  #   - false: only show public Placemarks
+  #   - nil: show private and public Placemarks
+  # tagcrumb_type:
+  #   - Placemark: only show Placemarks
+  #   - Favorite: only show Favorites
+  #   - nil: show Placemarks and Favorites
+  # tag_list: only show Tagcrumbs that are tagged with all of the tags in the comma-separated list 
+  # since: all Tagcrumbs since this point of time
+  # until: all Tagcrumbs until this point of time (can be combined with since)
+  # from: you, everybody, fans, friends, recommendations
+  
+  class Filter < Model
+    can_be :created, :updated, :destroyed
+    
+    readable_attributes  :created_at, :updated_at, :permalink
+    writeable_attributes :name, :private, :tagcrumb_type, :tag_list, :middle_of_nowhere, :from, :within, :since, :until
+    
+    has_one :user
+    
+    has_one :monitored_user, :modifiable => true
+    has_one :city, :modifiable => true
+    has_one :state, :modifiable => true
+    has_one :country, :modifiable => true
+    
+    has_many :tagcrumbs
+  end
+end

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

@@ -0,0 +1,10 @@
+module Tagcrumbs
+  # A Flag is used to mark a Placemark to be against the Terms of Service. It can only be created and not read, destroyed or
+  # updated afterwards. 
+  class Flag < Model
+    can_be :created
+    
+    writeable_attributes :reason
+    
+  end
+end

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

@@ -0,0 +1,12 @@
+module Tagcrumbs
+  # A Friendship can be created or destroyed and lets you "follow" other Users
+  class Friendship < Model
+    can_be :created, :destroyed
+    
+    readable_attributes :created_at, :updated_at
+    
+    has_one :user
+    has_one :friend, :modifiable => true
+
+  end
+end

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

@@ -0,0 +1,8 @@
+module Tagcrumbs
+  # Cities, States and Countries are connected to a Geoname. You can get more information about a place by querying the 
+  # geonames webservice with the geonameid of the place.
+  class Geoname < Model
+    readable_attributes :geonameid, :latitude, :longitude
+    
+  end
+end

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