README

README.md

@@ -41,6 +41,11 @@ Stasis uses [Tilt](https://github.com/rtomayko/tilt) to support the following te
 Example
 -------
 
+Our [spec project](https://github.com/winton/stasis/tree/master/spec/fixtures/project) implements all the features below.
+
+Get Started
+-----------
+
 Create a directory for your project and a markup file:
 
 ### view.erb
@@ -63,10 +68,21 @@ You now have a `public` directory with rendered markup:
 Controllers
 -----------
 
-A controller defines `before` and `after` render callbacks.
-
 The only reserved filename in a Stasis project is `controller.rb`.
 
+You can have a `controller.rb` at any directory level:
+
+    controller.rb
+    index.erb
+    pages/
+      controller.rb
+      page.erb
+
+Callbacks
+---------
+
+Define `before` and `after` render callbacks within your controller:
+
 ### controller.rb
 
     # Call before any file renders
@@ -85,19 +101,16 @@ The only reserved filename in a Stasis project is `controller.rb`.
 
     Welcome to <%= @title %>!
 
-### Multiple Controllers
-
-You can have a `controller.rb` at any directory level:
+Change the Destination
+----------------------
 
-    controller.rb
-    index.erb
-    pages/
-      controller.rb
-      page.erb
+Let's say we want `view.erb` to be our front page:
 
-This allows you to better organize your callbacks.
+### controller.rb
 
-Read more about [callback execution order](https://github.com/winton/stasis/wiki/Callback-Execution-Order).
+    before 'view.erb' do
+      @destination = '/index.html'
+    end
 
 Layouts
 -------
@@ -121,25 +134,38 @@ Create the layout markup:
     end
 
     before 'layout.erb' do
-      @ignore = true
+      @destination = nil
     end
 
 We want `view.erb` to use the layout, so we set `@layout = 'layout.erb'`.
 
-We do not want a `public/layout.html` file, so we set `@ignore = true`.
+We do not want a `public/layout.html` file, so we set `@destination = nil`.
 
-Change the Path
----------------
+Helpers
+-------
 
-Let's say we want `view.erb` to be our front page.
+Define helper methods within your controllers.
 
 ### controller.rb
 
-    before 'view.erb' do
-      @path = '/'
+    helpers do
+      def active?(path)
+        @source == path
+      end
     end
 
-Adding `@path = '/'` changes the render location to `public/index.html`.
+### layout.erb
+
+    <%= active?('view.erb') %>
+
+Class Variables
+---------------
+
+To summarize, the following class variables have a special purpose in a Stasis project:
+
+* `@destination` - Get/set the destination path within `public/`
+* `@layout` - Get/set a file path to use as the layout
+* `@source` - Get/set the file path that is being rendered
 
 Continuous Rendering
 --------------------
@@ -159,25 +185,8 @@ In your browser, visit [http://localhost:3000](http://localhost:3000).
 
 In web server mode, Stasis continuously renders (`-c`).
 
-Programmatically Generate Content
----------------------------------
-
-    require 'rubygems'
-    require 'stasis'
-
-    stasis = Stasis.new '/path/to/project'
-
-    # Generate all files
-    stasis.generate '**/*'
-
-    # Generate one file
-    stasis.generate 'view.erb'
-
-    # Generate one file with extra callbacks
-    stasis.generate 'view.erb' do
-      before do
-        @path = "/custom/path"
-      end
-    end
+Other Topics:
+-------------
 
-Extra callbacks execute before any filters defined in the project.
+* [Callback Execution Order](https://github.com/winton/stasis/wiki/Callback-Execution-Order).
+* [Run Stasis Programmatically](https://github.com/winton/stasis/wiki/Run-Stasis-Programmatically)

lib/stasis.rb

@@ -30,6 +30,7 @@ def generate(*paths)
       next unless File.file?(path)
       next unless Tilt.mappings.keys.include?(File.extname(path)[1..-1])
       context = Context::Render.new rel_path
+      trigger :helpers, context, path, rel_path
       trigger :before, context, path, rel_path
       next if context.ignore
       template = Tilt.new path
@@ -56,7 +57,11 @@ def trigger(type, context, path, rel_path)
         blocks += callbacks.send(type, rel_path)
         blocks += callbacks.send(type, File.basename(rel_path))
         blocks.each do |block|
-          context.instance_eval &block
+          if type == :helpers
+            context.class.class_eval &block
+          else
+            context.instance_eval &block
+          end
         end
       end
       dir = File.expand_path('../', dir)
@@ -85,6 +90,16 @@ def before(view=nil, &block)
           @before[view]
         end
       end
+
+      def helpers(view=nil, &block)
+        @helpers ||= {}
+        @helpers[view] ||= []
+        if block
+          @helpers[view] << block
+        else
+          @helpers[view]
+        end
+      end
     end
 
     class Render

spec/fixtures/project/controller.rb

@@ -5,4 +5,10 @@
 before 'view.erb' do
   @layout = 'layout.erb'
   @title = 'My Site'
+end
+
+helpers do
+  def blah
+    '!!!'
+  end
 end

spec/fixtures/project/layout.erb

@@ -2,5 +2,5 @@
   <head>
     <title><%= @title %></title>
   </head>
-  <body><%= yield %></body>
+  <body><%= yield %><%= blah %></body>
 </html>