plate 0.5.4 → 0.6.0

data/lib/plate/callbacks.rb

@@ -1,28 +1,44 @@
 module Plate
+  # Callbacks are used to extend the base functionality of Plate. You might want to create
+  # some dynamic pages after all posts have been loaded (such as a blog archives view) or
+  # clean up some page output after it is rendered but before it is written to disk. Callbacks
+  # are the best way to achieve these and other common use cases.
+  #
+  # Callbacks must be registered with an object to be used. If you generated a new site
+  # using the `plate new .` or `platify` command, you should see an example callbacks file
+  # in `lib/callbacks.rb`.
+  #
   module Callbacks
     def self.included(base)
       base.send(:include, InstanceMethods)
       base.send(:extend, ClassMethods)
     end
-    
+
     module ClassMethods
+      # All of the callbacks that have been registered.
       def callbacks
         @callbacks ||= {}
       end
-      
+
+      # Register a new callback
+      #
+      # @example
+      #     Plate::Page.register_callback(:after_render) do |page|
+      #       puts "Rendered page! #{page.path}"
+      #     end
       def register_callback(name, method_name = nil, &block)
         callbacks[name] ||= []
         callbacks[name] << (block || method_name)
       end
     end
-    
+
     module InstanceMethods
       def around_callback(name, &block)
         run_callback "before_#{name}".to_sym
         block.call
         run_callback "after_#{name}".to_sym
       end
-      
+
       def run_callback(name)
         if callbacks = self.class.callbacks[name]
           callbacks.each do |callback|

data/lib/plate/cli.rb

@@ -2,45 +2,45 @@ module Plate
   # The CLI class controls the behavior of plate when it is used as a command line interface.
   class CLI
     require 'optparse'
-    
+
     attr_accessor :source, :destination, :args, :options
-    
+
     def initialize(args = [])
       @args = String === args ? args.split(' ') : args.dup
       @options = {}
-      
+
       # Some defaults
       @source = Dir.pwd
       @destination = File.join(@source, 'public')
     end
-    
+
     def builder
       @builder ||= Builder.new(self.source, self.destination, self.options)
     end
-    
+
     # The current command to be run. Pulled from the args attribute.
     def command
       self.args.size > 0 ? self.args[0] : 'build'
     end
-    
+
     def parse_options!
       options = {}
 
       opts = OptionParser.new do |opts|
         banner = "Usage: plate [command] [options]"
-        
+
         opts.on('--category [CATEGORY]', '-c', 'Pass in a category for creating a new post.') do |c|
           options[:category] = c
         end
-        
+
         opts.on('--config [PATH]', '-C', 'Set the config file location for the site.') do |c|
           options[:config] = c
         end
-        
+
         opts.on('--destination [PATH]', '-d', 'Set the destination directory for this build.') do |d|
           @destination = File.expand_path(d)
         end
-        
+
         opts.on('--layout [LAYOUT]', '-l', 'Pass in a layout for creating a new post.') do |l|
           options[:layout] = l
         end
@@ -57,23 +57,23 @@ module Plate
           puts "You're running Plate version #{Plate::VERSION}!"
           exit 0
         end
-        
+
         opts.on('--watch', '-w', 'Watch the source directory for changes.') do
           options[:watch] = true
         end
       end
 
       opts.parse!(self.args)
-      
+
       @options = options
     end
-    
+
     # Run the given command. If the command does not exist, nothing will be run.
     def run
       parse_options!
-      
+
       command_name = "run_#{command}_command".to_sym
-      
+
       if self.respond_to?(command_name)
         # remove command name
         self.args.shift
@@ -82,20 +82,20 @@ module Plate
         puts "Command #{command} not found"
         return false
       end
-      
+
       true
     end
-    
+
     class << self
       def run!
         new(ARGV).run
       end
     end
-    
+
     protected
       def process_file_change(event)
-        relative_path = builder.relative_path(event.path)        
-          
+        relative_path = builder.relative_path(event.path)
+
         unless relative_path.start_with?('/public/')
           if builder.reloadable?(relative_path)
             case event.type
@@ -115,13 +115,15 @@ module Plate
           end
         end
       end
-    
+
       def run_build_command
-        puts "Building your site from #{source} to #{destination}"
-        
         builder.enable_logging = true if options[:verbose]
+        builder.load!
+
+        puts "Building your site from #{source} to #{builder.destination}"
+
         builder.render!
-        
+
         if builder.items?
           # If we want to watch directories, keep the chain open
           if options[:watch]
@@ -139,86 +141,96 @@ module Plate
             puts "Site build complete."
           end
         else
-          puts "** There seems to be no site content in this folder. Did you mean to create a new site?\n\n    plate new .\n\n"
+          puts "** There seems to be no site content in this folder. Did you mean to create a new site first?\n\n    platify .\n\n"
         end
       end
-      
-      def run_new_command        
+
+      def run_new_command
         # Set the base root
         root = './'
-        
+
         if args.size > 0
           root = args[0]
         end
-        
+
         puts "Generating new plate site at #{root}..."
-        
+
         # The starting path for the new site
         root_path = File.expand_path(root)
-        
+
         # Create all folders needed for a base site.
         %w(
           /
           config
           content
+          content/css
           layouts
+          lib
           posts
         ).each do |dir|
-          action = File.directory?(File.join(root_path, dir)) ? "exists" : "create"          
+          action = File.directory?(File.join(root_path, dir)) ? "exists" : "create"
           puts "   #{action}   #{File.join(root, dir)}"
-          
+
           if action == "create"
             FileUtils.mkdir_p(File.join(root_path, dir))
-          end          
+          end
         end
-        
+
         # Create a blank layout file
-        create_template('layouts/default.erb', 'layout.erb', root, root_path)
-        
+        create_template('layouts/default.html.erb', 'layout.html.erb', root, root_path)
+
         # Config file
         create_template('config/plate.yml', 'config.yml', root, root_path)
-        
+
         # Index page
-        create_template('content/index.md', 'index.md', root, root_path)
-        
+        create_template('content/index.html', 'index.html', root, root_path)
+
+        # RSS Feed
+        create_template('content/rss.erb', 'rss.erb', root, root_path)
+
+        # Sample callbacks file
+        create_template('lib/callbacks.rb', 'callbacks.rb', root, root_path)
+
+        # Default CSS file from Bootstrap
+        create_template('content/css/bootstrap.min.css', 'bootstrap.min.css', root, root_path)
+
         puts "New site generated!"
       end
-      
+
       def run_post_command
         title = args.size == 0 ? "" : args[0]
         slug = title.parameterize
         date = Time.now
-        
+
         # if there are any post defaults in the config file, use those as the default options
         if builder.config.has_key?(:post_defaults)
           options.reverse_merge!(builder.config[:post_defaults])
         end
-        
+
         category = options[:category] ? "\ncategory: #{options[:category]}" : ""
         layout = options[:layout] ? "\nlayout: #{options[:layout]}" : ""
