octopress-hooks 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8146d664fb709b511c92e4ae185dcc904896b395
-  data.tar.gz: 0842bc67f1fafbf5f853c9bc88a5a79ae91f6312
+  metadata.gz: 3169a133f7c3a17900e54db52932fb84a202ec66
+  data.tar.gz: 104ff2a28bcce7a7bea13e51acd7b3585025bbfe
 SHA512:
-  metadata.gz: df5cdfe5412c3a0e089b3d2d30f332283a8554477c0a0be790cb2dbc88466fd2e44963b398d66bd5e77b07689b79afb2d704cb4d3f31fcbdd192a02aad58d80b
-  data.tar.gz: 34191d047548eca5d6a081be03b59e9351450ba59b53872ceae5a08d7a45f0ed43fca2a47c883e895140d1e6942616e61c1344fb7908a474ecac57b1b336f15f
+  metadata.gz: 9985494e92eb14430704b568b60beb58fd14e5043779f76eb0ed87bac8a23abc1da593128b30514b50c7091b7aea3e0565aacb186d38371d78e58d2da1ae8884
+  data.tar.gz: e4cb99f4706e85ac8d39b0fb8da9bfb006b21c7afaf286a7e38de1bb8ff9d5c267ede3b3e1c6eeeb984fdfcc26a19a06926cd159ec6834d93111966bd76731be

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+### 2.1.0
+- New: Added Post hooks.
+- Change: Page hooks now only target pages.
+- New: Added post_init hooks for pages and posts which is triggered after initialization.
+- Gone: Removed the ConvertiblePartial thing. It was unnecessary. Extending hooks is easy.
+
 ### 2.0.0
 - Added support for Site hooks: pre_render, post_write and a way to patch the site payload.
 - Changed name to octopress-hooks and moved repository to octopress/hooks.

data/README.md

@@ -1,6 +1,10 @@
 # Octopress Hooks
 
