opencomponents 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8ad282648e755c0c28348bb1b2c243892bc4c100
-  data.tar.gz: bbee3ca89a7c5b264a7e8b17872efed62f711989
+  metadata.gz: bad9832ecad1d26ca9511e032e4c85d948f17f18
+  data.tar.gz: cc277e8e5182192778dec331c80050d3d8dd4c5d
 SHA512:
-  metadata.gz: 0bbfa189e576fd2e24ac401f159adf483d78e67e16a57ba44e87c598e1e493e7d0d87abdb5e121ca58d67adf5b358274c0bcbb4106e48246ec5dbf0c503a77cb
-  data.tar.gz: 03b8c7878cb230499a3f6c5a4e0f1c79684eff6c222c8c76525af770f2267b749eca7f2efef535517c18adb87c27bc334d9318464928342e15c67a7ccd7aed94
+  metadata.gz: f33a1d25e888b0d4ad0a2e158f2b6eebfb93bb2959d3c2965dd8577e1663766dc758fb202d6ba9884f9ec2fe4187bc773a1e6db9e9ae10f62763684150947f37
+  data.tar.gz: 55f5b8e3d0c2aa0c932951a7ee06539c2d60ca55cba65f0d9d9f9021a8446824c919068e911ca4e3ce941b15a08427e52c0105b96caba31b2734d9f9f97a5699

data/README.md

@@ -1,20 +1,28 @@
 # opencomponents
