shortcode 0.0.4 → 0.1.0

data/README.md

@@ -28,19 +28,19 @@ $ gem install shortcode
 
 Shortcode can be used in one of two ways, the parser and transformer can be called seperatly or the `process` method can be used which performs both the parsing and transforming and returns the result.
 
-The former is good if you want to work with the intemediary hash returned by the parser
+The shorthand wraps up the above code into a single method call for convenience
 
 ```ruby
-parser = Shortcode::Parser.new
-transformer = Shortcode::Transformer.new
-parsed_hash = parser.parse("[quote]Hello World[/quote]")
-transformer.apply(parsed_hash)
+Shortcode.process("[quote]Hello World[/quote]")
 ```
 
-The shorthand wraps up the above code into a single method call for convenience
+The longer form is good if you want to work with the intemediary hash returned by the parser
 
 ```ruby
-Shortcode.process("[quote]Hello World[/quote]")
+parser = Shortcode::Parser.new
+transformer = Shortcode::Transformer.new
+parsed_hash = parser.parse("[quote]Hello World[/quote]")
+transformer.apply(parsed_hash)
 ```
 
 ### Configuration
@@ -90,6 +90,48 @@ Shortcodes can be nested inside other shortcodes, there are no limits imposed on
 
 Three templates would be required to support the above content, `[:collapsible_list, :item, :youtube]`. Each template is rendered in isolation and has no knowledge of parent or child elements.
 
+### Presenters
+
+Sometimes the data passed to the template from the shortcode it not enough. Lets say you want to render a gallery of images using id numbers of images stored in a database, e.g. `[gallery ids="1,2,3,4"]`. This is where presenters can help, they allow you to modify the `@content` and `@attributes` variables before they are sent to the template for rendering. Presenters are simple classes that define four methods. The class method `for` should return the name of the shortcode (as a symbol) it should be applied to. The classes `initialize` method received the `attributes` and `content` variables. Finally the class should define `content` and `attributes` methods.
+
+In a rails app you could return image records to the template using something like this:
+
+```ruby
+class CustomPrsenter
+
+  def self.for
+    :quote
+  end
+
+  def initialize(attributes, content)
+    @attributes = attributes
+    @content = content
+  end
+
+  def content
+    @content
+  end
+
+  def attributes
+    { images: images }
+  end
+
+  private
+
+    def images
+      @attributes.ids.split(',').collect { |n| Image.find(n) }
+    end
+end
+```
+
+#### Registering presenters
+
+To register a presenter simply call `Shortcode.register_presenter` passing the presenter class e.g.
+
+```ruby
+Shortcode.register_presenter(CustomPrsenter)
+```
+
 ## Contributing
 
 1. Fork it

data/lib/shortcode.rb

@@ -5,7 +5,9 @@ require 'erb'
 module Shortcode
   extend self
 
-  attr_accessor :configuration
+  attr_accessor :configuration, :presenters
+  @@presenters = {}
+
 
   def setup
     self.configuration ||= Configuration.new
@@ -16,6 +18,10 @@ module Shortcode
     transformer.apply(parser.parse(code))
   end
 
+  def register_presenter(presenter)
+    self.presenters[presenter.for.to_sym] = presenter
+  end
+
   private
 
     def parser
@@ -31,6 +37,7 @@ end
 require 'shortcode/version'
 require 'shortcode/configuration'
 require 'shortcode/parser'
+require 'shortcode/presenter'
 require 'shortcode/transformer'
 require 'shortcode/tag'
 require 'shortcode/exceptions'

data/lib/shortcode/presenter.rb

@@ -0,0 +1,27 @@
+class Shortcode::Presenter
+
+  def initialize(name, attributes, content)
+    @attributes = attributes
+    @content = content
+    initialize_custom_presenter(name)
+  end
+
+  def content
+    @content
+  end
+
+  def attributes
+    @attributes
+  end
+
+  private
+
+    def initialize_custom_presenter(name)
+      if Shortcode.presenters.has_key? name.to_sym
+        presenter   = Shortcode.presenters[name.to_sym].new(@attributes, @content)
+        @attributes = presenter.attributes
+        @content    = presenter.content
+      end
+    end
+
+end

data/lib/shortcode/tag.rb

@@ -1,14 +1,16 @@
 class Shortcode::Tag
 
-  def initialize(name, attributes=[])
-    @name = name.downcase
-    set_attributes attributes
+  def initialize(name, attributes=[], content='')
+    @name       = name.downcase
+    presenter   = Shortcode::Presenter.new name, set_attributes(attributes), content
+    @attributes = presenter.attributes
+    @content    = presenter.content
   end
 
   def set_attributes(attributes)
     hash = {}
     attributes.each { |o| hash[o[:key].to_sym] = o[:value] }
-    @attributes = hash
+    hash
   end
 
   def markup
@@ -18,8 +20,7 @@ class Shortcode::Tag
     raise Shortcode::TemplateNotFound, "Searched in:", template_files
   end
 
-  def wrap(content='')
-    @content = content
+  def render
     render_template
   end
 

data/lib/shortcode/transformer.rb

@@ -6,11 +6,11 @@ class Shortcode::Transformer < Parslet::Transform
     options:  subtree(:options),
     inner:    sequence(:inner),
     close:    simple(:name)
-  ) { Shortcode::Tag.new(name.to_s, options).wrap(inner.join) }
+  ) { Shortcode::Tag.new(name.to_s, options, inner.join).render }
   rule(
     open_close: simple(:name),
     options:    subtree(:options)
-  ) { Shortcode::Tag.new(name.to_s, options).wrap }
+  ) { Shortcode::Tag.new(name.to_s, options).render }
 
   rule(body: sequence(:strings)) { strings.join }
 end

data/lib/shortcode/version.rb

@@ -1,3 +1,3 @@
 module Shortcode
-  VERSION = "0.0.4"
+  VERSION = "0.1.0"
 end

data/spec/presenter_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+require 'parslet/rig/rspec'
+require 'pp'
+
+class MyPrsenter
+
+  def self.for
+    :quote
+  end
+
+  def initialize(attributes, content)
+    @attributes = attributes
+    @content = content
+  end
+
+  def content
+    @content
+  end
+
+  def attributes
+    { title: "my custom title" }
+  end
+end
+
+describe Shortcode::Presenter do
+
+  let(:simple_quote)        { load_fixture :simple_quote }
+  let(:simple_quote_output) { load_fixture :simple_quote_presenter_output, :html }
+
+  describe "using a custom presenter" do
+
+    before do
+      Shortcode.register_presenter MyPrsenter
+    end
+
+    it "uses the custome attributes" do
+      Shortcode.process(simple_quote).gsub("\n",'').should == simple_quote_output.gsub("\n",'')
+    end
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -7,6 +7,7 @@ RSpec.configure do |config|
   config.order = "random"
 
   config.before(:each) do
+    Shortcode.presenters = {}
     Shortcode.setup do |config|
       config.template_parser = :haml
       config.template_path = File.join File.dirname(__FILE__), "support/templates/haml"

data/spec/support/fixtures/simple_quote_presenter_output.html

@@ -0,0 +1,6 @@
+<blockquote>
+<p class='quotation'>hello</p>
+<p class='citation'>
+<span class='position'>my custom title</span>
+</p>
+</blockquote>

data/spec/tag_spec.rb

@@ -7,7 +7,7 @@ describe Shortcode::Tag do
     let(:tag) { Shortcode::Tag.new('doesnt_exist') }
 
     it "raises a TemplateNotFound error when the file doesn't exists" do
-      expect { tag.wrap }.to raise_error(Shortcode::TemplateNotFound)
+      expect { tag.render }.to raise_error(Shortcode::TemplateNotFound)
     end
 
   end
@@ -23,7 +23,7 @@ describe Shortcode::Tag do
     end
 
     it "raises a TemplateNotFound error when the file doesn't exists" do
-      expect { tag.wrap }.to raise_error(Shortcode::TemplateParserNotSupported)
+      expect { tag.render }.to raise_error(Shortcode::TemplateParserNotSupported)
     end
 
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shortcode
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -108,12 +108,14 @@ files:
 - lib/shortcode/configuration.rb
 - lib/shortcode/exceptions.rb
 - lib/shortcode/parser.rb
+- lib/shortcode/presenter.rb
 - lib/shortcode/tag.rb
 - lib/shortcode/transformer.rb
 - lib/shortcode/version.rb
 - shortcode.gemspec
 - spec/parser_spec.rb
 - spec/performance_spec.rb
+- spec/presenter_spec.rb
 - spec/shortcode_spec.rb
 - spec/spec_helper.rb
 - spec/support/fixtures.rb
@@ -128,6 +130,7 @@ files:
 - spec/support/fixtures/simple_list_output.html
 - spec/support/fixtures/simple_quote.txt
 - spec/support/fixtures/simple_quote_output.html
+- spec/support/fixtures/simple_quote_presenter_output.html
 - spec/support/fixtures/timeline_event.txt
 - spec/support/fixtures/timeline_event_output.html
 - spec/support/fixtures/timeline_info.txt
@@ -171,6 +174,7 @@ summary: Gem for parsing wordpress style shortcodes
 test_files:
 - spec/parser_spec.rb
 - spec/performance_spec.rb
+- spec/presenter_spec.rb
 - spec/shortcode_spec.rb
 - spec/spec_helper.rb
 - spec/support/fixtures.rb
@@ -185,6 +189,7 @@ test_files:
 - spec/support/fixtures/simple_list_output.html
 - spec/support/fixtures/simple_quote.txt
 - spec/support/fixtures/simple_quote_output.html
+- spec/support/fixtures/simple_quote_presenter_output.html
 - spec/support/fixtures/timeline_event.txt
 - spec/support/fixtures/timeline_event_output.html
 - spec/support/fixtures/timeline_info.txt