shortcode 0.0.1 → 0.0.2

data/README.md

@@ -1,45 +1,94 @@
 # Shortcode
 
-A ruby gem for parsing Wordpress style shortcodes. The gem uses a PEG (Parsing Expression Grammar) parser rather than using regular expressions so its easier to understand, test and extend.
+A ruby gem for parsing Wordpress style shortcodes. The gem uses a [PEG](http://en.wikipedia.org/wiki/Parsing_expression_grammar) (Parsing Expression Grammar) parser rather than using regular expressions so its easier to understand, test and extend.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'shortcode'
+```ruby
+gem 'shortcode'
+```
 
 And then execute:
 
-    $ bundle
+```
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install shortcode
+```
+$ gem install shortcode
+```
 
 ## Usage
 
-Example usage
+### Example
 
-    parser = Shortcode::Parser.new
-    transformer = Shortcode::Transformer.new
-    transformer.apply(parser.parse("[quote]Hello World[/quote]"))
+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.
 
-Configuration
+The former is good if you want to work with the intemediary hash returned by the parser
 
-    Shortcode.setup do |config|
+```ruby
+parser = Shortcode::Parser.new
+transformer = Shortcode::Transformer.new
+parsed_hash = parser.parse("[quote]Hello World[/quote]")
+transformer.apply(parsed_hash)
+```
 
-      # the template parser to use
-      config.template_parser = :haml # :erb or :haml supported, :haml is default
+The shorthand wraps up the above code into a single method call for convenience
 
-       # location of the template files
-      config.template_path = "support/templates/haml"
+```ruby
+Shortcode.process("[quote]Hello World[/quote]")
+```
 
-      # a list of block tags to support e.g. [quote]Hello World[/quote]
-      config.block_tags = [:quote, :collapsible_list, :item, :timeline_person]
+### Configuration
 
-      # a list of self closing tags to support e.g. [gallery]
-      config.self_closing_tags = [:timeline_event, :timeline_info]
-    end
+```ruby
+Shortcode.setup do |config|
+
+  # the template parser to use
+  config.template_parser = :haml # :erb or :haml supported, :haml is default
+
+   # location of the template files
+  config.template_path = "support/templates/haml"
+
+  # a list of block tags to support e.g. [quote]Hello World[/quote]
+  config.block_tags = [:quote]
+
+  # a list of self closing tags to support e.g. [youtube id="12345"]
+  config.self_closing_tags = [:youtube]
+end
+```
+
+### Templates
+
+Each shortcode tag needs a template file to translate the shortcode into html. Templates can be written in HAML or erb and work in
+a similar way to views in Rails. The main content of a tag is passed via the instance variable `@content`. Any attributes defined on a tag are passed in via an `@attributes` hash, shortcodes can have any number of attributes. For instance a quote shortcode might look like this:
+
+    [quote author="Homer Simpson"]Doh![/quote]
+
+And the haml template to render the shortcode
+
+```haml
+%blockquote
+  %p.quotation= @content
+  -if @attributes[:author]
+    %p.citation
+      %span.author= @attributes[:author]
+```
+
+Shortcodes can be nested inside other shortcodes, there are no limits imposed on the nesting depth. This can be useful when creating complex content such as a collapsible list that can have any content inside each element. We could have the following shortcodes
+
+    [collapsible_list]
+      [item]
+        [youtube id="12345"]
+      [/item]
+      [item]Hellow World[/item]
+    [/collapsible_list]
+
+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.
 
 ## Contributing
 

data/lib/shortcode.rb

@@ -15,16 +15,30 @@ module Shortcode
 
   # Set the supported block_tags
   mattr_accessor :block_tags
-  @@block_tags = [:quote, :collapsible_list, :item, :timeline_person]
+  @@block_tags = [:quote]
 
   # Set the supported self_closing_tags
   mattr_accessor :self_closing_tags
-  @@self_closing_tags = [:timeline_event, :timeline_info]
+  @@self_closing_tags = [:youtube]
 
   def self.setup
     yield self
   end
 
+  def self.process(code)
+    transformer.apply(parser.parse(code))
+  end
+
+  private
+
+    def self.parser
+      @@parser ||= Shortcode::Parser.new
+    end
+
+    def self.transformer
+      @@transformer ||= Shortcode::Transformer.new
+    end
+
 end
 
 require 'shortcode/version'

data/lib/shortcode/tag.rb

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

data/lib/shortcode/version.rb

@@ -1,3 +1,3 @@
 module Shortcode
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/shortcode.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["jamie@kernowsoul.com"]
   spec.description   = "Gem for parsing wordpress style shortcodes"
   spec.summary       = "Gem for parsing wordpress style shortcodes"
-  spec.homepage      = ""
+  spec.homepage      = "https://github.com/kernow/shortcode"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files`.split($/)

data/spec/shortcode_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+require 'parslet/rig/rspec'
+require 'pp'
+
+describe Shortcode do
+
+  let(:simple_quote)        { load_fixture :simple_quote }
+  let(:simple_quote_output) { load_fixture :simple_quote_output, :html }
+
+  context "simple_quote" do
+
+    it "converts into html" do
+      Shortcode.process(simple_quote).should == simple_quote_output
+    end
+
+  end
+
+  context "erb templates" do
+
+    before(:each) do
+      Shortcode.setup do |config|
+        config.template_parser = :erb
+        config.template_path = File.join File.dirname(__FILE__), "support/templates/erb"
+      end
+    end
+
+    it "converts into html" do
+      Shortcode.process(simple_quote).gsub("\n",'').should == simple_quote_output.gsub("\n",'')
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -10,6 +10,8 @@ RSpec.configure do |config|
     Shortcode.setup do |config|
       config.template_parser = :haml
       config.template_path = File.join File.dirname(__FILE__), "support/templates/haml"
+      config.block_tags = [:quote, :collapsible_list, :item, :timeline_person]
+      config.self_closing_tags = [:timeline_event, :timeline_info]
     end
   end
 end

data/spec/support/templates/erb/quote.html.erb

@@ -1,11 +1,11 @@
 <blockquote>
-<p class='quotation'><%= @text %></p>
-<% if @options[:author] || @options[:title] %>
+<p class='quotation'><%= @content %></p>
+<% if @attributes[:author] || @attributes[:title] %>
 <p class='citation'>
-<% if @options[:author] %>
-<span class='author'><%= @options[:author] %></span>
+<% if @attributes[:author] %>
+<span class='author'><%= @attributes[:author] %></span>
 <% end %>
-<% if @options[:title] <% end %><span class='position'><%= @options[:title] %></span>
+<% if @attributes[:title] <% end %><span class='position'><%= @attributes[:title] %></span>
 <% end %>
 </p>
 <% end %>

data/spec/support/templates/haml/collapsible_list.html.haml

@@ -1,2 +1,2 @@
 .collapsible
-  = @text
+  = @content

data/spec/support/templates/haml/item.html.haml

@@ -1,3 +1,3 @@
 %section
-  %h5= @options[:title]
-  %div= @text
+  %h5= @attributes[:title]
+  %div= @content

data/spec/support/templates/haml/quote.html.haml

@@ -1,8 +1,8 @@
 %blockquote
-  %p.quotation= @text
-  -if @options[:author] || @options[:title]
+  %p.quotation= @content
+  -if @attributes[:author] || @attributes[:title]
     %p.citation
-      -if @options[:author]
-        %span.author= @options[:author]
-      -if @options[:title]
-        %span.position= @options[:title]
+      -if @attributes[:author]
+        %span.author= @attributes[:author]
+      -if @attributes[:title]
+        %span.position= @attributes[:title]

data/spec/support/templates/haml/timeline_event.html.haml

@@ -3,8 +3,8 @@
     %tbody
       %tr
         %th{scope: :row}
-          = @options[:date]
+          = @attributes[:date]
         %td.event
-          %span.description= @options[:title]
-          -if @options[:link]
-            %a.read_more{href: @options[:link]} Read More
+          %span.description= @attributes[:title]
+          -if @attributes[:link]
+            %a.read_more{href: @attributes[:link]} Read More

data/spec/support/templates/haml/timeline_info.html.haml

@@ -3,6 +3,6 @@
     %tbody
       %tr
         %th{scope: :row}
-          = @options[:date]
+          = @attributes[:date]
         %td.information
-          %p= @options[:title]
+          %p= @attributes[:title]

data/spec/support/templates/haml/timeline_person.html.haml

@@ -3,13 +3,13 @@
     %tbody
       %tr
         %th{scope: :row}
-          = @options[:date]
+          = @attributes[:date]
         %td.team_news
-          %img{src: @options[:image]}
-          %h4= @options[:title]
-          %span.name= @options[:name]
-          %span.position= @options[:position]
-          -if @options[:link]
-            %a.read_more{href: @options[:link]} View Profile
+          %img{src: @attributes[:image]}
+          %h4= @attributes[:title]
+          %span.name= @attributes[:name]
+          %span.position= @attributes[:position]
+          -if @attributes[:link]
+            %a.read_more{href: @attributes[:link]} View Profile
           .description
-            %p= @text
+            %p= @content

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shortcode
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-05 00:00:00.000000000 Z
+date: 2013-08-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parslet
@@ -128,6 +128,7 @@ files:
 - lib/shortcode/version.rb
 - shortcode.gemspec
 - spec/parser_spec.rb
+- spec/shortcode_spec.rb
 - spec/spec_helper.rb
 - spec/support/fixtures.rb
 - spec/support/fixtures/complex_snippet.txt
@@ -155,7 +156,7 @@ files:
 - spec/support/templates/haml/timeline_person.html.haml
 - spec/tag_spec.rb
 - spec/transformer_spec.rb
-homepage: ''
+homepage: https://github.com/kernow/shortcode
 licenses:
 - MIT
 post_install_message: 
@@ -182,6 +183,7 @@ specification_version: 3
 summary: Gem for parsing wordpress style shortcodes
 test_files:
 - spec/parser_spec.rb
+- spec/shortcode_spec.rb
 - spec/spec_helper.rb
 - spec/support/fixtures.rb
 - spec/support/fixtures/complex_snippet.txt