-[![Build Status](https://travis-ci.org/opentable/ruby-oc.svg?branch=master)](https://travis-ci.org/opentable/ruby-oc)
-[![Coverage Status](https://coveralls.io/repos/opentable/ruby-oc/badge.svg)](https://coveralls.io/r/opentable/ruby-oc)
+[![Build Status](https://travis-ci.org/opentable/ruby-oc.svg?branch=master)][1]
+[![Coverage Status](https://coveralls.io/repos/opentable/ruby-oc/badge.svg)][2]
+[![Code Climate](https://codeclimate.com/github/opentable/ruby-oc/badges/gpa.svg)][3]
+[![Gem Version](https://badge.fury.io/rb/opencomponents.svg)][4]
+[![Dependency Status](https://gemnasium.com/opentable/ruby-oc.svg)][5]
 
-[OpenComponents][1] for Ruby
+[1]:https://travis-ci.org/opentable/ruby-oc
+[2]:https://coveralls.io/r/opentable/ruby-oc
+[3]:https://codeclimate.com/github/opentable/ruby-oc
+[4]:http://badge.fury.io/rb/opencomponents
+[5]:https://gemnasium.com/opentable/ruby-oc
 
-[1]:https://github.com/opentable/oc
+[OpenComponents][6] for Ruby
+
+[6]:https://github.com/opentable/oc
 
 ## Important
 This gem is still under heavy development and the API is likely to change at any
 time.
 
 ## Getting Started
-Add the gem to your Gemfile and run `bundle install` (prerelease versions aren't
-on RubyGems):
+Add the gem to your Gemfile and run `bundle install`:
 ```ruby
-gem 'opencomponents', github: 'opentable/ruby-oc'
+gem 'opencomponents', '~> 0.1.0'
 ```
 
 By default, the gem will attempt to use a component registry located at
@@ -25,14 +33,48 @@ it with:
 OpenComponents.configure { |config| config.registry = 'http://some.other.host' }
 ```
 
+## Getting Rendered Components
+To request an OpenComponent with its rendered HTML, you can create and load a new
+`RenderedComponent` object.
+```ruby
+component = OpenComponents::RenderedComponent.new('my-awesome-component')
+component.load
+```
+
+Optionally, you can also specify parameters, the component version, and
+additional HTTP headers to request:
+```ruby
+component = OpenComponents::RenderedComponent.new(
+  'my-awesome-component',
+  params: {name: 'Kate'},
+  version: '1.0.2',
+  headers: {accept_language: 'emoji'}
+)
+```
+
+## Getting Pre-rendered Components
+If you'd like to perform the component rendering yourself, you can request a
+pre-rendered component from a registry using a `PrerenderedComponent` object.
+```ruby
+component = OpenComponents::PrerenderedComponent.new('my-awesome-component')
+component.load
+```
+
+You can use the same optional `params`, `version`, and `headers` arguments as
+`RenderedComponent`s.
+
+**Note**: `PrerenderedComponent`s will only fetch component data for you - they
+do not provide an interface for rendering them. At the moment, it's up to you to
+determine the best way to render the template.
+
 ## Integrations
 Individual integrations for rendering components in Rails and Sinatra are
 available.
-  * [opencomponents-rails][2]
-  * [sinatra-opencomponents][3]
+  * [opencomponents-rails][7]
+  * [sinatra-opencomponents][8]
 
-[2]:https://github.com/opentable/opencomponents-rails
-[3]:https://github.com/opentable/sinatra-opencomponents
+[7]:https://github.com/opentable/opencomponents-rails
+[8]:https://github.com/opentable/sinatra-opencomponents
 
 ## Contributing
 Would be rad. Open a PR or Issue if you have an idea for improvements.

data/lib/opencomponents.rb

@@ -5,17 +5,41 @@ require 'opencomponents/renderer'
 require 'opencomponents/version'
 
 module OpenComponents
+  # Public: Default OC registry URL (http://localhost:3030).
   DEFAULT_REGISTRY = 'http://localhost:3030'
 
+  # Internal: Custom exception class to raise in the event a component cannot be
+  #   found in the registry.
   ComponentNotFound = Class.new(RuntimeError)
 
+  # Internal: Stores configuration data.
+  #
+  # registry - String for the registry host.
   Configuration = Struct.new(:registry)
-  Template      = Struct.new(:src, :type, :key)
 
+  # Internal: Wrapper object for pre-rendered OC templates.
+  #
+  # src  - String for the template URL.
+  # type - String for template engine type.
+  # key  - String for template key.
+  Template = Struct.new(:src, :type, :key)
+
+  # Public: Getter for OC Configuration.
+  #
+  # Returns the Configuration if set, a default Configuration if not set.
   def self.config
     @@_config ||= Configuration.new(DEFAULT_REGISTRY)
   end
 
+  # Public: Setter for Configuration.
+  #
+  # Examples
+  #
+  #   OpenComponents.configure do |oc|
+  #     oc.registry = 'http://my-awesome-oc-registry.com'
+  #   end
+  #
+  # Returns the Configuration.
   def self.configure
     yield self.config
   end

data/lib/opencomponents/component.rb

@@ -1,20 +1,67 @@
 require 'rest-client'
 
 module OpenComponents
+  # Wrapper object for a component fetched from an OC registry.
   class Component
-    attr_reader :name, :version, :params, :href, :registry_version,
-                :type, :render_mode
+    # Public: Gets/sets the String name of the component.
+    attr_accessor :name
 
-    def initialize(name, params = {}, version = '')
+    # Public: Gets/sets the desired String version of the component.
+    attr_accessor :version
+
+    # Public: Gets/sets a Hash of params to send in the component request.
+    attr_accessor :params
+
+    # Public: Gets/sets a Hash of headers to send in the component request.
+    attr_accessor :headers
+
+    # Public: Returns the String URL of the requested component.
+    attr_reader :href
+
+    # Public: Returns the String version of the component as served by the
+    #   registry.
+    attr_reader :registry_version
+
+    # Public: Returns the String type of the component as served by the
+    #   registry.
+    attr_reader :type
+
+    # Public: Returns the String render mode of the component as served by the
+    #   registry. Generally either `rendered` or `pre-rendered`.
+    attr_reader :render_mode
+
+    # Public: Initializes a new Component subclass.
+    #
+    # name - The String name of the component to request.
+    # opts - A Hash of options to use when requesting the component
+    #   (default: {}).
+    #        :params  - A Hash of parameters to send in the component request
+    #          (optional, default: {}).
+    #        :version - The String version of the component to request
+    #          (optional, default: '').
+    #        :headers - A Hash of HTTP request headers to include in the
+    #          component request (optional, default: {}).
+    def initialize(name, opts = {})
       @name    = name
-      @params  = params
-      @version = version
+      @params  = opts[:params]  || {}
+      @version = opts[:version] || ''
+      @headers = opts[:headers] || {}
     end
 
+    # Public: Returns the String value of `requestVersion` from a component
+    #   response, `nil` if not present.
     def request_version
       @request_version == '' ? nil : @request_version
     end
 
+    # Public: Resets all component attributes from a registry response to `nil`.
+    #
+    # Examples
+    #
+    #   component.flush!
+    #   # => #<OpenComponents::RenderedComponent: ... >
+    #
+    # Returns the reset Component.
     def flush!
       flush_variables_whitelist.each do |var|
         instance_variable_set(var, nil)
@@ -23,6 +70,15 @@ module OpenComponents
       self
     end
 
+    # Public: Resets all component attributes and reloads them from a registry
+    #   response.
+    #
+    # Examples
+    #
+    #   component.reload!
+    #   # => #<OpenComponents::RenderedComponent: ... >
+    #
+    # Returns the reloaded Component.
     def reload!
       flush!
       load
@@ -30,6 +86,11 @@ module OpenComponents
 
     protected
 
+    # Internal: Executes a component request and sets attributes common to all
+    #   component render modes. Public-facing `#load` methods exist on Component
+    #   subclasses.
+    #
+    # Returns the Component.
     def load
       @href             = response_data['href']
       @registry_version = response_data['version']
@@ -40,32 +101,47 @@ module OpenComponents
       self
     end
 
+    # Internal: Builds the URL to send a component request to.
+    #
+    # Returns the String URL to request a component from.
     def url
       File.join(OpenComponents.config.registry, name, version)
     end
 
+    # Internal: Executes a component request against the configured registry.
+    #
+    # Returns a response body String.
+    # Raises OpenComponents::ComponentNotFound if the registry responds with a
+    #   404.
     def response
+      request_headers = headers.merge(params: params)
+
       RestClient::Request.execute(
         method: :get,
         url: url,
         timeout: 10,
-        headers: {
-          accept: accept_header,
-          params: params,
-        }
+        headers: request_headers
       )
     rescue RestClient::ResourceNotFound => e
       fail ComponentNotFound, e.message
     end
 
+    # Internal: Helper method for converting and memoizing registry response
+    #   data.
+    #
+    # Returns a Hash of registry response data.
     def response_data
       @_response_data ||= JSON.parse(response)
     end
 
     private
 
+    # Internal: Whitelists instance variable names allowed to be reset when
+    #   calling `#flush!`.
+    #
+    # Returns an Array of instance variable Symbols allowed to be reset.
     def flush_variables_whitelist
-      instance_variables - [:@name, :@version, :@params]
+      instance_variables - [:@name, :@version, :@params, :@headers]
     end
   end
 end

data/lib/opencomponents/prerendered_component.rb

@@ -1,7 +1,42 @@
 module OpenComponents
+  # Wrapper object for components using the `pre-rendered` rendering mode.
   class PrerenderedComponent < Component
-    attr_reader :data, :template
+    # Internal: Default HTTP headers to send when requesting a component.
+    DEFAULT_HEADERS = {accept: 'application/vnd.oc.prerendered+json'}
 
+    # Public: Returns a Hash of data to use when rendering the component.
+    attr_reader :data
+
+    # Public: Returns a Template with data for rendering the raw component.
+    attr_reader :template
+
+    # Public: Initializes a new PrerenderedComponent.
+    #
+    # name - The String name of the component to request.
+    # opts - A Hash of options to use when requesting the component
+    #   (default: {}).
+    #        :params  - A Hash of parameters to send in the component request
+    #          (optional, default: {}).
+    #        :version - The String version of the component to request
+    #          (optional, default: nil).
+    #        :headers - A Hash of HTTP request headers to include in the
+    #          component request (optional, default: DEFAULT_HEADERS).
+    def initialize(name, opts = {})
+      super(name, opts)
+
+      @headers.merge!(DEFAULT_HEADERS)
+    end
+
+    # Public: Executes a request for the Component against the configured
+    #   registry and sets the component attributes.
+    #
+    # Examples
+    #
+    #   component = OpenComponents::RenderedComponent.new('my-component')
+    #   component.load
+    #   # => #<OpenComponents::RenderedComponent: ... >
+    #
+    # Returns the Component with attributes set.
     def load
       template_data = response_data['template']
 
@@ -12,11 +47,5 @@ module OpenComponents
 
       super
     end
-
-    private
-
-    def accept_header
-      'application/vnd.oc.prerendered+json'
-    end
   end
 end

data/lib/opencomponents/rendered_component.rb

@@ -1,17 +1,23 @@
 module OpenComponents
+  # Wrapper object for components using the `rendered` rendering mode.
   class RenderedComponent < Component
+    # Public: Returns the HTML String for the rendered component.
     attr_reader :html
 
+    # Public: Executes a request for the Component against the configured
+    #   registry and sets the component attributes.
+    #
+    # Examples
+    #
+    #   component = OpenComponents::RenderedComponent.new('my-component')
+    #   component.load
+    #   # => #<OpenComponents::RenderedComponent: ... >
+    #
+    # Returns the Component with attributes set.
     def load
       @html = response_data['html']
 
       super
     end
-
-    private
-
-    def accept_header
-      nil
-    end
   end
 end

data/lib/opencomponents/renderer.rb

@@ -1,7 +1,20 @@
 module OpenComponents
+  # Provides rendering helper methods for components.
   module Renderer
-    def render_component(component, params = {}, version = '')
-      OpenComponents::RenderedComponent.new(component, params, version)
+    # Public: Builds a new RenderedComponent, executes a request for it against
+    #   the configured registry, and returns the rendered component HTML.
+    #
+    # component - The String name of the component to render.
+    # opts - A Hash of options to use when requesting the component
+    #   (default: {}).
+    #        :params  - A Hash of parameters to send in the component request
+    #          (optional, default: {}).
+    #        :version - The String version of the component to request
+    #          (optional, default: nil).
+    #        :headers - A Hash of HTTP request headers to include in the
+    #          component request (optional, default: {}).
+    def render_component(component, opts = {})
+      OpenComponents::RenderedComponent.new(component, opts)
         .load
         .html
     end

data/lib/opencomponents/version.rb

@@ -1,3 +1,3 @@
 module OpenComponents
-  VERSION = '0.1.0'
+  VERSION = '0.2.0' # :nodoc:
 end

data/opencomponents.gemspec

@@ -20,4 +20,5 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
   spec.summary       = spec.description
   spec.version       = OpenComponents::VERSION
+  spec.rdoc_options  = ['--markup=tomdoc']
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opencomponents
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Todd Bealmear
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-02 00:00:00.000000000 Z
+date: 2015-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -59,7 +59,8 @@ licenses:
 - MIT
 metadata: {}
 post_install_message: 
-rdoc_options: []
+rdoc_options:
+- "--markup=tomdoc"
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement