populr 0.1.5 → 0.1.6

data/README.rdoc

@@ -1,6 +1,120 @@
 = Populr.me Ruby Gem
 
-A rubygem for interacting with the Populr.me API from Ruby apps.
+A rubygem for interacting with the Populr.me API from Ruby apps. If you're just getting started, be sure to check out the sample app at http://github.com/populr/populr_api_ruby_sample
+
+=== Getting an API Key
+
+Read the 'Getting Started' section of the API documentation, which explains how to get an API key and create API templates on the Populr.me website:
+http://developers.populr.me/api
+
+
+=== Retrieving and Listing Pops and Templates
+
+    # Create an API Connection
+    require 'populr'
+    @populr = Populr.new(<Your API Key>)
+
+    # List the templates in your populr account
+    @populr.templates.each do |template|
+      puts template.id
+    end
+
+    # Fetch a specific template
+    @template = @populr.templates.first
+    @template = @populr.templates.find(params[:template_id])
+
+    # List the pops that have already been created with a template
+    @template.pops.each do |pop|
+      puts pop.id
+    end
+
+    # List pops 100-150
+    @template.pops.range(100,50).each do |pop|
+      puts pop.id
+    end
+
+
+=== Creating & Publishing a Pop
+
+    # You must always create a pop from an existing template created
+    # on Populr.me
+    template = @populr.templates.find(<Template ID>)
+    pop = Pop.new(template)
+
+    # Assign it's title, slug, and other properties
+    p.slug = params[:pop_data]['slug']
+
+    # Fill in {{tags}} in the body of the pop using the
+    # values the user has provided in the pop_data parameter
+    for tag,value in params[:pop_data]['tags']
+      p.populate_tag(tag, value)
+    end
+
+    # Optionally set a password that will be required to view
+    p.password = 'pass'
+
+    # Save the pop. This commits our changes above.
+    p.save!
+
+    # Publish the pop. This makes it available at http://p.domain/p.slug.
+    # The pop model is updated with a valid published_pop_url after this line!
+    p.publish!
+
+
+=== Creating Assets
+
+    # Create a new image asset and fill the region named
+    # 'profile-image-region' with it.
+    file = File.open('my-image.jpg', 'r')
+    asset = @populr.images.build(file, 'Image Name').save!
+    p.populate_region('profile-image-region', asset)
+
+    # Fill in an embed regions by creating a new embed asset with HTML
+    html = "My HTML"
+    asset = @populr.embeds.build(html).save!
+    p.populate_region('youtube-region', asset)
+
+
+=== Creating Tracers
+
+    # Create a new tracer for our pop. This will allow us to collect
+    # analytics when users visit the page with the tracer code added.
+    tracer = pop.tracers.build
+    tracer.name = 'bengotow@gmail.com'
+    tracer.enable_webhook('http://mysite.com/tracer_viewed/%{pop-id}')
+    tracer.save!
+
+    # The URL (with the ?tc tracer extension) to give to the user.
+    traced_url = #{pop.published_pop_url}?#{tracer.code}
+
+
+=== Retrieving Tracer Analytics
+
+    pop = @populr.pops.find('<Pop ID>')
+    tracer = pop.tracers.find('<Tracer ID>')
+ 
+    # Fetch the number of views
+    puts tracer.views
+
+    # Fetch the number of clicks for a particular asset we placed in a region
+    puts tracer.clicks_for_asset('<Asset ID>')
+
+    # Fetch the number of clicks within an entire region (for example, clicks on 
+    # a set of documents that were all placed in the same region.)
+    puts tracer.clicks_for_region('profile-image-region')
+
+
+== Best Practices & Tips
+
+* Create template pops using the Populr.me website that have everything _except_ what you need to insert via the API.
+* Show a list of available templates to users, or store template IDs on your server or hardcode them into your app. 
+  You cannot perform 'where' queries using the Populr API, so you can't retrieve pops or template by name or labels.
+* Avoid creating the same asset each time you create a pop. If you plan to put the same image, document or embed in 
+  multiple pops, create the assets ahead of time and insert them into each pop.
+* Consider using the tracer name property to store extra information, such as a user ID or email address.
+* Do not create hundreds of pops in a hard loop. If you make an exessive number of requests in a small period of time, 
+  your API access may be suspended. Use Resque or a rake task to push pop creation to the background.
+
 
 == Contributing to the Populr.me Ruby Gem
  

data/VERSION

@@ -1 +1 @@
-0.1.5
+0.1.6

data/lib/pop.rb

@@ -15,6 +15,14 @@ class Pop < RestfulModel
   attr_accessor :published_pop_url
   attr_accessor :unpopulated_api_regions
   attr_accessor :unpopulated_api_tags
