RubyGems - excalibur - Versions diffs - 0.0.2 - Mend

excalibur 0.0.2

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