shortcode 0.2.0 → 0.3.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    shortcode (0.1.2)
+    shortcode (0.3.0)
       haml (~> 4.0)
       parslet (= 1.6.0)
 

data/README.md

@@ -42,9 +42,13 @@ 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
+   # location of the template files, default is "app/views/shortcode_templates"
   config.template_path = "support/templates/haml"
 
+   # a hash of templates passed as strings, if this is set it overrides the
+   # above template_path option. The default is nil
+  config.templates = { gallery: 'template code' }
+
   # a list of block tags to support e.g. [quote]Hello World[/quote]
   config.block_tags = [:quote]
 
@@ -58,7 +62,7 @@ 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
+Each shortcode tag needs a template in order to translate the shortcode into html (or other output). 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]
@@ -73,7 +77,7 @@ And the haml template to render the shortcode
       %span.author= @attributes[:author]
 ```
 
-If using the gem within a Rails project you can use the Rails helper methods within template files.
+If using the gem within a Rails project you can use the Rails helper methods within templates.
 
 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
 
@@ -86,6 +90,28 @@ 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.
 
+There are 2 ways templates can be used with Shortcode, the default it to load templates from the file system, an alternative approach is to pass templates to the setup
+block as strings.
+
+#### Templates loaded from the file system
+
+Simply create files with the extension or .haml or .erb with a filename the same as the shortcode tag, e.g. gallery.haml would render a [gallery] shortcode tag. The default
+location for template files is `app/views/shortcode_templates`, if you want to load tempaltes from a different location use the `template_path` config option.
+
+#### Templates set as configuration options
+
+The alternative way to define tempaltes is to set them using the `templates` config option, this option can take a hash with keys of the same name as the shortcode tags and
+values containing a template string. For instance:
+
+```ruby
+Shortcode.setup do |config|
+  config.templates = { gallery: 'template code' }
+end
+```
+
+If the `templates` config option is set all templates will be loaded from this hash, if a shortcode is encountered without a matching key in the `templates` config option
+an exception will be raised.
+
 ### 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`, `content` and `additional_attributes` variables. Finally the class should define `content` and `attributes` methods.

data/lib/shortcode/configuration.rb

@@ -5,6 +5,9 @@ class Shortcode::Configuration
   # Sets the template parser to use, supports :erb and :haml, default is :haml
   attr_accessor :template_path
 
+  # Allows templates to be set from strings rather than read from the filesystem
+  attr_accessor :templates
+
   # Set the supported block_tags
   attr_accessor :block_tags
 
@@ -17,6 +20,7 @@ class Shortcode::Configuration
   def initialize
     @template_parser    = :haml
     @template_path      = "app/views/shortcode_templates"
+    @templates          = nil
     @block_tags         = []
     @self_closing_tags  = []
     @quotes             = '"'

data/lib/shortcode/tag.rb

@@ -14,6 +14,7 @@ class Shortcode::Tag
   end
 
   def markup
+    return markup_from_config unless Shortcode.configuration.templates.nil?
     template_files.each do |path|
       return File.read(path) if File.file? path
     end
@@ -37,6 +38,14 @@ class Shortcode::Tag
       end
     end
 
+    def markup_from_config
+      if Shortcode.configuration.templates.has_key? @name.to_sym
+        Shortcode.configuration.templates[@name.to_sym]
+      else
+        raise Shortcode::TemplateNotFound, "Shortcode.configuration.templates does not contain the key #{@name.to_sym}"
+      end
+    end
+
     def template_files
       template_paths.map do |filename|
         File.join Shortcode.configuration.template_path, filename

data/lib/shortcode/version.rb

@@ -1,3 +1,3 @@
 module Shortcode
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/spec/spec_helper.rb

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

data/spec/tag_spec.rb

@@ -28,4 +28,42 @@ describe Shortcode::Tag do
 
   end
 
+  context "templates from strings" do
+
+    let(:tag) { Shortcode::Tag.new('from_string', [{ key: 'string', value: 'batman' }]) }
+
+    before(:each) do
+      Shortcode.setup do |config|
+        config.template_parser = :erb
+        config.templates = {
+          from_string: '<p><%= @attributes[:string] %></p>'
+        }
+      end
+    end
+
+    it "renders a template from a string" do
+      tag.render.should == '<p>batman</p>'
+    end
+
+  end
+
+  context "when the template is missing from the config" do
+
+    let(:tag) { Shortcode::Tag.new('missing', [{ key: 'string', value: 'batman' }]) }
+
+    before(:each) do
+      Shortcode.setup do |config|
+        config.template_parser = :erb
+        config.templates = {
+          from_string: '<p><%= @attributes[:string] %></p>'
+        }
+      end
+    end
+
+    it "raises an error" do
+      expect { tag.render }.to raise_error(Shortcode::TemplateNotFound)
+    end
+
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: shortcode
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-09 00:00:00.000000000 Z
+date: 2014-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: parslet