excalibur 0.0.2

data/lib/generators/excalibur/install_generator.rb

@@ -0,0 +1,18 @@
+require 'rails/generators/base'
+
+module Excalibur
+  module Generators
+    # the install generator allows you to get a free to use and fully
+    # documented initializer file for your rails app by running:
+    # rails g excalibur:install
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('../../templates', __FILE__)
+
+      desc 'Creates a Excalibur initializer.'
+
+      def copy_initializer
+        template 'excalibur.rb', 'config/initializers/excalibur.rb'
+      end
+    end
+  end
+end

data/lib/generators/templates/decorator.rb

@@ -0,0 +1,75 @@
+class Excalibur::<%= class_name %>Decorator < Excalibur::Decorator
+  # ==> Full custom configuration
+  # it is possible to force a new config onto over the application wide
+  # default set in the initializer.
+  #
+  # You can pass a custom configuration in like so:
+  # excalibur_init @my_custom_config
+  #
+  # or start with a blank configuration like so:
+  # excalibur_init Excalibur::Configuration.new
+  #
+  # The last method is easiest as all configuration options are available in
+  # this decorator through a DSL instead of building the object from scratch.
+
+  # ==> Title and Description settings
+  # Titles and descriptions act mostly the same way within Excalibur. They
+  # share the same DSL with the small difference in method name. Below the
+  # description is for title but it applies to description as well.
+  #
+  # => Set content
+  # the excalibur_set_title_content method takes two parameters to change the
+  # content of a title. By defaults you can set a :prefix, :body and :suffix.
+  # All of these can be a string or a Proc.
+  #
+  # as an example:
+  # excalibur_set_title_content :body, 'my class specific title body'
+  #
+  # => Set option
+  # the excalibur_set_title_option method takes two arguments to change the
+  # options of a title. By defaults you can set a :length, :omission and
+  # :separator.
+  #
+  # :length takes any integer to indicate the length limit of the title.
+  # :omission is what fills the end of the line when the body is truncated
+  # below the limited length of the title :body.
+  # :separator determines what character the :body will be truncated on. with
+  # a single space (' ') it will break on words and with no-space ('') it
+  # will break on any character.
+  #
+  # as an examples:
+  # excalibur_set_title_content :length, 42
+  # excalibur_set_title_content :omission, '... (continued)'
+  #
+  # => set combinator
+  # the excalibur_set_title_combinator takes one argument and it should be a
+  # Proc. The proc is passed the decorated object so you have access to the
+  # object and the configuration of required. It needs to result in a string.
+  #
+  # excalibur_set_title_combinator(proc { |obj|
+  #   # your code here
+  # })
+
+  # ==> Meta tag settings
+  # the excalibur_set_meta_tag method takes three arguments to set the content
+  # for a meta tag. The first and second arguments are about the type of meta
+  # tag while the third is used for the content.
+  #
+  # A description meta tag would look like this:
+  # excalibur_set_meta_tag :name, :description, 'Some description content'
+  #
+  # The content of a meta tag can be anything that prints nicely into a
+  # string, a Proc or an Array. The Proc may also result in an array and is
+  # passed the decorated object for access to the objects attributes and the
+  # excalibur configuration acting for the object.
+
+  # ==> Recommended use
+  # Because the title, description and the meta tags all allow for a Proc to
+  # be passed it gives you a lot of freedom. However like any freedom it is to
+  # be used with some warning. It is recommended when doing larger amounts of
+  # work in code of a proc to use the decorator to delegate that
+  # responsibility. The decorator becomes easier to test and it is also a lot
+  # cleaner.
+  #
+  # TODO: An article about how to do it properly will come soon!
+end

data/lib/generators/templates/excalibur.rb