-This plugin isn't useful on its own. It monkeypatches Jekyll's Site, Post, Page and Convertible classes to allow plugin authors to access page and post data before and after render, and after write. 
+Modify Jekyll's Site, Pages and Posts at different points during the site processing stream.
+
+[![Build Status](https://travis-ci.org/octopress/hooks.svg)](https://travis-ci.org/octopress/hooks)
+[![Gem Version](http://img.shields.io/gem/v/octopress-hooks.svg)](https://rubygems.org/gems/octopress-hooks)
+[![License](http://img.shields.io/:license-mit-blue.svg)](http://octopress.mit-license.org)
 
 ## Installation
 
@@ -18,86 +22,102 @@ Or install it yourself as:
 
 ## Usage
 
-First require this plugin at the top of a plugin file, inside of Jekyll's plugin directory. Then if your plugin class inherits the PageHooks class, the methods, `pre_render`, `post_render`, `post_write` will execute automatically in turn.
+First extend the appropriate Hook class.
 
-Here's an example.
+- `Octopress::Hooks::Site` - access Jekyll's Site instance.
+- `Octopress::Hooks::Page` - access to each of Jekyll's Page instances.
+- `Octopress::Hooks::Post` - access to each of Jekyll's Post instances.
 
-```ruby
-require 'octopress-hooks'
+Then add a method based on when you want to trigger your hooks.
 
-class YourPageHooks < Octopress::Hooks::Page
+#### Site Hooks
 
-  # Manipulate page/post data before it has been processed with Liquid or
-  # Converters like Markdown or Textile.
-  #
-  def pre_render(page)
-    page.content = highlight_code(page.content)
-  end
+The Site class has three methods. Here's an example.
 
-  # Manipulate page/post data after content has been processed to html.
-  #
-  def post_render(page)
-    page.content = link_headings(page.content)
+```
+class MySiteHook < Octopress::Hooks::Site
+  
+  def pre_render(site)
   end
 
-  # Access page/post data after it has been succesfully written to disk.
-  #
-  def post_write(page)
-    log_something(page.title)
+  def merge_payload(payload, site)
   end
 
+  def post_write(site)
+  end
 end
+```
 
-class YourSiteHooks < Octopress::Hooks::Site
+Use the `pre_render` hook to modify the site instance before posts and pages are rendered.
 
-  # Get access to the site before the render process
-  #
-  def pre_render(site)
-    # do something interesting
-  end
+Use the `merge_paylod` hook to modify the site payload or merge custom data into it. This data will be available to all documents when they are rendered. This method must return a hash.
 
-  # Return a hash to be merged into the site payload
-  #
-  def merge_payload(payload, site)
-    { 'awesome' => true }
+Use the `post_write` to trigger and action after all documents have been written to disk.
+
+#### Post/Page hooks
+
+The Page and Post hooks have four methods and are identical except that Post hooks only operate on posts, and Page hooks only operate on
+pages. Here's an example of a Page hook.
+
+```
+class MySiteHook < Octopress::Hooks::Page
+
+  def post_init(page)
+  end
+  
+  def pre_render(page)
   end
 
-  # Trigger some action after the site has been written 
-  #
-  def post_write(site)
-    # do something interesting
+  def post_render(page)
   end
 
+  def post_write(page)
+  end
 end
 ```
 
-For a more complete example, check out [test.rb](test/_plugins/test.rb).
+The `post_init` method lets you access the post or page class instance immediately after it has been initialized. This allows you to
+modify the instance before the Site compiles its payload, which includes arrays of each page and post.
+
+With `pre_render` you can parse and modify page contents before it is processed by Liquid, Markdown, Textile and the like, and rendered to HTML.
 
-### When to use what
+With `post_render` you can access pages and posts after it has been converted into HTML. You might use this option if you want to modify generated HTML.
 
-#### For posts/pages
+With `post_write` you can execute a code block after a page or post has been successfully written to disk.
 
-With `pre_render` you can access page and post data before it has been
-processed by Liquid, Markdown, Textile, etc. You might want to do this if your
-plugin requires text which conflicts with some content convertors. This way
-you can replace that content with the correctly generated HTML before Liquid
-or other convertors sees it.
+To run an action on both posts and pages, you'd do something like this.
 
-With `post_render` you can access pages and posts after it has been proccessed into HTML. You might use this option if you want to modify generated HTML, for example adding anchors for each heading element.
+```ruby
+module MyModule
+  def self.do_awesome(document)
+    # something awesome
+  end
 
-With `post_write` you can execute a code block after a page or post has been
-successfully written to disk. You might use this for logging or triggering
-some external process.
+  MyPostHook < Octopress::Hooks::Post
+    def pre_render(post)
+      do_awesome(post)
+    end
+  end
 
-#### For site
+  MyPostHook < Octopress::Hooks::Page
+    def pre_render(post)
+      MyModule.do_awesome(post)
+    end
+  end
+end
+```
 
-Use the `pre_render` hook to get access to the site class and modify it as necessary before posts and pages are rendered.
-You could use this to modify these objects or even add to them.
+### Hook timeline
 
-Use the `merge_paylod` hook to add data that all documents will have access to when they are rendered, or modify the contents
-of the site payload. Be sure to return a hash that can be merged.
+Just to be clear, this is the order in which these hooks are triggered.
 
-Use the `post_write` to trigger and action after all documents have been written. With this you could gzip assets, or trigger a shell command.
+1. Post/Page `post_init`
+2. Site `pre_render`
+3. Site `merge_payload`
+4. Post/Page `pre_render`
+5. Post/Page `post_render`
+6. Post/Page `post_write`
+7. Site `post_write`
 
 ## Contributing
 

data/lib/octopress-hooks.rb

@@ -3,12 +3,38 @@ require 'jekyll'
 
 module Octopress  
   module Hooks
+
+    class Site < Jekyll::Plugin
+
+      # Called before Jekyll renders posts and pages
+      # Returns nothing
+      # 
+      def pre_render(site)
+      end
+
+      # Merges hash into site_payload
+      # Returns hash to be merged
+      #
+      def merge_payload(payload, site)
+        payload
+      end
+
+      # Called after Jekyll writes site files
+      # Returns nothing
+      #
+      def post_write(site)
+      end
+    end
     
-    # Extended plugin type that allows the plugin
-    # to be called on varous callback methods.
-    #
     class Page < Jekyll::Plugin
 
+      # Called after Page is initialized
+      # allows you to modify a # page object before it is 
+      # added to the Jekyll pages array
+      #
+      def post_init(post)
+      end
+
       # Called before post is sent to the converter. Allows
       # you to modify the post object before the converter
       # does it's thing
@@ -31,28 +57,13 @@ module Octopress
       end
     end
 
-    class Site < Jekyll::Plugin
-
-      # Called before Jekyll renders posts and pages
-      # Returns nothing
-      # 
-      def pre_render(site)
-      end
-
-      # Merges hash into site_payload
-      # Returns hash to be merged
-      #
-      def merge_payload(payload, site)
-        payload
-      end
-
-      # Called after Jekyll writes site files
-      # Returns nothing
-      #
-      def post_write(site)
-      end
-
+    class Post < Jekyll::Plugin
+      def post_init(post); end
+      def pre_render(post); end
+      def post_render(post); end
+      def post_write(post); end
     end
+
   end
 end
 
@@ -62,34 +73,42 @@ module Jekyll
 
   # For compatibilty with old jekyll-page-hooks gem
   #
-  class PageHooks < Octopress::Hooks::Page; end
+  PageHooks = Class.new(Octopress::Hooks::Page)
 
   # Monkey patch for the Jekyll Site class.
   class Site
 
     # Instance variable to store the various page_hook
     # plugins that are loaded.
-    attr_accessor :page_hooks, :site_hooks
+    attr_accessor :page_hooks, :post_hooks, :site_hooks
 
     # Instantiates all of the hook plugins. This is basically
     # a duplication of the other loaders in Site#setup.
     def load_hooks
       self.site_hooks = instantiate_subclasses(Octopress::Hooks::Site)
       self.page_hooks = instantiate_subclasses(Octopress::Hooks::Page)
+      self.post_hooks = instantiate_subclasses(Octopress::Hooks::Post)
     end
 
 
     alias_method :old_site_payload, :site_payload
     alias_method :old_render, :render
     alias_method :old_write, :write
+    alias_method :old_read, :read
+
+    # Load hooks before read to ensure that Post and Page hooks 
+    # can be triggered during initialization
+    #
+    def read
+      self.load_hooks
+      old_read
+    end
 
     # Allows site hooks to get access to the site before
     # the render method is called
     #
     # Returns nothing
     def render
-      self.load_hooks
-
       if self.site_hooks
         self.site_hooks.each do |hook|
           hook.pre_render(self)
@@ -133,87 +152,41 @@ module Jekyll
         end
       end
     end
-
   end
 
 
-  # Create a new page class to allow partials to trigger Jekyll Page Hooks.
+  # Monkey patch Jekyll's Page class
   #
-  class ConvertiblePartial
-    include Convertible
-    
-    attr_accessor :name, :content, :site, :ext, :output, :data
-    
-    def initialize(site, name, content)
-      @site     = site
-      @name     = name
-      @ext      = File.extname(name)
-      @content  = content
-      @data     = { layout: "no_layout" } # hack
-      
-    end
-    
-    def render(payload)
-      do_layout(payload, { no_layout: nil })
-    end
-  end
-
-  # Monkey patch for the Jekyll Convertible module.
-  module Convertible
+  class Page
+    alias_method :old_initialize, :initialize
 
-    def is_post?
-      self.is_a? Jekyll::Post
+    def initialize(*args)
+      old_initialize(*args)
+      post_init if respond_to?(:post_init) && self.hooks
     end
 
-    def is_page?
-      self.is_a? Jekyll::Page ||
-      self.class.to_s == 'Octopress::Ink::Page'
-    end
-
-    def is_convertible_partial?
-      self.is_a? Jekyll::ConvertiblePartial
+    def hooks
+      self.site.page_hooks
     end
+  end
 
-    def is_filterable?
-      is_post? or is_page? or is_convertible_partial?
-    end
+  # Monkey patch Jekyll's Post class
+  #
+  class Post
+    alias_method :old_initialize, :initialize
 
-    # Call the #pre_render methods on all of the loaded
-    # page_hook plugins.
-    #
-    # Returns nothing
-    def pre_render
-      if self.site.page_hooks and is_filterable?
-        self.site.page_hooks.each do |filter|
-          filter.pre_render(self)
-        end
-      end
+    def initialize(*args)
+      old_initialize(*args)
+      post_init if respond_to?(:post_init) && self.hooks
     end
 
-    # Call the #post_render methods on all of the loaded
-    # page_hook plugins.
-    #
-    # Returns nothing
-    def post_render
-      if self.site.page_hooks and is_filterable?
-        self.site.page_hooks.each do |filter|
-          filter.post_render(self)
-        end
-      end
-    end
-
-    # Call the #post_write methods on all of the loaded
-    # page_hook plugins.
-    #
-    # Returns nothing
-    def post_write
-      if self.site.page_hooks and is_filterable?
-        self.site.page_hooks.each do |filter|
-          filter.post_write(self)
-        end
-      end
+    def hooks
+      self.site.post_hooks
     end
+  end
 
+  # Monkey patch for the Jekyll Convertible module.
+  module Convertible
     alias_method :old_transform, :transform
     alias_method :old_do_layout, :do_layout
     alias_method :old_write, :write
@@ -224,7 +197,7 @@ module Jekyll
     # Returns nothing.
     def transform
       old_transform
-      post_render if respond_to?(:post_render)
+      post_render if respond_to?(:post_render) && self.hooks
     end
 
     # Calls the pre_render method if it exists and then adds any necessary
@@ -235,7 +208,7 @@ module Jekyll
     #
     # Returns nothing.
     def do_layout(payload, layouts)
-      pre_render if respond_to?(:pre_render)
+      pre_render if respond_to?(:pre_render) && self.hooks
       old_do_layout(payload, layouts)
     end
 
@@ -246,13 +219,41 @@ module Jekyll
     # Returns nothing
     def write(dest)
       old_write(dest)
-      post_write if respond_to?(:post_write)
+      post_write if respond_to?(:post_write) && self.hooks
+    end
+
+    def hooks
+      []
+    end
+
+    def post_init
+      self.hooks.each do |hook|
+        hook.post_init(self)
+      end
+    end
+    
+    def pre_render
+      self.hooks.each do |hook|
+        hook.pre_render(self)
+      end
+    end
+
+    def post_render
+      self.hooks.each do |hook|
+        hook.post_render(self)
+      end
+    end
+
+    def post_write
+      self.hooks.each do |hook|
+        hook.post_write(self)
+      end
     end
 
     # Returns the full url of the post, including the configured url
     #
     def full_url
-      self.site.config['url'] + self.url
+      File.join(self.site.config['url'], self.url)
     end
   end
 end

data/lib/octopress-hooks/version.rb

@@ -1,5 +1,5 @@
 module Octopress
   module Hooks
-    VERSION = "2.0.0"
+    VERSION = "2.1.0"
   end
 end

data/test/_expected/2014/05/21/hi-guys.html

@@ -0,0 +1 @@
+<p>Hi guys awesome</p>

data/test/_plugins/test.rb

@@ -23,7 +23,13 @@ module TestingHooks
     end
   end
 
-  class PageHooksTest < Jekyll::PageHooks
+  class PostHooksTest < Octopress::Hooks::Post
+    def post_init(post)
+      post.data['injected_data'] = 'awesome'
+    end
+  end
+
+  class PageHooksTest < Octopress::Hooks::Page
 
     # Inherited methods from PageHooks
    

data/test/_posts/2014-05-21-hi-guys.md

@@ -0,0 +1,3 @@
+---
+---
+Hi guys {{ page.injected_data }}

data/test/pre_render_page.md

@@ -1,3 +1,3 @@
 ---
 ---
-Snatch this *cupcake* from my hand.
+Snatch this *cupcake* from my hand.{{ page.injected_data }}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: octopress-hooks
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Brandon Mathis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-25 00:00:00.000000000 Z
+date: 2014-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -60,6 +60,7 @@ files:
 - test/.gitignore
 - test/Gemfile
 - test/_config.yml
+- test/_expected/2014/05/21/hi-guys.html
 - test/_expected/boom
 - test/_expected/magic
 - test/_expected/merge_payload.html
@@ -67,6 +68,7 @@ files:
 - test/_expected/post_write_page.html
 - test/_expected/pre_render_page.html
 - test/_plugins/test.rb
+- test/_posts/2014-05-21-hi-guys.md
 - test/merge_payload.md
 - test/post_render_page.md
 - test/post_write_page.md