-        
+
         filename = File.join(self.source, 'posts', date.strftime('%Y/%m'), "#{date.strftime('%Y-%m-%d')}-#{slug}.md")
         content = %Q(---\ntitle: "#{title}"\ndate: #{date.strftime('%Y-%m-%d %H:%M:%S')}#{category}#{layout}\ntags: []\n\n# #{title}\n\nLorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.)
-        
+
         FileUtils.mkdir_p(File.dirname(filename))
         File.open(filename, 'w') { |f| f.write(content) }
-        
+
         puts "New post file added [#{filename}]"
       end
-      
+
       def create_template(path, template, root, root_path)
-        action = File.exist?(File.join(root_path, path)) ? "exists" : "create"          
+        action = File.exist?(File.join(root_path, path)) ? "exists" : "create"
         puts "   #{action}   #{File.join(root, path)}"
-        
+
         if action == "create"
+          dest = File.join(root_path, path)
           template_root = File.expand_path(File.join(File.dirname(__FILE__), '..', 'templates'))
-          
           contents = File.read(File.join(template_root, template))
-          
           unless contents.to_s.blank?
-            File.open(File.join(root_path, path), 'w') { |f| f.write(contents) }
+            File.open(dest, 'w') { |f| f.write(contents) }
           end
-        end        
+        end
       end
   end
 end

data/lib/plate/dsl.rb

@@ -0,0 +1,68 @@
+module Plate
+  # The Dsl class provides the methods available in plugin files in order to extend
+  # the functionality a generated site.
+  class Dsl
+    class << self
+      # Evaluate the given file path into the {Plate::Dsl dsl} instance.
+      def evaluate_plugin(file_path)
+        instance_eval_plugin(read_plugin_file(file_path))
+      end
+
+      # Performs evaluation of the file's content
+      def instance_eval_plugin(content)
+        new.instance_eval(content)
+      end
+
+      # Read the given plugin file path into a string
+      #
+      # @return [String] The plugin file's contents
+      def read_plugin_file(file_path)
+        File.read(file_path)
+      rescue
+        raise PluginNotReadable
+      end
+    end
+
+    # Register a new callback for the given object and event.
+    #
+    # @example Run block after rendering a site
+    #     callback :site, :after_render do
+    #       puts 'done!'
+    #     end
+    #
+    # @example Run block before rendering a page
+    #     callback :page, :before_render do |page|
+    #       puts "Rendering page #{page.path}"
+    #     end
+    #
+    # @example Run a method on the site after write
+    #     class Site
+    #       def finished!
+    #         log('All done.')
+    #       end
+    #     end
+    #
+    #     callback :site, :after_write, :finished!
+    #
+    def callback(object, event, method_name = nil, &block)
+      if Symbol === object
+        object = "Plate::#{object.to_s.classify}".constantize
+      end
+
+      object.register_callback(event, method_name, &block)
+    end
+    alias :register_callback :callback
+
+    # Set up a new engine designed for rendering dynamic assets.
+    # Engines should be compatible with the Tilt::Template syntax.
+    def register_asset_engine(extension, klass)
+      Plate.register_asset_engine(extension, klass)
+    end
+
+    # Set up a new engine designed for rendering dynamic assets.
+    # Engines should be compatible with the Tilt::Template syntax.
+    def register_template_engine(extension, klass)
+      Plate.register_template_engine(extension, klass)
+    end
+  end
+end

data/lib/plate/errors.rb

@@ -1,10 +1,13 @@
 module Plate
-  class SourceNotFound < StandardError
-  end
-  
   class FileNotFound < StandardError
   end
-  
+
   class NoPostDateProvided < StandardError
   end
+
+  class PluginNotReadable < StandardError
+  end
+
+  class SourceNotFound < StandardError
+  end
 end

data/lib/plate/hash_proxy.rb

@@ -0,0 +1,27 @@
+module Plate
+  # Just a blank class that allows you to call methods that return hash values
+  class HashProxy
+    # Pass in a hash object to use this class as a proxy for its keys.
+    def initialize(source = {})
+      @source = source
+    end
+    
+    # Pass through for getting the hash's value at the given key.
+    def [](key)
+      @source[key]
+    end
+    
+    # Handle method missing calls and proxy methods to hash values.
+    #
+    # Allows for checking to see if a key exists and returning a key value.
+    def method_missing(method, *args)
+      if @source.has_key?(method)
+        self[method]
+      elsif method.to_s =~ /^[a-zA-Z0-9_]*\?$/
+        @source.has_key?(method.to_s.gsub!(/\?/, '').to_sym)
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/plate/helpers/url_helper.rb

@@ -1,6 +1,25 @@
 module Plate
   # Includes basic helpers for managing URLs within your site.
   module URLHelper  
+    # replace all relative links within the given content block to absolute
+    # links containing the base url for this site.
+    #
+    # This is useful in creating RSS and/or Atom feeds that you'd like to 
+    # contain links back to your site.
+    #
+    # href or src values that don't start with a slash are left intact.
+    #
+    # @example
+    #     <a href="/posts/one"><img src="/images/sample.jpg"></a>
+    #
+    #     <!-- turns into: -->
+    #
+    #     <a href="http://example.com/posts/one"><img src="http://example.com/images/sample.jpg"></a>
+    def absolutize_paths(content)
+      content.gsub(Regexp.new("(src|href)=(\"|')/"), "\\1=\\2#{site.url}/")
+    end
+    alias_method :a, :absolutize_paths
+  
     # Cleans up a string to make it URl-friendly, removing all special 
     # characters, spaces, and sanitizing to a dashed, lowercase string.
     def sanitize_slug(str)

data/lib/plate/layout.rb

@@ -1,125 +1,125 @@
 module Plate
   class Layout
     attr_accessor :site, :file, :meta, :content
-    
+
     def initialize(site, file = nil, load_on_initialize = true)
       self.site = site
       self.file = file
       self.meta = {}
       self.content = ""
-      
+
       load! if load_on_initialize and file?
     end
-    
+
     # The name of the layound, without any path data
     def basename
       File.basename(self.file)
     end
-    
+
     # Is this layout the default layout, by name.
     def default?
       self.name.downcase.strip.start_with? "default"
     end
-    
+
     # The layout engine to use. Based off of the last file extension for this layout.
     def engine
       @engine ||= self.site.registered_page_engines[self.extension.gsub(/\./, '').to_sym]
     end
-    
+
     # The last file extension of this layout.
     def extension
       File.extname(self.file)
     end
-    
-    # Does the file exist or not. 
+
+    # Does the file exist or not.
     def file?
       return false if self.file.nil?
       File.exists?(self.file)
     end
-    
+
     # A unique ID for this layout.
-    def id      
+    def id
       @id ||= Digest::MD5.hexdigest(relative_file)
     end
-    
+
     def inspect
       "#<#{self.class}:0x#{object_id.to_s(16)} name=#{name.to_s.inspect}>"
     end
-    
+
     def load!
-      return if @loaded      
+      return if @loaded
       raise FileNotFound unless file?
-      
+
       read_file!
       read_metadata!
-      
+
       @loaded = true
     end
-    
+
     # The name for a layout is just the lowercase, first part of the file name.
     def name
-      return "" unless file?      
+      return "" unless file?
       @name ||= self.basename.to_s.downcase.strip.split('.')[0]
     end
-    
+
     # A parent layout for this current layout file. If no layout is specified for this
     # layout's parent, then nil is returned. If there is a parent layout for this layout,
     # any pages using it will be rendered using this layout first, then sent to the parent
     # for further rendering.
     def parent
       return @parent if @parent
-      
+
       if self.meta[:layout]
         @parent = self.site.find_layout(self.meta[:layout])
       else
         @parent = nil
       end
-      
+
       @parent
     end
-    
+
     def relative_file
       @relative_file ||= self.site.relative_path(self.file)
     end
-    
+
     def reload!
       @template = nil
       @loaded = false
       @name = nil
       @engine = nil
     end
-    
+
     # Render the given content against the current layout template.
     def render(content, page = nil, view = nil)
       if self.template
         view ||= View.new(self.site, page)
         result = self.template.render(view) { content }
-        
+
         if self.parent
           result = self.parent.render(result, page, view)
         end
-        
+
         view = nil
-        
+
         result
       else
         content.respond_to?(:rendered_content) ? content.rendered_content : content.to_s
       end
     end
-    
-    # The render template to use for this layout. A template is only used if the 
+
+    # The render template to use for this layout. A template is only used if the
     # file extension for the layout is a valid layout extension from the current
     # site.
     def template
       return @template if @template
-            
+
       if template?
         @template = self.engine.new() { self.content }
       else
         nil
       end
     end
-    
+
     # Does this file have the ability to be used as a template?
     #
     # This currently only works if the layout is a .erb file. Otherwise anything that
@@ -127,31 +127,36 @@ module Plate
     def template?
       self.site.page_engine_extensions.include?(self.extension)
     end
-    
+
     # Is this layout equal to another page being sent?
     def ==(other)
       other = other.relative_file if other.respond_to?(:relative_file)
       self.id == other or self.relative_file == other
     end
-    
+
+    # Compare two layouts, by name.
+    def <=>(other)
+      self.name <=> other.name
+    end
+
     protected
       # Read the file and store it in @content
       def read_file!
         self.content = file? ? File.read(self.file) : nil
       end
-    
+
       # Reads all content from a layouts's meta data. At this time, the layout only supports
       # loading a parent layout. All other meta data is unused.
       #
       # Meta data is stored in YAML format within the head of a page after the -- declaration like so:
-      # 
+      #
       #     ---
       #     layout: default
       #
       #     # Start of layout content
       def read_metadata!
         return unless self.content
-        
+
         begin
           if matches = /^(---\n)(.*?)^\s*?$/m.match(self.content)
             if matches.size == 3
@@ -159,7 +164,7 @@ module Plate
               self.meta = YAML.load(matches[2])
               self.meta.symbolize_keys!
             end
-          end        
+          end
         rescue Exception => e
           self.meta = {}
           self.site.log("  ** Problem reading YAML for file #{relative_file} (#{e.message}). Meta data skipped")