RubyGems - excalibur - Versions diffs - 0.0.2 - Mend

excalibur 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (30) hide show

checksums.yaml +7 -0
data/.gitignore +22 -0
data/.rspec +3 -0
data/Gemfile +4 -0
data/LICENSE.txt +22 -0
data/README.md +162 -0
data/Rakefile +2 -0
data/excalibur.gemspec +32 -0
data/lib/excalibur/configuration.rb +77 -0
data/lib/excalibur/decorator.rb +55 -0
data/lib/excalibur/duplicator.rb +19 -0
data/lib/excalibur/railtie.rb +15 -0
data/lib/excalibur/truncatable_content.rb +82 -0
data/lib/excalibur/version.rb +4 -0
data/lib/excalibur/view_helpers.rb +59 -0
data/lib/excalibur.rb +91 -0
data/lib/generators/excalibur/decorator_generator.rb +18 -0
data/lib/generators/excalibur/install_generator.rb +18 -0
data/lib/generators/templates/decorator.rb +75 -0
data/lib/generators/templates/excalibur.rb +151 -0
data/spec/lib/excalibur/configuration_spec.rb +215 -0
data/spec/lib/excalibur/decorator_spec.rb +224 -0
data/spec/lib/excalibur/duplicator_spec.rb +49 -0
data/spec/lib/excalibur/truncatable_content_spec.rb +192 -0
data/spec/lib/excalibur/view_helper_spec.rb +87 -0
data/spec/lib/excalibur_spec.rb +85 -0
data/spec/lib/generators/excalibur/decorator_generator_spec.rb +28 -0
data/spec/lib/generators/excalibur/install_generator_spec.rb +30 -0
data/spec/spec_helper.rb +80 -0
metadata +219 -0

checksums.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3a2f5e3f336d2c2b9cd05b21f50387fca47779dd
+  data.tar.gz: ef5f966e21a9f27b7c23db57533d5c6f6dece688
+SHA512:
+  metadata.gz: 51506887560a0d4771933ef36713ca814c96ed4c2c12fc2ba31cdafd214a7b982c15d0df47a9d33c70bef15e5f03bc50bd5f6086bc55aa1439b5b3a803eda9c3
+  data.tar.gz: eefbce53136c980ee7be535160ed801efc794052bb84686bfcde9152bc35319af85034fc059b19cba6ad9f2383db0d657a28cea935eea4ea6a0896cd62c3623a

data/.gitignore ADDED Viewed

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec ADDED Viewed

@@ -0,0 +1,3 @@
+--color
+--warnings
+--require spec_helper

data/Gemfile ADDED Viewed

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+# Specify your gem's dependencies in excalibur.gemspec
+gemspec

data/LICENSE.txt ADDED Viewed

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Joost (yopefonic) Elfering
+MIT License
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md ADDED Viewed

@@ -0,0 +1,162 @@
+# Excalibur
+Excalibur is a SEO gem for [Ruby on Rails](rubyonrails.org) and helps you to
+set the title and meta tags for you site overall and per page. Unlike other
+options like [meta-tags](https://github.com/kpumuk/meta-tags) and
+[meta_magic](https://github.com/lassebunk/metamagic) Excalibur focusses on
+providing an object based DSL to turn the objects you are presenting on the
+page into SEO related tags in the head.
+## Installation
+Add this line to your application's Gemfile:
+    gem 'excalibur'
+And then execute:
+    $ bundle
+Or install it yourself as:
+    $ gem install excalibur
+### Initialize
+To add an initializer to your application execute:
+    rails generate excalibur:install
+The initializer is documented with the possible options you have to customize
+your default setup of Excalibur.
+## Usage
+### Layout
+In your layout you can replace your title tag with the Excalibur render title
+method:
+```erb
+<%= render_title_tag %>
+```
+To render meta tags place this between the ```<head>``` tags of your layout:
+```erb
+<%= render_meta_tags %>
+```
+### Views
+As excalibur believes in separation of concerns passing the current object you
+want to render title and meta tags for is done in the view.
+```erb
+<% entitle @your_object %>
+```
+The object your passing into the entitle method will search for a Excalibur
+decorator. You can find out more on how to create them in the
+[decorators](#decorators) section.
+To modify the configuration in the view you can pass an option into the
+```entitle``` method and pass it a new excalibur config object. Read more
+about creating your own in the [configurations](#configurations) section. It
+will try and merge the supplied configuration with the one specified in the
+decorator. Because of this you need to supply it with the same type of object
+to make that possible.
+Notably the second argument of ```entitle``` can also pass other
+[Draper](https://github.com/drapergem/draper) related options like draper's
+context.
+```ruby
+entitle @your_object, config: @custom_config
+```
+### Decorators
+The decorators are what turns your object into data that can be used for the
+meta tags and the title. So without a decorator for an object the view helper
+``` entitle ``` will have no use at all.
+To scaffold a decorator execute:
+    rails generate excalibur:install [class name]
+A detailed description on how the decorators work can be found in the newly
+created decorator class. As a side note the ```Excalibur::Decorator``` is a
+subclass of ```Draper::Decorator``` and comes with the free functionality
+provided by [Draper](https://github.com/drapergem/draper). Have fun!
+### Configurations
+**WARNING:** handle with care!
+So you want to roll your own configuration, awesome!
+```Excalibur::Configuration``` can be initialized with 3 arguments that are
+the title, description and meta tags.
+Both title and description are an instance of
+```Excalibur::TruncateableContent``` but as long as you make sure a
+```.to_s``` with one argument is present for the object you put in there it is
+fine. The object passed to it is either a decorated object when it is set or a
+blank decorated object.
+```Excalibur::TruncateableContent``` can be of course used on it's own when
+creating a new configuration. It also takes 3 arguments. Two hashes; the first
+for the content and the second for options. On it's own the
+TruncateableContent does not do a lot but the third argument takes a
+```Proc``` that is called with the decorator on render. By default the proc
+combines the content according to the content and the options supplied in the
+first two hashes. But of course you can supply your own. Setting them to empty
+hashes or nil will work and when merged the default will keep in place.
+The meta tags, and third argument of the configuration is a structured hash
+with two layers. The first layer is the global type of meta tag and the second
+contains the sub-types with the content.
+so a meta tag like this:
+```html
+<meta name="description" content="Excalibur is cool" />
+```
+you need a hash like this:
+```ruby
+{
+  name: {
+    description: 'Excalibur is cool'
+  }
+}
+```
+For an OpenGraph tag this would be something like:
+```html
+<meta property="og:description" content="Excalibur is cool" />
+```
+```ruby
+{
+  property: {
+    'og:description' => 'Excalibur is cool'
+  }
+}
+```
+The content of the meta_tags can be defined as an Array of items or just a
+single one. The item itself can be any type of variable that render as a
+string on a page. It can also be a ```Proc``` that will be passed the
+decorated object just like the title and description. This Proc can also
+result in an array.
+## Contributing
+1. Fork it ( https://github.com/yopefonic/excalibur/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ require "bundler/gem_tasks"
2	+

data/excalibur.gemspec ADDED Viewed

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'excalibur/version'
+Gem::Specification.new do |spec|
+  spec.name          = 'excalibur'
+  spec.version       = Excalibur::VERSION
+  spec.authors       = ['Joost Elfering']
+  spec.email         = ['yopefonic@gmail.com']
+  spec.summary       = %q{helper gem to set page title and meta tags in a rails app}
+  spec.description   = %q{helper gem for rails apps to set the title and meta tags for a page. The helper can take custom input per page, objects that use decorator to determine the tags or an application wide configurable default.}
+  spec.homepage      = 'https://github.com/yopefonic/excalibur'
+  spec.license       = 'MIT'
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 1.9.3'
+  spec.add_dependency 'rails', '~> 3'
+  spec.add_dependency 'draper', '~> 1.3', '>= 1.3.0'
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'rake', '~> 10.3'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'generator_spec', '~> 0.9', '>= 0.9.2'
+  spec.add_development_dependency 'simplecov', '~> 0.8', '>= 0.8.0'
+  spec.add_development_dependency 'pry', '~> 0.10', '>= 0.10.1'
+end

data/lib/excalibur/configuration.rb ADDED Viewed

@@ -0,0 +1,77 @@
+module Excalibur
+  # the Configuration class is responsible for holding the configurable data
+  # and logic that will be passed down
+  class Configuration
+    include Duplicator
+    attr_accessor :title
+    attr_accessor :description
+    attr_accessor :meta_tags
+    def initialize(
+        title = TruncateableContent.new,
+        description = TruncateableContent.new,
+        meta_tags = ::HashWithIndifferentAccess.new({}))
+      @title = title
+      @description = description
+      @meta_tags = meta_tags
+    end
+    def merge!(obj)
+      if obj.is_a? Configuration
+        @title = merge_instance(@title, obj.title)
+        @description = merge_instance(@description, obj.description)
+        @meta_tags = merge_instance(@meta_tags, obj.meta_tags)
+        self
+      else
+        fail(TypeError.new(true),
+             'can only merge two Excalibur::Configuration objects')
+      end
+    end
+    def dup
+      self.class.new(
+          dup_instance(@title),
+          dup_instance(@description.dup),
+          dup_instance(@meta_tags.dup))
+    end
+    def set_meta_tag(type, name, value = nil)
+      if @meta_tags[type].nil?
+        @meta_tags[type] = ::HashWithIndifferentAccess.new
+      end
+      @meta_tags[type][name] = value
+    end
+    def remove_meta_tag(type, name)
+      @meta_tags[type].delete(name) if @meta_tags[type].present?
+      @meta_tags.delete(type) if @meta_tags[type].empty?
+    end
+    private
+    def merge_instance(old, new)
+      if old.is_a? new.class
+        merge_content(old, new)
+      elsif !new.nil?
+        new
+      else
+        old
+      end
+    end
+    def merge_content(old, new)
+      if old.is_a? ::Hash
+        old.deep_merge!(new)
+      elsif old.is_a? TruncateableContent
+        old.merge!(new)
+      elsif old.is_a? ::String
+        old + new
+      else
+        new
+      end
+    end
+  end
+end

data/lib/excalibur/decorator.rb ADDED Viewed

@@ -0,0 +1,55 @@
+require 'draper'
+module Excalibur
+  # the Decorator class helps content to be derived from application base
+  # object and turn them into Excalibur titles and meta tags. It's main
+  # responsibilities are to make local classes configurable and it acts as a
+  # connector between the application's objects and Excalibur.
+  class Decorator < ::Draper::Decorator
+    delegate_all
+    attr_accessor :custom_configuration
+    class << self
+      attr_writer :configuration
+      def excalibur_init(config = configuration)
+        @configuration = config
+      end
+      def configuration
+        @configuration ||= ::Excalibur.configuration.dup
+      end
+      def method_missing(meth, *args)
+        if meth.to_s =~ /^excalibur_set_(title|description+)_(content|option|combinator+)$/
+          configuration.send($1).send("update_#{$2}", *args)
+        else
+          super
+        end
+      end
+      def excalibur_set_meta_tag(type, name, value = nil)
+        configuration.set_meta_tag(type, name, value)
+      end
+    end
+    def initialize(object, options = {})
+      configuration.merge!(options.delete(:config)) if options.key?(:config)
+      super(object, options)
+    end
+    def configuration
+      @custom_configuration ||= self.class.configuration.dup
+    end
+    def customize_configuration(config)
+      configuration.merge!(config)
+    end
+    def render_title(obj = self)
+      configuration.title.to_s(obj) if configuration.title.present?
+    end
+  end
+end

data/lib/excalibur/duplicator.rb ADDED Viewed

@@ -0,0 +1,19 @@
+module Excalibur
+  # the Duplicator module helps in making sure duplication of nested objects
+  # functions properly and is used by the class Configuration and the class
+  # TruncableContent
+  module Duplicator
+    # duplicates TruncatableContent and calls the deep_dup method on any form
+    # of Hash. Otherwise return the object as not all objects do not need to
+    # be duplicated.
+    def dup_instance(obj)
+      if obj.is_a?(TruncateableContent)
+        obj.dup
+      elsif obj.is_a?(Hash)
+        obj.deep_dup
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/excalibur/railtie.rb ADDED Viewed

@@ -0,0 +1,15 @@
+require 'excalibur/view_helpers'
+module Excalibur
+  # ties the ViewHelpers into Rails and allows them to be used in the views
+  class Railtie < Rails::Railtie
+    initializer 'excalibur.view_helpers' do
+      ActionView::Base.send :include, ViewHelpers
+    end
+    generators do
+      require 'generators/excalibur/install_generator'
+      require 'generators/excalibur/decorator_generator'
+    end
+  end
+end

data/lib/excalibur/truncatable_content.rb ADDED Viewed

@@ -0,0 +1,82 @@
+module Excalibur
+  # The TruncateableContent class is responsible for text content that is
+  # constrained in length due to SEO specifications. Mainly used for title
+  # and meta description tags this class facilitates the creation and proper
+  # rendering of the content. A prefix/body/suffix data structure is used so
+  # that only the body is truncated without having an effect on the branding
+  # that is put before and/or after the body.
+  class TruncateableContent
+    include Duplicator
+    attr_accessor :content
+    attr_accessor :options
+    attr_accessor :combinator
+    def initialize(content = {}, options = {}, combinator = nil)
+      @content = ::HashWithIndifferentAccess.new(content)
+      @options = ::HashWithIndifferentAccess.new(options)
+      @combinator = combinator
+    end
+    def can_merge?(obj)
+      obj.is_a? TruncateableContent
+    end
+    def merge!(obj)
+      if can_merge?(obj)
+        @content.merge!(obj.content)
+        @options.merge!(obj.options)
+        @combinator = obj.combinator unless obj.combinator.nil?
+        self
+      else
+        fail(TypeError.new(true),
+             'can only merge two Excalibur::TruncateableContent objects')
+      end
+    end
+    def dup
+      self.class.new(
+          dup_instance(@content),
+          dup_instance(@options),
+          dup_instance(@combinator)
+      )
+    end
+    def get_content(key, obj = nil)
+      if @content[key].instance_of?(Proc)
+        @content[key].call(obj)
+      elsif @content[key].nil?
+        ''
+      else
+        @content[key]
+      end
+    end
+    def update_content(key, value = nil)
+      @content[key] = value
+    end
+    def update_option(key, value = nil)
+      @options[key] = value
+    end
+    def update_combinator(value = nil)
+      @combinator = value
+    end
+    def render_long(obj = nil)
+      @content.map { |key, _value| get_content(key, obj).to_s }.inject(:+).to_s
+    end
+    def render_short(obj = nil)
+      if @combinator.instance_of? Proc
+        @combinator.call(obj)
+      else
+        render_long(obj)
+      end
+    end
+    alias_method :to_s, :render_short
+  end
+end

data/lib/excalibur/version.rb ADDED Viewed

@@ -0,0 +1,4 @@
+# setting version number for the Excalibur gem
+module Excalibur
+  VERSION = '0.0.2'
+end

data/lib/excalibur/view_helpers.rb ADDED Viewed

@@ -0,0 +1,59 @@
+module Excalibur
+  # the ViewHelpers module contains the methods to access Excalibur from the
+  # view. Most commonly placed in the view templates and the application Layout
+  module ViewHelpers
+    def entitle(object, options = {})
+      @excalibur_subject = excalibur_decorate_subject(object, options)
+    end
+    def render_title_tag
+      content_tag :title, excalibur_subject.render_title
+    end
+    def render_meta_tags
+      result = ''
+      excalibur_subject.configuration.meta_tags.each do |type_name, value|
+        value.each do |type_value, contents|
+          next if contents.nil?
+          contents = render_meta_content(contents)
+          contents = [contents] unless contents.is_a?(Array)
+          contents.each do |content|
+            result << tag(
+                :meta,
+                type_name => type_value,
+                content: content
+            )
+          end
+        end
+      end
+      result.html_safe
+    end
+    private
+    def render_meta_content(content)
+      if content.is_a? Proc
+        content.call(excalibur_subject)
+      else
+        content
+      end
+    end
+    def excalibur_subject
+      @excalibur_subject ||= new_blank_excalibur_subject
+    end
+    def new_blank_excalibur_subject
+      ::Excalibur::Decorator.decorate(true)
+    end
+    def excalibur_decorate_subject(object, options = {})
+      Object.const_get(
+          "::Excalibur::#{object.class.name}Decorator"
+      ).decorate(object, options)
+    end
+  end
+end

data/lib/excalibur.rb ADDED Viewed

@@ -0,0 +1,91 @@
+require 'excalibur/version'
+require 'active_support/all'
+require 'excalibur/decorator'
+require 'excalibur/duplicator'
+require 'excalibur/configuration'
+require 'excalibur/truncatable_content'
+require 'excalibur/railtie' if defined?(Rails)
+# the Excalibur gem helps you to decorate a rails app with proper title and
+# meta tags for every page. It does this by providing default configuration
+# options, object based decorators for customization per object type and
+# helpers to put in on the page.
+module Excalibur
+  class << self
+    attr_writer :configuration
+    def configuration
+      @configuration ||= new_default_configuration
+    end
+    def reset
+      @configuration = new_default_configuration
+    end
+    # defines the gem default
+    def new_default_configuration
+      Configuration.new(
+          new_default_title,
+          new_default_description,
+          new_default_meta_tags
+      )
+    end
+    def configure
+      yield(configuration)
+    end
+    private
+    def new_default_title
+      TruncateableContent.new(
+          { body: 'Excalibur' },
+          { length: 69, omission: '...', separator: '' },
+          proc do |obj|
+            if obj.present?
+              t = obj.configuration.title
+              length  = t.options[:length]
+              length -= t.get_content(:prefix, obj).length
+              length -= t.get_content(:suffix, obj).length
+              res  = t.get_content(:prefix, obj)
+              res += t.get_content(:body, obj).truncate(length, t.options)
+              res +  t.get_content(:suffix, obj)
+            end
+          end
+      )
+    end
+    def new_default_description
+      TruncateableContent.new(
+          { body: 'Excalibur; a worthy title for a gem about titles.' },
+          { length: 155, omission: '...', separator: ' ' },
+          proc do |obj|
+            if obj.present?
+              d = obj.configuration.description
+              length  = d.options[:length]
+              length -= d.get_content(:prefix, obj).length
+              length -= d.get_content(:suffix, obj).length
+              res  = d.get_content(:prefix, obj)
+              res += d.get_content(:body, obj).truncate(length, d.options)
+              res +  d.get_content(:suffix, obj)
+            end
+          end
+      )
+    end
+    def new_default_meta_tags
+      ::HashWithIndifferentAccess.new(
+          name: ::HashWithIndifferentAccess.new(
+              description: proc do |obj|
+                obj.configuration.description.to_s(obj)
+              end,
+              viewport: 'width=device-width, initial-scale=1'
+          )
+      )
+    end
+  end
+end

data/lib/generators/excalibur/decorator_generator.rb ADDED Viewed

@@ -0,0 +1,18 @@
+require 'rails/generators/base'
+module Excalibur
+  module Generators
+    # allows you to use rails generate to create a new scaffolded decorator
+    # for a application native class.
+    # rails g excalibur:decorator [class_name]
+    class DecoratorGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('../../templates', __FILE__)
+      desc 'Creates a Excalibur decorator.'
+      def create_decorator
+        template 'decorator.rb', "app/decorators/excalibur/#{file_name}_decorator.rb"
+      end
+    end
+  end
+end