flutterby 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 912db5fb0467b2ea17535d27a16f7d5cae9c4844
-  data.tar.gz: bc120fb8c0db94fe25f9894183c2ac784c8c7723
+  metadata.gz: aaa79d7d4b6d42abb898e01b65d8628910b116c0
+  data.tar.gz: 28642fba892e47a24b141d9aaeb8d0e4851947ad
 SHA512:
-  metadata.gz: 2f00d281c3fc731e97877ee6c091d38a5589ed3ff6bcddc0301f6b5b4a78a1b6357585af2facbbe314c2134233e2e349108d789e34c75e11f502e9617d5a58f2
-  data.tar.gz: 2c054331bd42b2c1fc898694ec1b9446d8fa04d8e53f728feaff8ba13885c27e6ac0d22e738f9191998e47619c46309e8820deccf53c40b2e08c9d4ae80f4d9d
+  metadata.gz: c6cb96a3e41dd21a7a0903ba6bd3b3d5f47ab30d2d6aff21d57385dc2dfe9e8b1d408e3d2f35b08d3d55ff389a71b5d5924ae29ae94d778ffa8a8f5e20fc4570
+  data.tar.gz: e65316a8cee9c3c93244491c801c5582f1be68ca7df225e976d3ac5855616d7d854c603b969ebd6bc4b4eba520626e96d4a998d06b00118abd3b8609397580c5

data/CHANGES.md

@@ -1,5 +1,13 @@
 # Version History
 
+### 0.6.0 (2017-01-26)
+
+- **NEW:** Within a view context, you can now invoke `render(node, as: "foo")`, and it will use a `_foo` partial in the same folder as `node`, passing `node` as a `foo` local. This allows you to easily apply decorator partials to nodes.
+- **NEW:** When invoking `Node#render`, you now have additional control over the layout behavior through the `layout` argument. Like before, when `true`, the default page layouts will be applied; when `false`, no layout will be applied whatsoever; but now you can also pass one or more nodes (or node selectors) that will be applied as layouts.
+- **BREAKING:** If you want to pass locals to `render`, you now need to use the `locals:` key. Example: `node.render(locals: { foo: "bar" })`
+- **IMPROVED:** The new project template has received some minor improvements, including a `Rakefile` containing an example `deploy` task.
+
+
 ### 0.5.2 (2017-01-25)
 
 - **NEW:** Just like `find`, there is now also a `find!` that will raise an exception when the specified node could not be found.

data/README.md

@@ -5,93 +5,35 @@
 [![Gem Version](https://badge.fury.io/rb/flutterby.svg)](https://badge.fury.io/rb/flutterby) [![Build Status](https://travis-ci.org/hmans/flutterby.svg?branch=master)](https://travis-ci.org/hmans/flutterby) [![license](https://img.shields.io/github/license/hmans/flutterby.svg)](https://github.com/hmans/flutterby/blob/master/LICENSE.txt) ![Status](https://img.shields.io/badge/status-active-brightgreen.svg)
 
 
-#### Key Features:
+#### Links:
 
-- Generate a static website from a source directory!
-- Apply any number of transformations on files!
-- Built-in support for Markdown, Sass, Erb, Slim and more!
-- Extremely easy to extend with new transformation filters!
-- Sprinkle your site with Ruby code that can interact with your site's pages and data!
-
-#### Recommended Reading:
-
-- [Blog post introducing Flutterby](http://hmans.io/posts/2017/01/11/flutterby.html)
-- [New project template](https://github.com/hmans/flutterby/tree/master/lib/templates/new_project) (example code)
-- [Code Reference Documentation](http://www.rubydoc.info/github/hmans/flutterby)
+- [Official Flutterby Website](http://www.flutterby.run/)
+- [Flutterby Documentation](http://www.flutterby.run/docs/) and [Reference](http://www.rubydoc.info/github/hmans/flutterby)
 - [Version History](https://github.com/hmans/flutterby/blob/master/CHANGES.md)
 - [Issues/Roadmap](https://github.com/hmans/flutterby/issues)
-- [Sites built with Flutterby](https://github.com/hmans/flutterby/wiki/Sites-built-with-Flutterby) (add yours!)
-
-
-## Installation & Basic Usage
-
-Flutterby is distributed as a RubyGem, so let's install it first:
-
-    gem install flutterby
-
-This will install a `flutterby` executable on your system. Let's use it to create a new project:
-
-    flutterby new mysite
-    cd mysite
-
-The new project template serves as a simple starting point for new projects. Let's compile it into a static site:
-
-    flutterby build
-
-Flutterby comes with a local development server that will automatically pick up changes you make to your files:
-
-    flutterby serve
 
-**Note**: by default, both the `build` and `serve` commands assume `./site/` to be the source directory and `./_build/` to be the export directory. Please refer to `flutterby help` to see how you can override these.
+#### Examples:
 
+- [Sites built with Flutterby](https://github.com/hmans/flutterby/wiki/Sites-built-with-Flutterby) (add yours!)
+- [New project template](https://github.com/hmans/flutterby/tree/master/lib/templates/new_project/site) (used with `flutterby new`)
+- [Source of hmans.io](https://github.com/hmans/hmans_me/tree/master/site), the Flutterby main author's blog
 
+#### Blog Posts:
 
-## Notes
-
-### How does Flutterby work?
-
-#### The Basics:
-
-Flutterby reads a _source directory_ and writes a static website into a _target directory_. (It can also serve a live version of your site.)
-
-Before it writes (or serves) anything, it reads the entire contents from the source directory into a graph of plain old Ruby objects. Each of these objects represents a file (or folder) from your site.
-
-Flutterby then walks this tree to write the resulting static site, optionally _applying filters_ first. For example, `index.html.md` will be exported as `index.html` after applying a Markdown filter.
-
-These filters can be anything that modifies the Ruby object. Some examples:
-
-- Rendering Markdown to HTML
-- Parsing and executing ERB, Slim, HAML and other templating engines
-- Processing Sass, CoffeeScript and the likes
-- Leaving the current body intact, but modifying file attributes like the generated file's extension
-
-Filters can be chained at any length you require.
-
-Files and folders starting with underscores (eg. `_secret.html`) will never be exported. There's a number of special files that start with this underscore -- more on that later.
-
-#### Using Ruby in templates:
-
-Ruby code embedded in ERB, Slim etc. templates can interact with this object graph to do funky stuff like:
-
-- including the rendered contents of another object (ie. partials)
-- query the graph for certain objects (eg. "all objects in `/posts` that have `published_at` set")
-- and much more, I guess!
+- [Blog post introducing Flutterby](http://hmans.io/posts/2017/01/11/flutterby.html)
 
-#### Layout files:
 
-When a `_layout` file is available in the same folder as the rendered page, it will be used to wrap the object's rendered output. These layout files stack, so you can have a `/posts/_layout.erb` with the layout for a single post, and a `/_layout.erb` with the layout of your site.
+#### Installation & Basic Usage:
 
-#### Extending views:
+Please refer to the [Flutterby Documentation](http://www.flutterby.run/docs/).
 
-When a `_view.rb` file is available in the same folder as the rendered page, it will be evaluated against the current view object, allowing you to define your own view helpers. Like layouts, these will stack.
 
-#### Writing Ruby nodes:
+#### Contributing to Flutterby's Development:
 
-When a file has a `.rb` filter extension, the contained Ruby code will be evaluated against the Node instance. This allows you to build Ruby-based nodes. These nodes can do some powerful things, like creating other "virtual" nodes on the fly. I'm using this technique for the [archives on my blog](https://github.com/hmans/hmans_me/tree/master/site/archive).
+Please refer to [Contributing to Flutterby](http://www.flutterby.run/docs/flutterby-development/contributing-to-flutterby.html) for details.
 
-When a file named `_node.rb` is present, the contained code will be evaluated against _all_ nodes in the same directory. This allows you to easily extend multiple nodes with functionality. [I'm using this in the template project](https://github.com/hmans/flutterby/tree/master/lib/templates/new_project/site/blog) to add `#title` and `#date` methods to blog posts.
 
 
-## License
+#### License:
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/flutterby/cli.rb

@@ -82,6 +82,7 @@ module Flutterby
       say color("🏗  Creating a new Flutterby project in #{path}...", :bold)
       directory("new_project", path)
       chmod("bin/flutterby", 0755)
+      chmod("bin/rake", 0755)
       in_root { bundle_install }
     end
 

data/lib/flutterby/filters.rb

@@ -8,29 +8,31 @@ require 'flutterby/markdown_formatter'
 
 module Flutterby
   module Filters
-    def self.apply!(input, view:)
+    extend self
+
+    def apply!(input, filters, view:, &blk)
       # Apply all filters
-      view.node.filters.inject(input) do |body, filter|
+      filters.inject(input) do |body, filter|
         meth = "process_#{filter}!"
 
         if Filters.respond_to?(meth)
-          Filters.send(meth, body, view: view)
+          Filters.send(meth, body, view: view, &blk)
         elsif template = tilt(filter, body)
-          template.render(view).html_safe
+          template.render(view, view.locals, &blk).html_safe
         else
-          Flutterby.logger.warn "Unsupported filter '#{filter}' for #{view.node.url}"
+          Flutterby.logger.warn "Unsupported filter '#{filter}'"
           body
         end
       end
     end
 
-    def self.add(fmts, &blk)
+    def add(fmts, &blk)
       Array(fmts).each do |fmt|
         define_singleton_method("process_#{fmt}!", &blk)
       end
     end
 
-    def self.tilt(format, body, options = {})
+    def tilt(format, body, options = {})
       default_options = {
         "erb" => { engine_class: Erubis::Auto::EscapedEruby }
       }

data/lib/flutterby/layout.rb

@@ -2,30 +2,18 @@ module Flutterby
   module Layout
     extend self
 
-    # Determines which layouts should be applied to the view object (based on
-    # the node it is rendering), and then applies each of these layouts in order,
-    # modifying the view in place.
-    #
-    def apply!(body, view:)
-      collect_layouts(view).inject(body) do |acc, layout|
-        tilt = Flutterby::Filters.tilt(layout.ext, layout.source)
-        tilt.render(view) { acc }.html_safe
-      end
-    end
-
-    private
-
-    def collect_layouts(view)
+    def collect_layouts(node, list: nil, include_tree: true)
       layouts = []
+      list ||= node.layout
 
       # Collect layouts explicitly configured for node
-      if defined? view.node.layout
-        Array(view.node.layout).each do |sel|
+      if defined? list
+        Array(list).each do |sel|
           # If a false is explicity specified, that's all the layouts
           # we're expected to render
           return layouts if sel == false
 
-          if layout = view.node.find(sel)
+          if layout = node.find(sel)
             layouts << layout
           else
             raise "No layout found for path expression '#{sel}'"
@@ -33,13 +21,15 @@ module Flutterby
         end
       end
 
-      # Decide on a starting node for walking the tree upwards
-      start = layouts.any? ? layouts.last.parent : view.node
+      if include_tree
+        # Decide on a starting node for walking the tree upwards
+        start = layouts.any? ? layouts.last.parent : node
 
-      # Walk the tree up, collecting any layout files found on our way
-      TreeWalker.walk_up(start) do |node|
-        if layout = node.sibling("_layout")
-          layouts << layout
+        # Walk the tree up, collecting any layout files found on our way
+        TreeWalker.walk_up(start) do |n|
+          if layout = n.sibling("_layout")
+            layouts << layout
+          end
         end
       end
 

data/lib/flutterby/node.rb

@@ -330,12 +330,63 @@ module Flutterby
 
 
     module Rendering
+      # Renders the node. One of the most important methods in Flutterby, which
+      # explains why it's wholly undocumented. Apologies, I'm working on it!
+      #
+      def render(layout: false, view: nil, extra_filters: [], locals: {}, &blk)
+        # If no view was specified, create a new one for this node.
+        view ||= View.for(self, locals: locals)
+        layouts = []
+
+        if layout == true
+          # build standard list of layouts for rendering the full page
+          layouts = Layout.collect_layouts(self, include_tree: page?)
+        elsif layout
+          # build list of nodes based on specified layouts
+          layouts = Layout.collect_layouts(self, list: layout, include_tree: false)
+        end
+
+        # Start rendering
+        output = ""
+        time = Benchmark.realtime do
+          # Apply filters
+          output = Filters.apply! @source.html_safe,
+            filters + extra_filters,
+            view: view, &blk
+
+          # Apply layouts
+          output = layouts.inject(output) do |acc, layout_node|
+            layout_node.render(layout: false,
+              view: view, extra_filters: [layout_node.ext]) { acc }
+          end
+        end
+
+        # Log rendering times using different colors based on duration
+        color = if time > 1
+          :red
+        elsif time > 0.25
+          :yellow
+        else
+          :green
+        end
+
+        logger.debug "Rendered #{url.colorize(:blue)} in #{sprintf("%.1fms", time * 1000).colorize(color)}"
+
+        output
+      end
+
+
+
       # Creates a new {View} instance and uses it to
       # render this node. Returns the rendered page as a string.
       #
-      def render(opts = {})
-        View.for(self, opts).render!
-      end
+      # def render(opts = {}, &blk)
+      #   render_with_view(View.for(self, opts), &blk)
+      # end
+      #
+      # def render_with_view(view, *args, &blk)
+      #   NodeRenderer.render(self, view, *args, &blk)
+      # end
     end
 
     include Rendering

data/lib/flutterby/version.rb

@@ -1,3 +1,3 @@
 module Flutterby
-  VERSION = "0.5.2"
+  VERSION = "0.6.0"
 end

data/lib/flutterby/view.rb

@@ -3,7 +3,7 @@ require 'flutterby/layout'
 
 module Flutterby
   class View
-    attr_reader :node, :opts
+    attr_reader :node, :locals
     alias_method :page, :node
 
     # Include ERB::Util from ActiveSupport. This will provide
@@ -13,35 +13,9 @@ module Flutterby
     #
     include ERB::Util
 
-    def initialize(node, opts = {})
+    def initialize(node, locals: {})
       @node = node
-      @opts = opts
-    end
-
-    def render!
-      output = node.source.try(:html_safe)
-
-      time = Benchmark.realtime do
-        output = Filters.apply!(output, view: self)
-
-        # Apply layouts
-        if opts[:layout] && node.page?
-          output = Layout.apply!(output, view: self)
-        end
-      end
-
-      # Log rendering times using different colors based on duration
-      color = if time > 1
-        :red
-      elsif time > 0.25
-        :yellow
-      else
-        :green
-      end
-
-      logger.debug "Rendered #{node.url.colorize(:blue)} in #{sprintf("%.1fms", time * 1000).colorize(color)}"
-
-      output
+      @locals = locals
     end
 
     def date_format(date, fmt)
@@ -52,12 +26,16 @@ module Flutterby
       str.html_safe
     end
 
-    def render(expr, *args)
-      if expr.is_a?(Node)
-        expr.render(*args)
-      else
-        find(expr).render(*args)
+    def render(expr, as: nil, locals: {}, **args)
+      node = expr.is_a?(Node) ? expr : find(expr)
+
+      # Resolve rendering "as" specific things
+      if as
+        locals[as] = node
+        node = node.find!("./_#{as}.#{self.node.ext}")
       end
+
+      node.render(**args, locals: locals.with_indifferent_access, **args)
     end
 
     def find(*args)

data/lib/templates/new_project/Gemfile.tt

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
 source "https://rubygems.org"
 
+gem "rake"
 gem "flutterby", "~> <%= Flutterby::VERSION %>"

data/lib/templates/new_project/Rakefile

@@ -0,0 +1,14 @@
+task default: [:build]
+
+desc "Build the website"
+task :build do
+  system "rm -rf _build/* && bin/flutterby build"
+end
+
+# This is a sample "deploy" task that will upload your
+# statically generated website to your server via rsync.
+#
+# desc "Deploy the website"
+# task deploy: [:build] do
+#   system "rsync -vr --del _build/* server:/path/to/website/"
+# end

data/lib/templates/new_project/bin/rake

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/lib/templates/new_project/site/about.html.md

@@ -1,5 +1,5 @@
 ## About this site
 
-This is a small template site [Flutterby] generated for you. You can keep using it, modify it as you wish, or get rid of everything and start from scratch. It's up to you!
+This is a small template site [Flutterby] generated for you. You can keep using it, modify it as you wish, or get rid of everything within the `site/` directory and start from scratch. It's up to you!
 
 [Flutterby]: http://www.flutterby.run

data/lib/templates/new_project/site/blog/hello-world.html.md.tt

@@ -10,8 +10,8 @@ This sample project is set up as a simple blog, but of course you can do so much
 
 | `/_config.yaml` | Your site configuration. |
 | `/css/styles.css.scss` | Your stylesheet. [Sass]-powered, of course! |
-| `/_layout.slim` | Your global site layout. |
-| `/posts/_layout.slim` | Your post-specific layout. |
+| `/_layout.html.slim` | Your global site layout. |
+| `/posts/_layout.html.slim` | Your post-specific layout. |
 
 #### Recommended Reading
 

data/lib/templates/new_project/site/index.html.slim

@@ -1,6 +1,6 @@
 h1 = config.site.title
 
-p This is my new website! #{link_to "Find out more", "/about.html"}.
+p Hooray, you now have a Flutterby-powered website! #{link_to "Find out more", "/about.html"}.
 
 h3 Latest Posts:
 == render("/blog/_list")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: flutterby
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Hendrik Mans
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-01-25 00:00:00.000000000 Z
+date: 2017-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -402,13 +402,15 @@ files:
 - lib/templates/new_project/.gitignore
 - lib/templates/new_project/Gemfile.tt
 - lib/templates/new_project/README.md
+- lib/templates/new_project/Rakefile
 - lib/templates/new_project/bin/flutterby
+- lib/templates/new_project/bin/rake
 - lib/templates/new_project/site/_config.yaml
-- lib/templates/new_project/site/_layout.slim
+- lib/templates/new_project/site/_layout.html.slim
 - lib/templates/new_project/site/_view.rb
 - lib/templates/new_project/site/about.html.md
 - lib/templates/new_project/site/blog/_init.rb
-- lib/templates/new_project/site/blog/_layout.slim
+- lib/templates/new_project/site/blog/_layout.html.slim
 - lib/templates/new_project/site/blog/_list.html.slim
 - lib/templates/new_project/site/blog/_view.rb
 - lib/templates/new_project/site/blog/hello-world.html.md.tt