@@ -0,0 +1,151 @@
+# Use this to set up your default
+Excalibur.configure do |config|
+  # ==> Your sane defaults:
+
+  # => Title content
+  # config.title.update_content :prefix, 'prefix - '
+  config.title.update_content :body, 'My website has a title by Excalibur'
+
+  # => Title options
+  # config.title.update_option :length, 69
+  # config.title.update_option :omission, '...'
+  # config.title.update_option :separator, ''
+
+  # => Description content
+  config.description.update_content :body, 'Excalibur gave me a description!'
+
+  # => Description options
+  # config.description.update_option :length, 155
+  # config.description.update_option :omission, '...'
+  # config.description.update_option :separator, ' '
+
+  # => Meta tags
+  config.set_meta_tag :name, :viewport, 'width=device-width, initial-scale=1'
+
+  # ==> Configuration DSL:
+  #
+  # Both the title and description are configurable in the same way;
+  # config.title for the title and config.description for the description.
+  # They both consist out of three elements; content, options and the
+  # combinator. The meta tags have their own interface as they are slightly
+  # different. Both the content in the title/description and the content in
+  # the meta tags can be given a Proc in order for on-render computation to
+  # occur.
+
+  # => Title/Description content
+  # The default of the gem tries to combine 3 parts; :prefix,
+  # :body and :suffix. They are put together in that order by the default
+  # combinator.
+  #
+  # To set these add:
+  # config.title.update_content :prefix, 'CNN.com - '
+  # config.title.update_content :body, 'Breaking, World, Business, Sports and
+  # Entertainment News'
+  #
+  # this will result in a title like 'CNN.com - Breaking, World, Business,
+  # Sports and Entertainment News'
+  #
+  # > Title Defaults:
+  # prefix: ''
+  # body: 'Excalibur'
+  # suffix: ''
+  #
+  # > Description Defaults:
+  # prefix: ''
+  # body: 'Excalibur; a worthy title for a gem about titles.'
+  # suffix: ''
+
+  # => Title/Description options
+  # The default of the gem uses the options to truncate the content
+  # components in the correct way. :length is the length the content will be
+  # truncated to. :omission is used to indicate that the content is truncated
+  # and is added behind the section that has been truncated. :separator
+  # determines if truncation happens on a character or not,
+  # '' for every letter and ' ' for a space as it allows for breaking on words
+  # or characters.
+  #
+  # To set these add:
+  # config.title.update_option :length, 42
+  # config.title.update_option :omission, '... (continued)'
+  #
+  # > Title Defaults:
+  # length: 69
+  # omission: '...'
+  # separator: ''
+  #
+  # > Description Defaults:
+  # length: 155
+  # omission: '...'
+  # separator: ' '
+
+  # => Title/Description combinator
+  # The combinator is by default a proc that combines the content elements
+  # together and truncates them according to what the options have specified.
+  # If your not into it yet the combinator is to be changed with caution.
+  #
+  # Change the combinator by:
+  # config.title.update_combinator(
+  #     proc do |object|
+  #       # your code here
+  #       #
+  #       # the object var is passed when rendering and contains an object
+  #       # with the current configuration for that render. It's advised when
+  #       # using data from that configuration to use object.configuration to
+  #       # access it.
+  #     end
+  # )
+  #
+  # > Default behavior
+  # By default the combinator takes the 3 content sections but only truncates
+  # the :body section. This does take into account the length of the :prefix
+  # and :suffix when truncating the content so the overall length of the
+  # title stays within the length set in the options.
+  #
+  # > Title/Description configuration examples:
+  # content:
+  #   prefix: 'Excalibur | '
+  #   body: 'The Object oriented way of setting SEO and meta information'
+  # options:
+  #   length: 69
+  #   omission: '...'
+  #   separator: ''
+  # result: 'Excalibur | The Object oriented way of setting SEO and meta
+  #     inform...'
+  #
+  # options:
+  #   separator: ' '
+  # result: 'Excalibur | The Object oriented way of setting SEO and meta...'
+  #
+  # content:
+  #   body: 'Just another website'
+  #   suffix: ' - site ID'
+  # result: 'Just another website - site ID'
+
+  # => Meta tags
+  # Meta tags are basically represented in the configuration as a double
+  # layered hash. The hash is converted to meta tags types and the values are
+  # the content of the meta tag.
+  #
+  # These can be easily set using:
+  # config.set_meta_tag(
+  #     :name,
+  #     :viewport,
+  #     'width=device-width, initial-scale=1')
+
+  # => General configuration:
+  # it is possible to roll your own configuration without using the accessors
+  # provided in the DSL. You can use the Excalibur::Configuration class to
+  # create your own config. Have a look at the code how to do so!
+  #
+  # you can set it by simply:
+  # config = MyCustomConfiguration.new
+  #
+  # If you want to keep using parts of the default configuration but want to
+  # replace others configuration has a #merge! method to merge another
+  # Excalibur::Configuration object into the default. Note that this will only
+  # work if the supplied object is a Excalibur::Configuration or an inherited
+  # object.
+  #
+  # use this by:
+  # config.merge!(MyCustomConfiguration.new)
+end

data/spec/lib/excalibur/configuration_spec.rb

