rooftop 0.0.1 → 0.0.3

data/README.md

@@ -1,68 +1,211 @@
 # Rooftop
-A mixin for Ruby classes to access the Wordpress REST API (http://wp-api.org)
+A mixin for ruby classes to access the rooftop cms rest api: http://www.rooftopcms.com
 
 # Setup
 
+## Installation
+
+You can either install using [bundler](http://bundler.io) or just from the command line.
+
+### Bundler
+Include this in your gemfile
+
+`gem 'rooftop'`
+
+That's it! this is in active development so you might prefer:
+
+`gem 'rooftop', github: "rooftop/rooftop-ruby"`
+ 
+### Using Gem
+As simple as:
+
+`gem install rooftop`
+
 ## Configuration
-You need to configure Rooftop with a block, like this
+You need to configure rooftop with a block, like this
 
 ```
     Rooftop.configure do |config|
-        config.url = "http://your.rooftop-cms.site/wp-json"
+        config.url = "http://yoursite.rooftopcms.io"
+        config.api_token = "your token"
+        config.api_path = "/wp-json/wp/v2/"
+        config.user_agent = "rooftop cms ruby client #{rooftop::version} (http://github.com/rooftopcms/rooftop-ruby)"
+        config.extra_headers = {custom_header: "foo", another_custom_header: "bar"}
+        config.advanced_options = {} #for future use
     end
 ```
 
+The minimum options you need to include are `url` and `api_token`.
+
 # Use
-Create a class and use one of the mixins to get the data.
+Create a class in your application, and mix in some (or all) of the rooftop modules to interact with your remote content.
 
 ## Rooftop::Post
-The Rooftop::Post mixin lets you specify a post type, so the API differentiates between types.
+The Rooftop::Post mixin lets you specify a post type, so the api differentiates between types. if you don't set a post type, it defaults to posts.
 
 ```
 class MyCustomPostType
     include Rooftop::Post
-    self.post_type = "my_custom_post_type" #this is the post type name in Wordpress
+    self.post_type = "my_custom_post_type" #this is the singular post type name in WordPress
 end
 ```
 ## Rooftop::Page
-The Rooftop::Page mixin identifies this class as a page.
+The rooftop::page mixin identifies this class as a page.
 ```
 class Page
     include Rooftop::Page
 end
 ```
 
+## Custom endpoints and WordPress namespaces
+If you write a wordpress api plugin, you can either expose your data in an existing `/wp/` namespace, or in a custom namespace.
+
+rooftop includes `wp-api-menus`, so this gem supports the ability to specify an arbitrary namespace, version and endpoint name if necessary.
+
+this example would return a collection of `mything` objects from the path `/wp-json/my-things/v3/things`:
+
+```
+class MyThing
+    include rooftop::base
+    self.api_namespace = "my-things"
+    self.api_version = 3
+    self.api_endpoint = "things"
+end
+```
+
+If you don't specify the `api_endpoint` attribute, it assumes the underscored, pluralized version of the class name (`my_things` in this case)
+
+
 ## Field coercions
-Sometimes you want to do something with a field after it's returned. For example, it would be useful to parse date strings to DateTime.
+Sometimes you want to do something with a field after it's returned. for example, it would be useful to parse date strings to datetime.
 
 To coerce one or more fields, call a class method in your class and pass a lambda which is called on the field.
 
 ```
-class MyCustomPostType
-    include Rooftop::Post
+class mycustomposttype
+    include rooftop::post
     self.post_type = "my_custom_post_type"
-    coerce_field date: ->(date) { DateTime.parse(date)}
+    coerce_field date: ->(date) { datetime.parse(date)}
+end
+    
+```
+
+### Object dates are coerced automatically
+The created date field is coerced to a datetime. it's also aliased to `created_at`
+
+The modification date is also coerced to a datetime. it's also aliased to `updated_at`
+
+## Field aliases
+Sometimes you might want to alias field names - for example, `date` is aliased to `created_at` to make it more rubyish. `modified` is also `updated_at`.
+ 
+Creating alises and coercing them is order-sensitive. if you need to both coerce a field *and* alias it, do the coercion first. otherwise you'll find the aliased field isn't coerced.
+
+(We don't just called `alias_method` on the original field because the object methods are dynamically generated from the returned data)
+
 ```
+class mycustomposttype
+    include rooftop::post
+    self.post_type = "my_custom_post_type"
+    coerce_field some_date: ->(date) { datetime.parse(date)}
+    alias_field some_date: :another_name_for_some_date
+end
+```
+
+## Resource links
+*Resource links are a work-in-progress*
+
+The Wordpress api uses the concept of hypermedia links (see http://v2.wp-api.org/extending/linking/ for more info). we parse the `_links` field in the response and build a Rooftop::ResourceLinks::Collection (which is a subclass of `array`). the individual links are instances of Rooftop::ResourceLinks::Link.
+
+The reason for these classes is because we can do useful stuff with them, for example call `.resolve()` on a link to get an instance of the class to which it refers.
+
+### Custom Link Relations
+according to the wordpress api docs (and iana link relation convention) you need a custom name for link relations which don't fall into a [small subset of names](http://www.iana.org/assignments/link-relations/link-relations.xhtml). for those aren't in this list, we're prefixing the relation names with http://docs.rooftopcms.com/link_relations, which will resolve to some documentation.
+
+### Nested Resource Links
+rooftop uses the custom link relations to return a list of ancestors and children (not all descendants) in `_links`. rooftop::post and rooftop::page include rooftop::nested, which has some utility methods to access them.
+ 
+```
+class Page
+    include rooftop::page
+end
+
+p = Page.first
+p.ancestors #returns a collection of rooftop::resourcelinks::link items where `link_type` is "http://docs.rooftopcms.com/link_relations/ancestors"
+p.children #returns a collection of rooftop::resourcelinks::link items where `link_type` is "http://docs.rooftopcms.com/link_relations/children"
+p.parent #returns the parent entity
+```
+## Handling Content Fields
+Rooftop can return a variable number of content fields depending on what you've configured in advanced custom fields.
+
+## SSL / TLS
+Hosted Rooftop from rooftopcms.io exclusively uses ssl/tls. you need to configure the rooftop library to use ssl.
+ 
+This library uses the excellent [her rest client](https://github.com/remiprev/her) which in turn uses [faraday](https://github.com/lostisland/faraday/) for http requests. the [faraday ssl docs](https://github.com/lostisland/faraday/wiki/setting-up-ssl-certificates) are pretty complete, and the ssl options are exposed straight through this library:
+
+```
+Rooftop.configure do |config|
+    # other config options
+    config.ssl_options = {
+        #your ssl options in here.
+    }
+    # other config options
+end
+```
+
+Leaving `config.ssl_options` unset allows you to work without https.
+
+## Caching
+While hosted rooftop is cached at source and delivered through a cdn, caching locally is a smart idea. the rooftop library uses the [faraday-http-cache](https://github.com/plataformatec/faraday-http-cache) to intelligently cache responses from the api. rooftop updates etags when entities are updated so caches shouldn't be stale.
+
+_(the cache headers plugin for rooftop is a work in progress)_
+ 
+ If you want to cache responses, set `perform_caching` to true in your configuration block. you will need to provide a cache store and logger in the `cache_store` and `cache_logger` config options. by default, the cache store is set to `activesupport::cache.lookup_store(:memory_store)` which is a sensible default, but isn't shared across threads. any activesupport-compatible cache store (memcache, file, redis etc.) will do.
+   
+ The `cache_logger` option determines where cache debug messages (hits, misses etc.) get stored. by default it's `nil`, which switches logging off.
+
+# Roadmap
+Lots! here's a flavour:
+
+## Reading data
+
+* preview mode. rooftop supports passing a preview header to see content in draft. we'll expose that in the rooftop gem as a constant.
+* taxonomies will be supported and side-loaded against content
+* menus are exposed by rooftop. we need to create a rooftop::menu mixin 
+* media: media is exposed by the api, and should be accessible and downloadable.
+
+## Writing
+If your api user in rooftop has permission to write data, the api will allow it, and so should this gem. at the moment all the code is theoretically in place but untested. it would be great to have [issues raised](https://github.com/rooftopcms/rooftop-ruby/issues) about writing back to the api.
+
+Some abstractions will definitely need putting back into a hash to save.
+
+# Contributing
+rooftop and its libraries are open-source and we'd love your input.
+
+1. fork the repo on github
+2.  make whatever changes / extensions you think would be useful
+3. if you've got lots of commits, rebase them into sensible squashed chunks
+4. raise a pr on the project
+
+if you have a real desire to get involved, we're looking for maintainers. [let us know!](mailto: hello@rooftopcms.com).
 
-There are some coercions done manually.
 
-### Author
-When an object is returned from the API, the Author information is automatically parsed into a Rooftop::Author object.
+# Licence
+`rooftop-ruby` is a library to allow you to connect to Rooftop CMS, the API-first WordPress CMS for developers and content creators.
 
-### Date
-Created date is coerced to a DateTime. It's also aliased to created_at
+Copyright 2015 Error Ltd.
 
-### Modified
-The modification date is coerced to a DateTime. It's also aliased to updated_at
+This program is free software: you can redistribute it and/or modify
+it under the terms of the gnu general public license as published by
+the free software foundation, either version 3 of the license, or
+(at your option) any later version.
 
-# To do
-Lots! Here's a flavour:
+This program is distributed in the hope that it will be useful,
+but without any warranty; without even the implied warranty of
+merchantability or fitness for a particular purpose.  see the
+gnu general public license for more details.
 
-* Taxonomies need to be supported (http://wp-api.org/#taxonomies_retrieve-all-taxonomies)
-* Authentication: there are a couple of ways of doing this, but the simplest would be a quick WP plugin to generate a per-user API key which we pass in the header.
-* Preview: once authentication is solved, we need to be able to show posts in draft
-* Media: media is exposed by the API. Don't know if this explicitly needs supporting by the API or just accessible
-* Allowing other classes to be exposed: mixing in Rooftop::Client *should* allow a custom class to hit the right endpoint, but it's work-in-progress
+You should have received a copy of the GNU general public license
+along with this program.  if not, see <http://www.gnu.org/licenses/>.
 
 
 

data/lib/rooftop/base.rb

@@ -0,0 +1,74 @@
+module Rooftop
+  module Base
+    def self.included(base)
+      base.extend ClassMethods
+      base.include Her::Model
+
+      # Paths to get to the API
+      base.api_namespace = Rooftop::DEFAULT_API_NAMESPACE
+      base.api_version = Rooftop::DEFAULT_API_VERSION
+      base.setup_path!
+
+      # Coercions allow you to pass a block to do something with a returned field
+      base.include Rooftop::Coercions
+      # Aliases allow you to specify a field (or fields) to alias
+      base.include Rooftop::FieldAliases
+      # Queries mixin includes a fixup for there `where()` method
+      base.include Rooftop::Queries
+      # Links mixin handles the _links key in a response
+      base.include Rooftop::ResourceLinks
+      # Use the API instance we have configured - in a proc because we can't control load order
+      base.send(:use_api,->{Rooftop.configuration.connection})
+
+      # Turn calls to `content` into a collection of Rooftop::ContentField objects
+      base.include Rooftop::Content
+
+      # Date and Modified fields are pretty universal in responses from WP, so we can automatically
+      # coerce these to DateTime.
+      base.send(:coerce_field,date: ->(date) {DateTime.parse(date)})
+      base.send(:coerce_field,modified: ->(modified) {DateTime.parse(modified)})
+
+      # Having coerced the fields, we can alias them (order is important - coerce first.)
+      base.send(:alias_field, date: :created_at)
+      base.send(:alias_field, modified: :updated_at)
+
+      # Set up the hooks identified in other mixins. This method is defined in Rooftop::HookCalls
+      base.send(:"setup_hooks!")
+
+    end
+
+    module ClassMethods
+      attr_reader :api_namespace, :api_version, :api_endpoint
+
+      def api_namespace=(ns)
+        @api_namespace = ns
+        setup_path!
+      end
+
+      def api_version=(v)
+        @api_version = v
+        setup_path!
+      end
+
+      def api_endpoint=(e)
+        @api_endpoint = e
+        setup_path!
+      end
+
+      def setup_path!
+        @api_endpoint ||= collection_path
+        self.collection_path "#{@api_namespace}/v#{@api_version}/#{@api_endpoint}"
+      end
+
+      # Allow calling 'first'
+      def first
+        all.first
+      end
+
+
+
+
+    end
+
+  end
+end

data/lib/rooftop/coercions/author_coercion.rb

@@ -0,0 +1,10 @@
+module Rooftop
+  module Coercions
+    module AuthorCoercion
+      def self.included(base)
+        base.send(:after_find, ->(r) { r.author.registered = DateTime.parse(r.author.registered)})
+        base.send(:coerce_field, {author: ->(author) { Rooftop::Author.new(author) }})
+      end
+    end
+  end
+end

data/lib/rooftop/coercions/parent_coercion.rb

@@ -0,0 +1,47 @@
+# Coerce any field called 'parent' which returns an ID into an actual object
+module Rooftop
+  module Coercions
+    module ParentCoercion
+      def self.included(base)
+        base.extend ClassMethods
+        # base.send(:after_find, ->(r) {
+        #   if r.has_parent?
+        #     r.instance_variable_set(:"parent_#{base.to_s.underscore}", resolve_parent_id())
+        #     r.class.send(:attr_reader, :"parent_#{base.to_s.underscore}")
+        #   end
+        # })
+        # base.send(:coerce_field, parent: ->(p) { base.send(:resolve_parent_id,p) })
+      end
+
+      module ClassMethods
+        def add_parent_reference
+          define_method :"parent_#{self.to_s.underscore}" do
+            puts "hello"
+          end
+        end
+      end
+
+      def has_parent?
+        respond_to?(:parent) && parent.is_a?(Fixnum) && parent != 0
+      end
+
+      def resolve_parent_id
+        if respond_to?(:parent)
+          if parent.is_a?(Fixnum)
+            if parent == 0
+              #no parent
+              return nil
+            else
+              return self.class.send(:find, id)
+            end
+          else
+            return parent
+          end
+
+        end
+
+      end
+    end
+  end
+
+end

data/lib/{rooftop_client → rooftop}/coercions.rb

@@ -1,9 +1,14 @@
 module Rooftop
   module Coercions
     def self.included(base)
+      # Include Rooftop::HookCalls to allow us to push things into a list of hooks in the right order
+      base.include Rooftop::HookCalls
       base.extend ClassMethods
-      # `after_find` is a method provided by Her; we iterate over our coercions and call each lambda
-      base.send(:after_find, ->(r){
+
+      # Add the call to the :after_find hook to the list of hook calls, to be processed later.
+      # This is where we iterate over our previously established list of coercions, and call each
+      # in turn
+      base.send(:add_to_hook, :after_find, ->(r){
         r.coercions.each do |field,coercion|
           if r.respond_to?(field)
             r.send("#{field}=",coercion.call(r.send(field)))
@@ -14,6 +19,8 @@ module Rooftop
 
     module ClassMethods
       # Call coerce_field() in a class to do something with the attribute. Useful for parsing dates etc.
+      # For example: coerce_field(date: ->(date_string) { DateTime.parse(date_string)}) to get a DateTime object from a string field. The date field will now be a DateTime.
+
       # @param coercion [Hash] the coercion to apply - key is the field, value is a lambda
       def coerce_field(*coercions)
         @coercions ||= {}
@@ -26,7 +33,7 @@ module Rooftop
 
     # Instance method to get the class's coercions
     def coercions
-      self.class.instance_variable_get(:"@coercions")
+      self.class.instance_variable_get(:"@coercions") || {}
     end
   end
 end

data/lib/rooftop/content_fields/collection.rb

@@ -0,0 +1,23 @@
+module Rooftop
+  module Content
+    class Collection < ::Array
+      def initialize(content_fields)
+          content_fields.each do |field|
+            self << Rooftop::Content::Field.new(field)
+          end
+      end
+
+      # Find content_fields by attribute. Assume there will only be one attribute in the search
+      def find_by(hash)
+        raise ArgumentError, "you can only find a field by one attribute at a time" unless hash.length == 1
+        attr = hash.first.first
+        val = hash.first.last
+        self.select {|l| l.send(attr) == val.to_s}
+      end
+
+      def named(name)
+        find_by(name: name.to_s).first
+      end
+    end
+  end
+end

data/lib/rooftop/content_fields/content_fields.rb

@@ -0,0 +1,39 @@
+module Rooftop
+  # The Rooftop API returns content for basic and advanced custom fields together. This module
+  # cleans up the response, and creates a collection of ContentField objects, with which we can do
+  # things like parse links.
+  module Content
+    def self.included(base)
+      base.include Rooftop::HookCalls
+      base.send(:add_to_hook, :after_find, ->(r) {
+        # basic content is the stuff which comes from WP by default.
+        if r.respond_to?(:content)
+          basic_fields = r.content[:basic].collect {|k,v| {name: k, value: v, fieldset: "Basic"}}
+          # advanced fields from from ACF, and are exposed in the api in this form:
+          # [
+          #   {
+          #     "title"=>"The fieldset title",
+          #     "fields"=>[
+          #       {"name"=>"field name", "label"=>"display name", "class"=>"type of field", "value"=>"The value of the field"},
+          #       {"name"=>"field name", "label"=>"display name", "class"=>"type of field",
+          #        "value"=>"The value of the field"},
+          #       etc.
+          #     ]
+          #   }
+          # ]
+          # Given that's a bit convoluted, we get both the content types into the same output format, like this:
+          # {"field name", "label"=>"display name", "class"=>"type of field", "value"=>"value of the field", "fieldset"=>"fieldset if there is one, or Basic for the builtin ones"}
+          advanced_fields = r.content[:advanced].collect do |fieldset|
+            fieldset[:fields].each do |field|
+              field.merge!(fieldset: fieldset[:title])
+              field[:type] = field[:class]
+              field.delete(:class)
+            end
+            fieldset[:fields]
+          end.flatten
+          r.fields = Rooftop::Content::Collection.new((basic_fields + advanced_fields))
+        end
+      })
+    end
+  end
+end

data/lib/rooftop/content_fields/field.rb

@@ -0,0 +1,12 @@
+module Rooftop
+  module Content
+    class Field < ::OpenStruct
+
+
+      def to_s
+        value if respond_to?(:value)
+      end
+
+    end
+  end
+end

data/lib/rooftop/errors/record_not_found.rb

@@ -0,0 +1,3 @@
+module Rooftop
+  class RecordNotFound < StandardError; end
+end

data/lib/rooftop/field_aliases.rb

@@ -0,0 +1,41 @@
+# This module allows you to alias one field as another. There's a bit of a circuitous route to
+# getting it done, because you need to push the after_find hook call onto the end of the hash of
+# existing hook calls. See Rooftop::HookCalls for more details.
+
+module Rooftop
+  module FieldAliases
+    def self.included(base)
+      # Include Rooftop::HookCalls to allow us to push things into a list of hooks in the right order
+      base.include Rooftop::HookCalls
+      base.extend ClassMethods
+
+      # Add the call to the :after_find hook to the list of hook calls, to be processed later.
+      # This is where we iterate over our previously established list of field aliases.
+      base.send(:add_to_hook, :after_find, ->(r){
+        r.field_aliases.each do |old, new|
+          if r.respond_to?(old)
+            r.send("#{new}=",r.send(old))
+          end
+        end
+      })
+
+    end
+
+    module ClassMethods
+      # Call alias_field(foo: :bar) in a class to alias the foo as bar.
+      # @param aliases [Sym] a hash of old and new field names
+      def alias_field(*aliases)
+        @field_aliases ||= {}
+        aliases.each do |alias_hash|
+          @field_aliases.merge!(alias_hash)
+        end
+        @field_aliases
+      end
+    end
+
+    # Class method to get the class's field aliases
+    def field_aliases
+      self.class.instance_variable_get(:"@field_aliases") || {}
+    end
+  end
+end

data/lib/{rooftop_client → rooftop}/headers.rb

@@ -2,7 +2,7 @@ module Rooftop
   class Headers < Faraday::Middleware
     def call(env)
       unless Rooftop.configuration.api_token.nil?
-        env[:request_headers]["API-TOKEN"] = Rooftop.configuration.api_token
+        env[:request_headers]["Api-Token"] = Rooftop.configuration.api_token
       end
 
       Rooftop.configuration.extra_headers.each do |key,value|

data/lib/rooftop/hook_calls.rb

@@ -0,0 +1,40 @@
+# This module exists because call order on the hooks provided by Her is important in some cases.
+# For example in Rooftop::FieldAliases we are aliasing the content of a field, which might need to
+# have been coerced first. So we control the order by writing (in a known order) to @hook_calls, and
+# then iterating over them.
+module Rooftop
+  module HookCalls
+    def self.included(base)
+      base.extend ClassMethods
+      # Iterate over an instance var which is a hash of types of hook, and blocks to call
+      # like this {after_find: [->{something}, ->{something}]}
+      base.instance_variable_set(:"@hook_calls", base.instance_variable_get(:"@hook_calls") || {})
+    end
+
+    module ClassMethods
+      # Add something to the list of hook calls, for a particular hook. This is called in other mixins where something is being added to a hook (probably :after_find). For example Rooftop::FieldAliases and Rooftop::FieldCoercions
+      def add_to_hook(hook, block)
+        # get existing hook calls
+        hook_calls = instance_variable_get(:"@hook_calls")
+        # add new one for the appropriate hook
+        if hook_calls[hook].is_a?(Array)
+          hook_calls[hook] << block
+        else
+          hook_calls[hook] = [block]
+        end
+        instance_variable_set(:"@hook_calls",hook_calls)
+      end
+
+      # A method to call the hooks. This iterates over each of the types of hook (:after_find,
+      # :before_save etc, identified here: https://github.com/remiprev/her#callbacks) and sets up
+      # the actual hook. All this is worth it to control order.
+      def setup_hooks!
+        instance_variable_get(:"@hook_calls").each do |type, calls|
+          calls.each do |call|
+            self.send(type, call)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/{rooftop_client → rooftop}/models/media_item.rb

@@ -1,6 +1,6 @@
 module Rooftop
   class MediaItem
     include Rooftop::Base
-    collection_path "media"
+    self.api_endpoint =  "media"
   end
 end

data/lib/rooftop/models/menu.rb

@@ -0,0 +1,9 @@
+module Rooftop
+  class Menu
+    include Rooftop::Base
+    has_many :menu_items, class: "Rooftop::MenuItem"
+    self.api_namespace = "wp-api-menus"
+    self.api_version = 2
+    # coerce_field items: ->(items) { items.collect {|i| MenuItem.new(i)} unless items.nil?}
+  end
+end

data/lib/{rooftop_client → rooftop}/models/taxonomy_term.rb

@@ -1,6 +1,6 @@
 module Rooftop
   class TaxonomyTerm
     include Rooftop::Base
-    primary_key "ID"
+
   end
 end

data/lib/rooftop/nested.rb

@@ -0,0 +1,26 @@
+module Rooftop
+  module Nested
+
+    def ancestors
+      if respond_to?(:resource_links)
+        resource_links.find_by(link_type: "#{Rooftop::ResourceLinks::CUSTOM_LINK_RELATION_BASE}/ancestors")
+      else
+        []
+      end
+    end
+
+    def children
+      if respond_to?(:resource_links)
+        resource_links.find_by(link_type: "#{Rooftop::ResourceLinks::CUSTOM_LINK_RELATION_BASE}/children")
+      else
+        []
+      end
+    end
+
+    def parent
+      if respond_to?(:resource_links)
+        resource_links.find_by(link_type: "up").first
+      end
+    end
+  end
+end

data/lib/rooftop/page.rb

@@ -0,0 +1,17 @@
+module Rooftop
+  module Page
+    def self.included(base)
+      base.include Rooftop::Base
+      base.include Rooftop::Nested
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+
+
+    end
+
+
+
+  end
+end