From 1aa1eedc10c7025e07b538b42c41e124a5c9952c Mon Sep 17 00:00:00 2001 From: Thomas Reynolds Date: Sat, 14 Jan 2012 12:18:39 -0800 Subject: [PATCH] docs --- .../core_extensions/show_exceptions.rb | 16 ++++- .../middleman-core/core_extensions/sitemap.rb | 2 + .../middleman-core/extensions/asset_host.rb | 24 +++++++- .../extensions/automatic_image_sizes.rb | 21 ++++++- .../extensions/directory_indexes.rb | 30 ++++++++++ .../lib/middleman-core/extensions/lorem.rb | 60 +++++++++++++++++-- 6 files changed, 140 insertions(+), 13 deletions(-) diff --git a/middleman-core/lib/middleman-core/core_extensions/show_exceptions.rb b/middleman-core/lib/middleman-core/core_extensions/show_exceptions.rb index 256e0ff7..260e04d8 100644 --- a/middleman-core/lib/middleman-core/core_extensions/show_exceptions.rb +++ b/middleman-core/lib/middleman-core/core_extensions/show_exceptions.rb @@ -1,9 +1,17 @@ -require 'rack/showexceptions' - +# Support rack/showexceptions during development module Middleman::CoreExtensions::ShowExceptions + + # Setup extension class << self + + # Once registered def registered(app) + # Require lib + require 'rack/showexceptions' + + # When in dev app.configure :development do + # Include middlemare if show_exceptions use ::Middleman::CoreExtensions::ShowExceptions::Middleware end @@ -11,6 +19,8 @@ module Middleman::CoreExtensions::ShowExceptions end end + # Custom exception class + # TODO: Style this ourselves class Middleware < ::Rack::ShowExceptions end -end +end \ No newline at end of file diff --git a/middleman-core/lib/middleman-core/core_extensions/sitemap.rb b/middleman-core/lib/middleman-core/core_extensions/sitemap.rb index 0435911c..a2c7e6b9 100644 --- a/middleman-core/lib/middleman-core/core_extensions/sitemap.rb +++ b/middleman-core/lib/middleman-core/core_extensions/sitemap.rb @@ -1,7 +1,9 @@ # Core Sitemap Extensions module Middleman::CoreExtensions::Sitemap + # Setup Extension class << self + # Once registered def registered(app) # Setup callbacks which can exclude paths from the sitemap diff --git a/middleman-core/lib/middleman-core/extensions/asset_host.rb b/middleman-core/lib/middleman-core/extensions/asset_host.rb index 2b856967..113f991a 100644 --- a/middleman-core/lib/middleman-core/extensions/asset_host.rb +++ b/middleman-core/lib/middleman-core/extensions/asset_host.rb @@ -1,21 +1,36 @@ +# Extensions namespace module Middleman::Extensions + + # Asset Host module module AssetHost + + # Setup extension class << self + + # Once registered def registered(app) + # Default to no host app.set :asset_host, false + # Include methods app.send :include, InstanceMethods end + alias :included :registered end + # Asset Host Instance Methods module InstanceMethods + + # Override default asset url helper to include asset hosts + # + # @param [String] path + # @param [String] prefix + # @return [String] def asset_url(path, prefix="") original_output = super return original_output unless asset_host - # valid_extensions = %w(.png .gif .jpg .jpeg .svg .svgz .js .css) - asset_prefix = if asset_host.is_a?(Proc) asset_host.call(original_output) elsif asset_host.is_a?(String) @@ -26,4 +41,7 @@ module Middleman::Extensions end end end -end + + # Register the extension + register :asset_host, AssetHost +end \ No newline at end of file diff --git a/middleman-core/lib/middleman-core/extensions/automatic_image_sizes.rb b/middleman-core/lib/middleman-core/extensions/automatic_image_sizes.rb index afb22561..a31cf140 100755 --- a/middleman-core/lib/middleman-core/extensions/automatic_image_sizes.rb +++ b/middleman-core/lib/middleman-core/extensions/automatic_image_sizes.rb @@ -1,15 +1,33 @@ +# Extensions namespace module Middleman::Extensions + + # Automatic Image Sizes extension module AutomaticImageSizes + + # Setup extension class << self + + # Once registered def registered(app) + # Include 3rd-party fastimage library require "middleman-core/extensions/automatic_image_sizes/fastimage" + # Include methods app.send :include, InstanceMethods end + alias :included :registered end + # Automatic Image Sizes Instance Methods module InstanceMethods + + # Override default image_tag helper to automatically calculate and include + # image dimensions. + # + # @param [String] path + # @param [Hash] params + # @return [String] def image_tag(path, params={}) if !params.has_key?(:width) && !params.has_key?(:height) && !path.include?("://") params[:alt] ||= "" @@ -34,5 +52,6 @@ module Middleman::Extensions end end + # Register the extension register :automatic_image_sizes, AutomaticImageSizes -end +end \ No newline at end of file diff --git a/middleman-core/lib/middleman-core/extensions/directory_indexes.rb b/middleman-core/lib/middleman-core/extensions/directory_indexes.rb index 4f7cfa94..1c8ea2df 100644 --- a/middleman-core/lib/middleman-core/extensions/directory_indexes.rb +++ b/middleman-core/lib/middleman-core/extensions/directory_indexes.rb @@ -1,8 +1,18 @@ +# Extensions namespace module Middleman::Extensions + + # Directory Indexes extension module DirectoryIndexes + + # Setup extension class << self + + # Once registered def registered(app) + # Include methods app.send :include, InstanceMethods + + # Before requests app.before do prefix = @original_path.sub(/\/$/, "") indexed_path = prefix + "/" + index_file @@ -11,22 +21,29 @@ module Middleman::Extensions is_ignored = false fm_ignored = false + # If the sitemap knows about the path if sitemap.exists?(@original_path) + # Inspect frontmatter d = sitemap.page(@original_path).data + + # Allow the frontmatter to ignore a directory index if !d.nil? && d.has_key?("directory_index") && d["directory_index"] == false fm_ignored = true else next end else + # Otherwise check this extension for list of ignored indexes is_ignored = ignored_directory_indexes.include?(extensioned_path) end + # If we're going to remap to a directory index if !sitemap.exists?(indexed_path) && !is_ignored && !fm_ignored parts = @original_path.split("/") last_part = parts.last last_part_ext = File.extname(last_part) + # Change the request if last_part_ext.blank? # This is a folder, redirect to index @request_path = extensioned_path @@ -34,11 +51,13 @@ module Middleman::Extensions end end + # Basically does the same as above, but in build mode app.build_reroute do |destination, request_path| index_ext = File.extname(index_file) new_index_path = "/#{index_file}" frontmatter_ignore = false + # Check for file and frontmatter if sitemap.exists?(request_path) p = sitemap.page(request_path) d = p.data @@ -47,6 +66,7 @@ module Middleman::Extensions end end + # Only reroute if not ignored if ignored_directory_indexes.include?(request_path) false elsif request_path =~ /#{new_index_path}$/ @@ -61,14 +81,23 @@ module Middleman::Extensions end end end + alias :included :registered end + # Directory indexes instance methods module InstanceMethods + # A list of pages which will not use directory indexes + # @return [Array] def ignored_directory_indexes @_ignored_directory_indexes ||= [] end + # Override the page helper to accept a :directory_index option + # + # @param [String] url + # @param [Hash] options + # @return [void] def page(url, options={}, &block) if options.has_key?(:directory_index) && !options["directory_index"] ignored_directory_indexes << url @@ -79,5 +108,6 @@ module Middleman::Extensions end end + # Register the extension register :directory_indexes, DirectoryIndexes end \ No newline at end of file diff --git a/middleman-core/lib/middleman-core/extensions/lorem.rb b/middleman-core/lib/middleman-core/extensions/lorem.rb index c6616fc1..0b8e17d8 100644 --- a/middleman-core/lib/middleman-core/extensions/lorem.rb +++ b/middleman-core/lib/middleman-core/extensions/lorem.rb @@ -1,17 +1,34 @@ +# Extension namespace module Middleman::Extensions + + # Lorem helper module Lorem + + # Setup extension class << self + + # Once registered def registered(app) + # Include methods app.send :include, InstanceMethods end + alias :included :registered end + # Lorem extension instance methods module InstanceMethods + # Access to the Lorem object + # @return [Middleman::Extensions::Lorem::LoremObject] def lorem - @_lorem ||= LoremObject.new(self) + @_lorem ||= LoremObject.new end + # Return a placeholder image using placekitten.com + # + # @param [String] size + # @param [Hash] options + # @return [String] def placekitten(size, options={}) options[:domain] = "http://placekitten.com" lorem.image(size, options) @@ -43,42 +60,57 @@ module Middleman::Extensions # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR # OTHER DEALINGS IN THE SOFTWARE. class LoremObject + # Words for use in lorem text WORDS = %w(alias consequatur aut perferendis sit voluptatem accusantium doloremque aperiam eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo aspernatur aut odit aut fugit sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt neque dolorem ipsum quia dolor sit amet consectetur adipisci velit sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem ut enim ad minima veniam quis nostrum exercitationem ullam corporis nemo enim ipsam voluptatem quia voluptas sit suscipit laboriosam nisi ut aliquid ex ea commodi consequatur quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae et iusto odio dignissimos ducimus qui blanditiis praesentium laudantium totam rem voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident sed ut perspiciatis unde omnis iste natus error similique sunt in culpa qui officia deserunt mollitia animi id est laborum et dolorum fuga et harum quidem rerum facilis est et expedita distinctio nam libero tempore cum soluta nobis est eligendi optio cumque nihil impedit quo porro quisquam est qui minus id quod maxime placeat facere possimus omnis voluptas assumenda est omnis dolor repellendus temporibus autem quibusdam et aut consequatur vel illum qui dolorem eum fugiat quo voluptas nulla pariatur at vero eos et accusamus officiis debitis aut rerum necessitatibus saepe eveniet ut et voluptates repudiandae sint et molestiae non recusandae itaque earum rerum hic tenetur a sapiente delectus ut aut reiciendis voluptatibus maiores doloribus asperiores repellat) - def initialize(app) - @app = app - end - + # Get one placeholder word + # @return [String] def word words(1) end + # Get some number of placeholder words + # @param [Fixnum] total + # @return [String] def words(total) (1..total).map do randm(WORDS) end.join(' ') end + # Get one placeholder sentence + # @return [String] def sentence sentences(1) end + # Get some number of placeholder sentences + # @param [Fixnum] total + # @return [String] def sentences(total) (1..total).map do words(randm(4..15)).capitalize end.join('. ') end + # Get one placeholder paragraph + # @return [String] def paragraph paragraphs(1) end + # Get some number of placeholder paragraphs + # @param [Fixnum] total + # @return [String] def paragraphs(total) (1..total).map do sentences(randm(3..7)).capitalize end.join("\n\n") end + # Get a placeholder date + # @param [String] fmt + # @return [String] def date(fmt = '%a %b %d, %Y') y = rand(20) + 1990 m = rand(12) + 1 @@ -86,20 +118,28 @@ module Middleman::Extensions Time.local(y,m,d).strftime(fmt) end + # Get a placeholder name + # @return [String] def name "#{first_name} #{last_name}" end + # Get a placeholder first name + # @return [String] def first_name names = "Judith Angelo Margarita Kerry Elaine Lorenzo Justice Doris Raul Liliana Kerry Elise Ciaran Johnny Moses Davion Penny Mohammed Harvey Sheryl Hudson Brendan Brooklynn Denis Sadie Trisha Jacquelyn Virgil Cindy Alexa Marianne Giselle Casey Alondra Angela Katherine Skyler Kyleigh Carly Abel Adrianna Luis Dominick Eoin Noel Ciara Roberto Skylar Brock Earl Dwayne Jackie Hamish Sienna Nolan Daren Jean Shirley Connor Geraldine Niall Kristi Monty Yvonne Tammie Zachariah Fatima Ruby Nadia Anahi Calum Peggy Alfredo Marybeth Bonnie Gordon Cara John Staci Samuel Carmen Rylee Yehudi Colm Beth Dulce Darius inley Javon Jason Perla Wayne Laila Kaleigh Maggie Don Quinn Collin Aniya Zoe Isabel Clint Leland Esmeralda Emma Madeline Byron Courtney Vanessa Terry Antoinette George Constance Preston Rolando Caleb Kenneth Lynette Carley Francesca Johnnie Jordyn Arturo Camila Skye Guy Ana Kaylin Nia Colton Bart Brendon Alvin Daryl Dirk Mya Pete Joann Uriel Alonzo Agnes Chris Alyson Paola Dora Elias Allen Jackie Eric Bonita Kelvin Emiliano Ashton Kyra Kailey Sonja Alberto Ty Summer Brayden Lori Kelly Tomas Joey Billie Katie Stephanie Danielle Alexis Jamal Kieran Lucinda Eliza Allyson Melinda Alma Piper Deana Harriet Bryce Eli Jadyn Rogelio Orlaith Janet Randal Toby Carla Lorie Caitlyn Annika Isabelle inn Ewan Maisie Michelle Grady Ida Reid Emely Tricia Beau Reese Vance Dalton Lexi Rafael Makenzie Mitzi Clinton Xena Angelina Kendrick Leslie Teddy Jerald Noelle Neil Marsha Gayle Omar Abigail Alexandra Phil Andre Billy Brenden Bianca Jared Gretchen Patrick Antonio Josephine Kyla Manuel Freya Kellie Tonia Jamie Sydney Andres Ruben Harrison Hector Clyde Wendell Kaden Ian Tracy Cathleen Shawn".split(" ") names[rand(names.size)] end + # Get a placeholder last name + # @return [String] def last_name names = "Chung Chen Melton Hill Puckett Song Hamilton Bender Wagner McLaughlin McNamara Raynor Moon Woodard Desai Wallace Lawrence Griffin Dougherty Powers May Steele Teague Vick Gallagher Solomon Walsh Monroe Connolly Hawkins Middleton Goldstein Watts Johnston Weeks Wilkerson Barton Walton Hall Ross Chung Bender Woods Mangum Joseph Rosenthal Bowden Barton Underwood Jones Baker Merritt Cross Cooper Holmes Sharpe Morgan Hoyle Allen Rich Rich Grant Proctor Diaz Graham Watkins Hinton Marsh Hewitt Branch Walton O'Brien Case Watts Christensen Parks Hardin Lucas Eason Davidson Whitehead Rose Sparks Moore Pearson Rodgers Graves Scarborough Sutton Sinclair Bowman Olsen Love McLean Christian Lamb James Chandler Stout Cowan Golden Bowling Beasley Clapp Abrams Tilley Morse Boykin Sumner Cassidy Davidson Heath Blanchard McAllister McKenzie Byrne Schroeder Griffin Gross Perkins Robertson Palmer Brady Rowe Zhang Hodge Li Bowling Justice Glass Willis Hester Floyd Graves Fischer Norman Chan Hunt Byrd Lane Kaplan Heller May Jennings Hanna Locklear Holloway Jones Glover Vick O'Donnell Goldman McKenna Starr Stone McClure Watson Monroe Abbott Singer Hall Farrell Lucas Norman Atkins Monroe Robertson Sykes Reid Chandler Finch Hobbs Adkins Kinney Whitaker Alexander Conner Waters Becker Rollins Love Adkins Black Fox Hatcher Wu Lloyd Joyce Welch Matthews Chappell MacDonald Kane Butler Pickett Bowman Barton Kennedy Branch Thornton McNeill Weinstein Middleton Moss Lucas Rich Carlton Brady Schultz Nichols Harvey Stevenson Houston Dunn West O'Brien Barr Snyder Cain Heath Boswell Olsen Pittman Weiner Petersen Davis Coleman Terrell Norman Burch Weiner Parrott Henry Gray Chang McLean Eason Weeks Siegel Puckett Heath Hoyle Garrett Neal Baker Goldman Shaffer Choi Carver".split(" ") names[rand(names.size)] end + # Get a placeholder email address + # @return [String] def email delimiters = [ '_', '-', '' ] domains = %w(gmail.com yahoo.com hotmail.com email.com live.com me.com mac.com aol.com fastmail.com mail.com) @@ -107,6 +147,10 @@ module Middleman::Extensions "#{username}@#{domains[rand(domains.size)]}".downcase end + # Get a placeholder image, using placehold.it by default + # @param [String] size + # @param [Hash] options + # @return [String] def image(size, options={}) domain = options[:domain] || "http://placehold.it" src = "#{domain}/#{size}" @@ -129,12 +173,16 @@ module Middleman::Extensions private + # Pick a random item from a given range + # @param [Range] range + # @return [Object] def randm(range) a = range.to_a a[rand(a.length)] end end end - + + # Register the extension register :lorem, Lorem end \ No newline at end of file