@@ -0,0 +1,215 @@
+require 'spec_helper'
+
+module Excalibur
+  describe Configuration do
+    describe '#new' do
+      context 'when creating a configuration without parameters' do
+        let(:config) { Configuration.new }
+
+        it 'should create a title' do
+          expect(config.title).to be_instance_of TruncateableContent
+        end
+
+        it 'should create a describe' do
+          expect(config.description).to be_instance_of TruncateableContent
+        end
+
+        it 'should create an empty meta tags hash' do
+          expect(config.meta_tags).to be_instance_of ::HashWithIndifferentAccess
+          expect(config.meta_tags).to be_empty
+        end
+      end
+
+      context 'when supplying parameters' do
+        let(:config) { Configuration.new('foo', 'bar', 'baz') }
+
+        it 'should set the right values' do
+          expect(config.title).to eq('foo')
+          expect(config.description).to eq('bar')
+          expect(config.meta_tags).to eq('baz')
+        end
+      end
+    end
+
+    describe '#merge!' do
+      context 'when trying to merge with the wrong type of object' do
+        let(:obj) { Configuration.new }
+
+        it 'should raise a TypeError' do
+          expect { obj.merge!('foo') }.to raise_error(TypeError, 'can only merge two Excalibur::Configuration objects')
+        end
+      end
+
+      context 'when merging two configurations' do
+        let(:obj_a) { Configuration.new(TruncateableContent.new, TruncateableContent.new) }
+        let(:obj_b) { Configuration.new(TruncateableContent.new, false, nil) }
+
+        context 'instance result' do
+          after do
+            obj_a.merge!(obj_b)
+          end
+
+          it 'should merge the instance variables' do
+            expect(obj_a).to receive(:merge_instance).exactly(3).times
+          end
+        end
+
+        context 'function result' do
+          it 'should return itself' do
+            expect(obj_a.merge!(obj_b)).to be_instance_of Configuration
+          end
+        end
+      end
+
+      describe 'when merging content merging' do
+        let(:a) { 'foobar' }
+        let(:b) { 'baz' }
+        let(:config) { Configuration.new(a) }
+        let(:new_config) { Configuration.new(b) }
+
+        before do
+          config.merge!(new_config)
+        end
+
+        context 'when the objects are different classes' do
+          context 'when the new object is nil' do
+            let(:new_config) { Configuration.new(nil) }
+
+            it 'should not change the config variable' do
+              expect( config.title ).to eq(config.title)
+            end
+          end
+
+          context 'when the new object is a value' do
+            let(:new_config) { Configuration.new(true) }
+
+            it 'should change the config variable' do
+              expect( config.title ).to eq(true)
+            end
+          end
+        end
+
+        context 'when the objects are the same class' do
+          context 'when merging two hashes' do
+            let(:a) { {foo: {bar: 'baz', other: 'old'}} }
+            let(:b) { {foo: {other: 'new'}} }
+
+            it 'should deep merge the two hashes' do
+              expect(config.title).to eq( { foo: {bar: 'baz', other: 'new'} } )
+            end
+          end
+
+          context 'when merging two TruncatableContent' do
+            let(:config) { Configuration.new }
+            let(:b) { TruncateableContent.new({foo: 'bar'}, {foo: 'bar'}, 'foobar') }
+
+            it 'should merge the two TruncatableContent' do
+              expect(config.title.content).to eq( b.content )
+              expect(config.title.options).to eq( b.options )
+              expect(config.title.combinator).to eq( b.combinator )
+            end
+          end
+
+          context 'when merging two strings' do
+            let(:a) { 'foo' }
+            let(:b) { 'bar' }
+
+            it 'should concatenate the two strings' do
+              expect(config.title).to eq('foobar')
+            end
+          end
+
+          context 'when merging something else' do
+            let(:a) { true }
+            let(:b) { false }
+
+            it 'should replace it' do
+              expect(config.title).to eq(false)
+            end
+          end
+        end
+      end
+    end
+
+    describe '#dup' do
+      it 'should create a duplicate of the object and the attributes' do
+        expect(Excalibur.configuration.title).to receive(:dup)
+        expect(Excalibur.configuration.description).to receive(:dup)
+        expect(Excalibur.configuration.meta_tags).to receive(:dup)
+
+        Excalibur.configuration.dup
+      end
+
+      it 'should create a duplicate of the object and the attributes' do
+        expect(Excalibur.configuration).to receive(:dup_instance).exactly(3).times
+
+        Excalibur.configuration.dup
+      end
+    end
+
+    describe '#set_meta_tag' do
+      let(:config) do
+        c = Configuration.new
+        c.meta_tags = ::HashWithIndifferentAccess.new( name: ::HashWithIndifferentAccess.new( description: 'old' ) )
+        c
+      end
+
+      it 'should overwrite a tag' do
+        config.set_meta_tag(:name, :description, 'Description content')
+
+        expect(config.meta_tags).to eq(::HashWithIndifferentAccess.new(
+                                           name: ::HashWithIndifferentAccess.new( description: 'Description content' ))
+                                    )
+      end
+
+      it 'should create a new tag type when required' do
+        config.set_meta_tag(:foo, :bar, 'baz')
+
+        expect(config.meta_tags).to have_key(:foo)
+        expect(config.meta_tags[:foo]).to have_key(:bar)
+        expect(config.meta_tags[:foo]).to be_instance_of ::HashWithIndifferentAccess
+        expect(config.meta_tags[:foo][:bar]).to eq('baz')
+      end
+    end
+
+    describe '#remove_meta_tag' do
+      let(:config) do
+        c = Configuration.new
+        c.meta_tags = {
+            name: {
+                description: 'content',
+                other: 'content'
+            },
+            foo: {
+                bar: 'baz'
+            }
+        }
+        c
+      end
+
+      context 'when the type still has values left' do
+        before do
+          config.remove_meta_tag(:name, :other)
+        end
+
+        it 'should have removed the name' do
+          expect(config.meta_tags[:name]).to_not have_key(:other)
+        end
+
+        it 'should still have the type' do
+          expect(config.meta_tags).to have_key(:name)
+        end
+      end
+
+      context 'when the type still has values left' do
+        before do
+          config.remove_meta_tag(:foo, :bar)
+        end
+
+        it 'should have removed the type' do
+          expect(config.meta_tags).to_not have_key(:foo)
+        end
+      end
+    end
+  end
+end

data/spec/lib/excalibur/decorator_spec.rb

@@ -0,0 +1,224 @@
+require 'spec_helper'
+
+module Excalibur
+  class Dummy; end
+  class DummyDecorator < Decorator; end
+
+  describe Decorator do
+    before do
+      Excalibur.reset
+      DummyDecorator.configuration = nil
+    end
+
+    after do
+      DummyDecorator.configuration = nil
+    end
+
+    describe '#new' do
+      context 'when creating it without options' do
+        let(:obj) { DummyDecorator.decorate(Dummy.new) }
+
+        it { expect(obj.context).to be_empty }
+        it { expect(obj.configuration).to be_present }
+      end
+
+      context 'when creating it with options' do
+        context 'when providing context' do
+          let(:obj) { DummyDecorator.decorate(Dummy.new, context: {foo: 'bar'}) }
+
+          it { expect(obj.context).to_not be_empty }
+          it { expect(obj.context).to eq({foo: 'bar'}) }
+        end
+
+        context 'when providing config' do
+          let(:config) { Configuration.new }
+          let(:obj) { DummyDecorator.decorate(Dummy.new, config: config) }
+
+          it 'should try and merge the configuration' do
+            expect_any_instance_of(Configuration).to receive(:merge!).with(config)
+
+            obj
+          end
+        end
+      end
+    end
+
+    context 'when configuring a decorator with mixed methods' do
+      before do
+        DummyDecorator.configuration = nil
+
+        class DummyDecorator < Decorator
+          excalibur_set_meta_tag(:foo, :bar, proc { |obj| 'content' })
+          excalibur_set_meta_tag(:name, :other, 'content')
+
+          excalibur_set_title_content(:prefix, 'Exc / ')
+          excalibur_set_title_content(:body, 'title body')
+          excalibur_set_title_option(:length, 42)
+          excalibur_set_title_combinator proc{ |obj| "result #{obj}" }
+
+          excalibur_set_description_content(:body, 'title body')
+          excalibur_set_description_option(:length, 42)
+          excalibur_set_description_combinator proc{ |obj| "result #{obj}" }
+        end
+      end
+
+      it { expect(DummyDecorator.configuration.meta_tags).to have_key(:name) }
+      it { expect(DummyDecorator.configuration.meta_tags[:name]).to have_key(:other) }
+      it { expect(DummyDecorator.configuration.meta_tags).to have_key(:foo) }
+      it { expect(DummyDecorator.configuration.meta_tags[:foo]).to have_key(:bar) }
+
+      it { expect(DummyDecorator.configuration.title.content[:prefix]).to eq 'Exc / ' }
+      it { expect(DummyDecorator.configuration.title.content[:body]).to eq 'title body' }
+      it { expect(DummyDecorator.configuration.title.options[:length]).to eq 42 }
+      it { expect(DummyDecorator.configuration.title.combinator).to be_instance_of Proc }
+      it { expect(DummyDecorator.configuration.title.combinator.call('foobar')).to eq('result foobar') }
+
+      it { expect(DummyDecorator.configuration.description.content[:body]).to eq 'title body' }
+      it { expect(DummyDecorator.configuration.description.options[:length]).to eq 42 }
+      it { expect(DummyDecorator.configuration.description.combinator).to be_instance_of Proc }
+      it { expect(DummyDecorator.configuration.description.combinator.call('foobar')).to eq('result foobar') }
+    end
+
+    describe '::excalibur_init' do
+      context 'when creating a decorator' do
+        context 'when setting the config without a value' do
+          before do
+            class DummyDecorator < Decorator
+              excalibur_init
+            end
+          end
+
+          it { expect(DummyDecorator.configuration).to be_present }
+          it { expect(DummyDecorator.configuration).to be_instance_of Configuration }
+        end
+
+        context 'when setting the config with a value' do
+          before do
+            class DummyDecorator < Decorator
+              excalibur_init true
+            end
+          end
+
+          it { expect(DummyDecorator.configuration).to be_present }
+          it { expect(DummyDecorator.configuration).to eq(true) }
+        end
+      end
+    end
+
+    describe '::configuration' do
+      it 'should duplicate the system wide configuration' do
+        expect( Excalibur.configuration ).to receive(:dup)
+
+        DummyDecorator.configuration
+      end
+
+      it 'should only duplicate the system wide configuration once' do
+        DummyDecorator.configuration
+
+        expect( Excalibur.configuration ).to_not receive(:dup)
+
+        DummyDecorator.configuration
+      end
+    end
+
+    describe '::excalibur_set' do
+      describe '_title' do
+        describe '_content' do
+          it 'should change the title content' do
+            expect {
+              DummyDecorator.excalibur_set_title_content(:foo, 'bar')
+            }.to change(DummyDecorator.configuration.title, :content).to(body: 'Excalibur', foo: 'bar')
+          end
+        end
+
+        describe '_option' do
+          it 'should change the title options' do
+            expect {
+              DummyDecorator.excalibur_set_title_option(:foo, 'bar')
+            }.to change(DummyDecorator.configuration.title, :options).to(length: 69, omission: '...', separator: '', foo: 'bar')
+          end
+        end
+
+        describe '_combinator' do
+          it 'should change the title combinator' do
+            expect {
+              DummyDecorator.excalibur_set_title_combinator(true)
+            }.to change(DummyDecorator.configuration.title, :combinator).to(true)
+          end
+        end
+      end
+
+      describe '_description' do
+        describe '_content' do
+          it 'should change the description content' do
+            expect {
+              DummyDecorator.excalibur_set_description_content(:foo, 'bar')
+            }.to change(DummyDecorator.configuration.description, :content).to(body: 'Excalibur; a worthy title for a gem about titles.', foo: 'bar')
+          end
+        end
+
+        describe '_option' do
+          it 'should change the description options' do
+            expect {
+              DummyDecorator.excalibur_set_description_option(:foo, 'bar')
+            }.to change(DummyDecorator.configuration.description, :options).to(length: 155, omission: '...', separator: ' ', foo: 'bar')
+          end
+        end
+
+        describe '_combinator' do
+          it 'should change the description combinator' do
+            expect {
+              DummyDecorator.excalibur_set_description_combinator(true)
+            }.to change(DummyDecorator.configuration.description, :combinator).to(true)
+          end
+        end
+      end
+
+      describe '_meta_tag' do
+        it 'should change the meta tags' do
+          expect(DummyDecorator.configuration).to receive(:set_meta_tag).with(:name, :description, 'foobar')
+
+          DummyDecorator.excalibur_set_meta_tag(:name, :description, 'foobar')
+        end
+      end
+    end
+
+    describe '#configuration' do
+      let(:obj) { DummyDecorator.decorate(Dummy.new) }
+
+      it "should duplicate the decorator's configuration" do
+        expect(obj.class.configuration).to receive(:dup)
+
+        obj.configuration
+      end
+
+      it 'should return a configuration' do
+        expect(obj.configuration).to be_instance_of Configuration
+      end
+    end
+
+    describe '#customize_configuration' do
+      let(:obj) { DummyDecorator.decorate(Dummy.new) }
+
+      it 'should merge the input with the configuration' do
+        expect(obj.configuration).to receive(:merge!).with('foobar')
+
+        obj.customize_configuration('foobar')
+      end
+    end
+
+    describe '#render_title' do
+      let(:obj) { DummyDecorator.decorate(Dummy.new) }
+
+      context 'when using the default settings' do
+        it { expect(obj.render_title).to eq('Excalibur') }
+
+        it 'should call to_s in the title' do
+          expect(obj.configuration.title).to receive(:to_s)
+
+          obj.render_title
+        end
+      end
+    end
+  end
+end