+  attr_accessor :custom_links
+  attr_accessor :custom_code
+  attr_accessor :clone_link_enabled
+  attr_accessor :clone_link_url
+  attr_accessor :collaboration_link_enabled
+  attr_accessor :collaboration_interstitial_text
+  attr_accessor :collaboration_link_url
+  attr_accessor :collaboration_webhook
   attr_accessor :domain
   attr_accessor :password
 
@@ -27,8 +35,10 @@ class Pop < RestfulModel
       self.template_id = parent._id
       self.title = parent.title
       self.name = parent.name
-      self.unpopulated_api_regions = parent.api_regions
-      self.unpopulated_api_tags = parent.api_tags
+      self.unpopulated_api_regions = parent.api_regions.dup
+      self.unpopulated_api_tags = parent.api_tags.dup
+      self.custom_code = parent.custom_code
+      self.custom_links = parent.custom_links.dup
 
     elsif parent.is_a?(RestfulModelCollection)
       @_api = parent.instance_variable_get :@_api
@@ -78,6 +88,28 @@ class Pop < RestfulModel
     update('POST', 'unpublish')
   end
 
+  def enable_collaboration!(interstitial_text = '', webhook = nil)
+    self.collaboration_link_enabled = true
+    self.collaboration_webhook = webhook
+    self.collaboration_interstitial_text = interstitial_text
+    self.save! # go and populate our model with the collaboration link
+  end
+
+  def disable_collaboration
+    self.collaboration_link_enabled = false
+    self.collaboration_link_url = nil
+  end
+
+  def enable_cloning!
+    self.clone_link_enabled = true
+    self.save! # go and populate our model with the clone link
+  end
+
+  def disable_cloning
+    self.clone_link_enabled = false
+    self.clone_link_url = nil # doesn't get saed, just for developer interface
+  end
+
   def has_unpopulated_region(region_identifier)
     self.unpopulated_api_regions.include?(region_identifier)
   end

data/lib/restful_model.rb

@@ -43,10 +43,14 @@ class RestfulModel
     setters = methods.grep(/^\w+=$/)
     setters.each do |setter|
       getter = setter.to_s[0..setter.to_s.index('=')-1]
-      hash[getter] = self.send(getter)
-
-      if hash[getter].class.method_defined? :as_json
-        hash[getter] = hash[getter].as_json(options)
+      unless options[:except] && options[:except].include?(getter)
+        value = self.send(getter)
+        unless value.is_a? RestfulModelCollection
+          hash[getter] = value
+          if value.class.method_defined? :as_json
+            value = value.as_json(options)
+          end
+        end
       end
     end
     hash

data/lib/template.rb

@@ -7,6 +7,8 @@ class Template < RestfulModel
   attr_accessor :label_names
   attr_accessor :api_tags
   attr_accessor :api_regions
+  attr_accessor :custom_code
+  attr_accessor :custom_links
 
   def pops
     @pops ||= RestfulModelCollection.new(Pop, @_api, self)

data/populr.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "populr"
-  s.version = "0.1.5"
+  s.version = "0.1.6"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Ben Gotow"]
-  s.date = "2013-04-24"
+  s.date = "2013-05-22"
   s.description = "Gem for interacting with the Populr.me API that allows you to create and publish one-page websites, subscribe to web hooks and receive events when those pages are interacted with. Visit http://www.populr.me/ for more information. "
   s.email = "ben@populr.me"
   s.extra_rdoc_files = [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: populr
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-24 00:00:00.000000000 Z
+date: 2013-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
-  requirement: &70343202086340 !ruby/object:Gem::Requirement
+  requirement: &70304957231240 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '1.6'
   type: :runtime
   prerelease: false
-  version_requirements: *70343202086340
+  version_requirements: *70304957231240
 - !ruby/object:Gem::Dependency
   name: shoulda
-  requirement: &70343202085160 !ruby/object:Gem::Requirement
+  requirement: &70304957230380 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70343202085160
+  version_requirements: *70304957230380
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &70343202084200 !ruby/object:Gem::Requirement
+  requirement: &70304957229640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: '3.12'
   type: :development
   prerelease: false
-  version_requirements: *70343202084200
+  version_requirements: *70304957229640
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70343202082840 !ruby/object:Gem::Requirement
+  requirement: &70304957227780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: 1.3.5
   type: :development
   prerelease: false
-  version_requirements: *70343202082840
+  version_requirements: *70304957227780
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &70343202081860 !ruby/object:Gem::Requirement
+  requirement: &70304957226680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -65,7 +65,7 @@ dependencies:
         version: 1.8.4
   type: :development
   prerelease: false
-  version_requirements: *70343202081860
+  version_requirements: *70304957226680
 description: ! 'Gem for interacting with the Populr.me API that allows you to create
   and publish one-page websites, subscribe to web hooks and receive events when those
   pages are interacted with. Visit http://www.populr.me/ for more information. '
@@ -116,7 +116,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4567027092822148073
+      hash: -668596441403544786
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: