yaks 0.8.0.beta2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e70fb16fe2a8b8d06d5748409ac51ce7de353cba
-  data.tar.gz: ed91cadda25837e29c307bed1caa86b7e93bb5b4
+  metadata.gz: 1784c312fc3b6f4a71be14c06506fafcc0dddcef
+  data.tar.gz: b44cc96127c4311a2ee91a74404d702a189b54b5
 SHA512:
-  metadata.gz: 61c520e3fa43ee9de85d54b1bf478c3d0ef68933f98c31668a8f7330bf75b1306edb1f442824434843e50d0d03068ad7f0a0a05fa8212adbf895ebd24ce97e40
-  data.tar.gz: ad0ab6ae6c9d0d385baf8bdaeef55c6cbffdaf2a3b87fadf30e7d28f2cf0a17bfa71967396963771aeebe5decd75ef2e986ebfe634501145e4e56c18eeb5a416
+  metadata.gz: 10c08be52835165067815e4df2c53dde58109f704efc1b2557a4be3813321d524452ed7799481fa6c422a8be84e6abbd8e9a67e7cf796918c5621ac50e50b853
+  data.tar.gz: 0c2d814f5022ddf9f29d64bb7424da0de584d69a46d48fd5ab58d9397e4f3c73757ae93b0bff49a2f1ded8072b90ef7595cc35108119dbd27f23c86a3c10d5e0

data/README.md

@@ -26,7 +26,7 @@ requested. These formats are presently supported:
 ## State of Development
 
 This library came into existence because we at
-[Ticketsolve](https://www.ticketsolve.com) wanted to build a rich
+[Ticketsolve](http://www.ticketsolve.com) wanted to build a rich
 hypermedia API, and were dissatisfied with any of the existing Ruby
 solutions at the time (November 2013).
 
@@ -37,7 +37,7 @@ supporting hypermedia formats in Ruby.
 Yaks can be used in production today, as we do, but until 1.0 is
 released there will regularly be breaking changes, as we figure out
 the best way to do things. These are all documented clearly in the
-[changelog](CHANGLOG.md). At this point we recommend locking to an
+[changelog](/CHANGELOG.md). At this point we recommend locking to an
 exact version number.
 
 ## Concepts
@@ -138,6 +138,30 @@ class CommentMapper < Yaks::Mapper
 end
 ```
 
+### Forms
+
+Mapper can contain form defintions, for formats that support them. The
+form DSL mimics the HTML5 field and attribute names.
+
+```ruby
+class PostMapper < Yaks::Mapper
+  attributes :id, :body, :date
+
+  form :add_comment do
+    action '/api/comments'
+    method 'POST'
+    media_type 'application/json'
+
+    text :body
+    hidden :post_id, value: -> { object.id }
+  end
+end
+```
+
+TODO: add more info on form element types, attributes, conditional
+rendering of forms, dynamic form sections, ...
+
+
 #### Filtering
 
 You can override `#attributes`, or `#associations`.
@@ -196,11 +220,16 @@ end
 
 ```
 
-You can pass a symbol instead of a template, in that case the symbol will be used as a method name on the object to retrieve the link. You can override this behavior just like with attributes.
+You can pass a proc instead of a template, in that case the proc will
+be resolved in the context of the mapper. What this means is that, if
+the proc takes no arguments, it will be evaluated with the mapper
+instance as the value of `self`. If the proc does take an argument,
+then it will receive the mapper instance, and will be evaluated as a
+closure, i.e. with access to the scope in which it was defined.
 
 ```ruby
 class FooMapper < Yaks::Mapper
-  link 'http://api.foo.com/rels/go_home', :home_url
+  link 'http://api.foo.com/rels/go_home', -> { home_url }
   # by default calls object.home_url
 
   def home_url
@@ -209,6 +238,21 @@ class FooMapper < Yaks::Mapper
 end
 ```
 
+
+To only include links based on certain conditions, add an `:if`
+option, passing it a block. The block will be resolved in the context
+of the mapper, as explained before.
+
+For example, say you want to notify the consumer of your API that upon
+confirming an order, the previously held cart is no longer valid, you
+could use the IANA standard `invalidates` rel to communicate this.
+
+``` ruby
+class OrderMapper < BaseMapper
+  link :invalidates, '/api/cart', if: ->{ env['api.invalidate_cart'] }
+end
+```
+
 ### Associations
 
 Use `has_one` for an association that returns a single object, or `has_many` for embedding a collection.
@@ -218,6 +262,7 @@ Options
 * `:mapper` : Use a specific for each instance, will be derived from the class name if omitted (see Policy vs Configuration)
 * `:collection_mapper` : For mapping the collection as a whole, this defaults to Yaks::CollectionMapper, but you can subclass it for example to add links or attributes on the collection itself
 * `:rel` : Set the relation (symbol or URI) this association has with the object. Will be derived from the association name and the configured rel_template if ommitted
+* `:if`: Only render the association if a condition holds
 * `:link_if`: Conditionally render the association as a link. A `:href` option is required
 
 ```ruby

data/lib/yaks/format/collection_json.rb

@@ -77,11 +77,7 @@ module Yaks
       protected
 
       def form_is_query?(form)
-        method_is_get?(form.method) && !form.action.nil?
-      end
-
-      def method_is_get?(method)
-        !method.nil? && method.downcase.to_sym === :get
+        form.method?(:get) && form.has_action?
       end
 
       def template_form_exists?(resource)

data/lib/yaks/mapper/association.rb

@@ -6,7 +6,8 @@ module Yaks
                 item_mapper: Undefined,
                 rel:         Undefined,
                 href:        Undefined,
-                link_if:     Undefined
+                link_if:     Undefined,
+                if:          Undefined
               ),
               Util
 
@@ -21,6 +22,7 @@ module Yaks
       end
 
       def add_to_resource(resource, parent_mapper, context)
+        return resource if self.if != Undefined && !parent_mapper.expand_value(self.if)
         AssociationMapper.new(parent_mapper, self, context).call(resource)
       end
 

data/lib/yaks/mapper/form.rb

@@ -15,6 +15,7 @@ module Yaks
           )
         end
         def_forward :dynamic
+        def_forward :condition
       end
 
       def_delegators :config, :name, :action, :title, :method,
@@ -36,6 +37,7 @@ module Yaks
       include Concord.new(:config)
 
       def add_to_resource(resource, mapper, _context)
+        return resource if config.if && !mapper.expand_value(config.if)
         resource.add_form(to_resource(mapper))
       end
 

data/lib/yaks/mapper/form/config.rb

@@ -9,12 +9,17 @@ module Yaks
                   method: nil,
                   media_type: nil,
                   fields: [],
-                  dynamic_blocks: []
+                  dynamic_blocks: [],
+                  if: nil
                 )
 
         def dynamic(&blk)
           append_to(:dynamic_blocks, blk)
         end
+
+        def condition(prc = nil, &blk)
+          with(if: prc || blk)
+        end
       end
     end
   end

data/lib/yaks/mapper/form/field.rb

@@ -28,14 +28,14 @@ module Yaks
           Resource::Form::Field.new(
             resource_attributes.each_with_object({}) do |attr, attrs|
               attrs[attr] = mapper.expand_value(public_send(attr))
-            end.merge(options: resource_options)
+            end.merge(options: resource_options(mapper))
           )
         end
 
-        def resource_options
+        def resource_options(mapper)
           # make sure all empty options arrays are the same instance,
           # makes for prettier #pp
-          options.empty? ? options : options.map(&:to_resource)
+          options.empty? ? options : options.map {|opt| opt.to_resource_field_option(mapper) }
         end
 
         # All attributes that can be converted 1-to-1 to

data/lib/yaks/mapper/form/field/option.rb

@@ -10,8 +10,12 @@ module Yaks
             new(opts.merge(value: value))
           end
 
-          def to_resource
-            Resource::Form::Field::Option.new(to_h)
+          def to_resource_field_option(mapper)
+            Resource::Form::Field::Option.new(
+              value: mapper.expand_value(value),
+              label: mapper.expand_value(label),
+              selected: mapper.expand_value(selected),
+            )
           end
         end
       end

data/lib/yaks/mapper/link.rb

@@ -55,6 +55,8 @@ module Yaks
       end
 
       def map_to_resource_link(mapper)
+        return unless mapper.expand_value(options.fetch(:if, true))
+
         uri = mapper.expand_uri(template, options.fetch(:expand, true))
         return if uri.nil?
 
@@ -69,7 +71,7 @@ module Yaks
         options = options()
         options = options.merge(title: Resolve(options[:title], mapper)) if options.key?(:title)
         options = options.merge(templated: true) if templated?
-        options.reject{|key| [:expand, :replace].include? key }
+        options.reject{|key| [:expand, :replace, :if].include? key }
       end
 
     end

data/lib/yaks/resource/form.rb

@@ -14,8 +14,8 @@ module Yaks
         end
       end
 
-      def fields_flat(fields = fields)
-        fields.each_with_object([]) do |field, acc|
+      def fields_flat(fs = fields)
+        fs.each_with_object([]) do |field, acc|
           if field.type.equal? :fieldset
             acc.concat(fields_flat field.fields)
           else
@@ -23,6 +23,14 @@ module Yaks
           end
         end
       end
+
+      def method?(meth)
+        !method.nil? && method.downcase.to_sym === meth.downcase.to_sym
+      end
+
+      def has_action?
+        !action.nil?
+      end
     end
   end
 end

data/lib/yaks/version.rb

@@ -1,3 +1,3 @@
 module Yaks
-  VERSION = '0.8.0.beta2'
+  VERSION = '0.8.0'
 end

data/spec/unit/yaks/mapper/association_spec.rb

@@ -7,7 +7,8 @@ RSpec.describe Yaks::Mapper::Association do
       item_mapper: mapper,
       rel: rel,
       href: href,
-      link_if: link_if
+      link_if: link_if,
+      if: self.if
     )
   end
 
@@ -16,6 +17,7 @@ RSpec.describe Yaks::Mapper::Association do
   let(:rel)               { Yaks::Undefined }
   let(:href)              { Yaks::Undefined }
   let(:link_if)           { Yaks::Undefined }
+  let(:if)                { Yaks::Undefined }
 
   its(:name)        { should equal :shoes }
   its(:item_mapper) { should equal Yaks::Mapper }
@@ -45,6 +47,23 @@ RSpec.describe Yaks::Mapper::Association do
     it 'should delegate to AssociationMapper' do
       expect(association.add_to_resource(Yaks::Resource.new, parent_mapper, yaks_context)).to eql Yaks::Resource.new(subresources: [Yaks::Resource.new(rels: ['rel:shoes'])])
     end
+
+    context 'with a truthy condition' do
+      let(:if)     { ->{ true } }
+
+      it 'should add the association' do
+        expect(association.add_to_resource(Yaks::Resource.new, parent_mapper, yaks_context).subresources.length).to be 1
+      end
+    end
+
+    context 'with a falsey condition' do
+      let(:if)     { ->{ false } }
+
+      it 'should not add the association' do
+        expect(association.add_to_resource(Yaks::Resource.new, parent_mapper, yaks_context).subresources.length).to be 0
+      end
+    end
+
   end
 
   describe '#render_as_link?' do

data/spec/unit/yaks/mapper/form/field/option_spec.rb

@@ -0,0 +1,19 @@
+RSpec.describe Yaks::Mapper::Form::Field::Option do
+  include_context 'yaks context'
+
+  let(:mapper_class) do
+    Class.new(Yaks::Mapper) do
+      def color
+        :yellow
+      end
+    end
+  end
+
+  let(:mapper) { mapper_class.new(yaks_context) }
+
+  let(:option) { described_class.new(value: ->{color}, label: :color) }
+
+  it 'should expand procs in the context of the mapper' do
+    expect(option.to_resource_field_option(mapper)).to eql Yaks::Resource::Form::Field::Option.new(value: :yellow, label: :color, selected: false)
+  end
+end

data/spec/unit/yaks/mapper/form_spec.rb

@@ -1,4 +1,6 @@
 RSpec.describe Yaks::Mapper::Form do
+  include_context 'yaks context'
+
   let(:form)   { described_class.create( full_args ) }
   let(:name)      { :the_name }
   let(:full_args) { {name: name}.merge(args) }
@@ -20,8 +22,8 @@ RSpec.describe Yaks::Mapper::Form do
   end
 
   describe '#add_to_resource' do
-    let(:resource) { form.new.add_to_resource(Yaks::Resource.new, Yaks::Mapper.new(nil), nil) }
-
+    let(:mapper) { Yaks::Mapper.new(yaks_context) }
+    let(:resource) { form.new.add_to_resource(Yaks::Resource.new, mapper, nil) }
 
     context 'with fields' do
       let(:fields) {
@@ -34,7 +36,23 @@ RSpec.describe Yaks::Mapper::Form do
           )
         ]
       }
+    end
+
+    context 'with a truthy condition' do
+      let(:form) { described_class.create { condition { true }}}
 
+      it 'should add the form' do
+        expect(form.add_to_resource(Yaks::Resource.new, mapper, nil).forms.length).to be 1
+      end
     end
+
+    context 'with a falsey condition' do
+      let(:form) { described_class.create { condition { false }}}
+
+      it 'should not add the form' do
+        expect(form.add_to_resource(Yaks::Resource.new, mapper, nil).forms.length).to be 0
+      end
+    end
+
   end
 end

data/spec/unit/yaks/mapper/link_spec.rb

@@ -68,6 +68,26 @@ RSpec.describe Yaks::Mapper::Link do
         )
       end
     end
+
+    context 'with :if defined and resolving to true' do
+      let(:options) { { if: ->{ true } } }
+
+      it 'should render the link' do
+        expect(link.add_to_resource(Yaks::Resource.new, mapper, yaks_context)).to eql(
+          Yaks::Resource.new(links: [Yaks::Resource::Link.new(rel: :next, uri: "/foo/bar/3/4")])
+        )
+      end
+    end
+
+    context 'with :if defined and resolving to false' do
+      let(:options) { { if: ->{ false } } }
+
+      it 'should not render the link' do
+        expect(link.add_to_resource(Yaks::Resource.new, mapper, yaks_context)).to eql(
+          Yaks::Resource.new
+        )
+      end
+    end
   end
 
   describe '#rel?' do
@@ -174,6 +194,38 @@ RSpec.describe Yaks::Mapper::Link do
         expect(resource_link).to be_nil
       end
     end
+
+    context 'with a if lambda resolving to true' do
+      let(:options) { { if: -> { add_link? } } }
+
+      before do
+        mapper_class.class_eval do
+          def add_link?
+            true
+          end
+        end
+      end
+
+      it 'should evaluate the lambda in the context of the mapper' do
+        expect(resource_link).to be_a(Yaks::Resource::Link)
+      end
+    end
+
+    context 'with a if lambda resolving to false' do
+      let(:options) { { if: -> { add_link? } } }
+
+      before do
+        mapper_class.class_eval do
+          def add_link?
+            false
+          end
+        end
+      end
+
+      it 'should evaluate the lambda in the context of the mapper' do
+        expect(resource_link).to be_nil
+      end
+    end
   end
 
   describe '.create' do

data/spec/unit/yaks/resource/form_spec.rb

@@ -49,4 +49,39 @@ RSpec.describe Yaks::Resource::Form do
     end
   end
 
+  describe "#method?" do
+    it 'should return true if method matches' do
+      form_sym = Yaks::Resource::Form.new(name: :foo, method: :get)
+      form_str = Yaks::Resource::Form.new(name: :foo, method: 'GET')
+
+      expect(form_sym.method?(:get)).to eq(true)
+      expect(form_sym.method?('get')).to eq(true)
+      expect(form_str.method?(:get)).to eq(true)
+      expect(form_str.method?('GET')).to eq(true)
+    end
+
+    it 'should return false if method does not match' do
+      form_sym = Yaks::Resource::Form.new(name: :foo, method: :get)
+      form_str = Yaks::Resource::Form.new(name: :foo, method: 'GET')
+
+      expect(form_sym.method?(:post)).to eq(false)
+      expect(form_sym.method?('patch')).to eq(false)
+      expect(form_str.method?(:delete)).to eq(false)
+      expect(form_str.method?('PUT')).to eq(false)
+    end
+  end
+
+  describe "#has_action?" do
+     it 'should return true if form has an action url' do
+      form = Yaks::Resource::Form.new(name: :foo, action: "/my-action")
+
+      expect(form.has_action?).to eq(true)
+    end
+
+    it 'should return false if form has not an action url' do
+      form = Yaks::Resource::Form.new(name: :foo)
+
+      expect(form.has_action?).to eq(false)
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yaks
 version: !ruby/object:Gem::Version
-  version: 0.8.0.beta2
+  version: 0.8.0
 platform: ruby
 authors:
 - Arne Brasseur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-14 00:00:00.000000000 Z
+date: 2015-02-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inflection
@@ -339,6 +339,7 @@ files:
 - spec/unit/yaks/mapper/association_spec.rb
 - spec/unit/yaks/mapper/attribute_spec.rb
 - spec/unit/yaks/mapper/config_spec.rb
+- spec/unit/yaks/mapper/form/field/option_spec.rb
 - spec/unit/yaks/mapper/form/field_spec.rb
 - spec/unit/yaks/mapper/form_spec.rb
 - spec/unit/yaks/mapper/has_many_spec.rb
@@ -374,9 +375,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.2.2
@@ -429,6 +430,7 @@ test_files:
 - spec/unit/yaks/mapper/association_spec.rb
 - spec/unit/yaks/mapper/attribute_spec.rb
 - spec/unit/yaks/mapper/config_spec.rb
+- spec/unit/yaks/mapper/form/field/option_spec.rb
 - spec/unit/yaks/mapper/form/field_spec.rb
 - spec/unit/yaks/mapper/form_spec.rb
 - spec/unit/yaks/mapper/has_many_spec.rb