blocks 3.0.0.rc4 → 3.0.0.rc5

data/docs/_includes/reserved-keywords.md

@@ -0,0 +1,59 @@
+# Reserved Keywords
+
+Whether defining a block, defining options for a block, rendering a block, registering hooks for a block, configuring global options for Blocks, or initializing an instance of a Blocks::Builder, there are certain keywords which are reserved for specific purposes:
+
+## "collection" and "as" and "object" and "current_index"
+
+"collection" is used to designate a collection for a block. When the block is rendered, it will be rendered for each item in the collection, and the "collection" option will be extracted from the options hash.
+
+"as" is used to give each item in the collection an alias as it is being iterated over. "as" will default to "object", meaning that "object" becomes a reserved keyword by default. If "as" is set to some other value, whatever that value is will become a reserved keyword for that block.
+
+"current_index" will be a zero-based index of the current item's position within the collection.
+
+## "with"
+
+"with" is used to specify the proxy render strategy, where its value is name of the other block to be rendered in its place.
+
+## "partial"
+
+"partial" is used to specify the Rails partial render strategy, where its value is the Rails partial to render.
+
+### Other Reserved Keywords when using a partial
+
+http://www.rubymagic.org/posts/ruby-and-rails-reserved-words
+
+## "block"
+
+"block" can be used to specify the Ruby block render strategy, where its value is the Ruby block to render. This is an alternative to specifying the block using the "do ... end" syntax.
+
+## "defaults"
+
+"defaults", if specified, must have its value be a hash. These represent default options, which are given a lower precedence than standard options when merging options.
+
+## "runtime"
+
+"runtime", if specified, must have its value be a hash. These represent runtime options, which are given a higher precedence than standard options when merging options.
+
+## "builder" and "builder_variable"
+
+"builder" will be the default variable name given to the instance of the Blocks::Builder passed to a partial that triggered the call to render to the possible. The "builder" can be used to invoke Blocks functionality within the partial on a shared instance of a Blocks::Builder.
+
+The name "builder" can be overridden by specifying a value in "builder_variable".
+
+## Wrappers
+
+### "wrap_all"
+
+Indicates that a wrapper will wrap around any wrap_each wrappers.
+
+### "wrap_each" / "outer_wrapper"
+
+Indicates that a wrapper will wrap around a block and any around, before, after, surround, prepend, and append hooks for that block.
+
+### "wrap_with" / "wrap" / "wrapper" / "inner_wrapper"
+
+Indicates that a wrapper will wrap around a block and any surround, prepend, and append hooks for that block.
+
+## "parent_runtime_context"
+
+Passed internally within the Blocks gem as a parent Blocks::RuntimeContext when calculating the Blocks::RuntimeContext for a hook or wrapper for a block.

data/docs/_includes/skipping.md

@@ -0,0 +1,403 @@
+# Skipping Blocks
+
+> Prerequisite code for below examples:
+
+```erb
+<% blocks.define :my_block,
+  wrap_all: :wrap_all_wrapper,
+  wrap_each: :wrap_each_wrapper,
+  wrap_with: :wrap_with_wrapper do %>
+  My Block
+  <br>
+<% end %>
+
+<% blocks.define :proxy_block do |*args| %>
+  <% options = args.extract_options! %>
+  <% item = args.shift %>
+  <%= options[:name] %>
+  <br>
+<% end %>
+
+<% blocks.define :wrapper do |b, *args| %>
+  <% options = args.extract_options! %>
+  <% item = args.shift %>
+  <%= options[:name] %> Before
+  <br>
+  <%= b.call %>
+  <%= options[:name] %> After
+  <br>
+<% end %>
+
+<% blocks.define :wrap_all_wrapper,
+  name: "wrap_all Wrapper",
+  with: :wrapper %>
+
+<% blocks.define :wrap_each_wrapper,
+  name: "wrap_each Wrapper",
+  with: :wrapper %>
+
+<% blocks.define :wrap_with_wrapper,
+  name: "wrap_with Wrapper",
+  with: :wrapper %>
+
+<% [:before_all,
+    :before,
+    :prepend,
+    :append,
+    :after,
+    :after_all].each do |hook| %>
+  <% blocks.send(hook,
+      :my_block,
+      with: :proxy_block,
+      name: "\"#{hook}\" Hook") %>
+<% end %>
+
+<% [:around_all,
+    :around,
+    :surround].each do |hook| %>
+  <% blocks.send(hook,
+      :my_block,
+      with: :wrapper,
+      name: "\"#{hook}\" Hook") %>
+<% end %>
+```
+
+```haml
+- blocks.define :my_block,
+  wrap_all: :wrap_all_wrapper,
+  wrap_each: :wrap_each_wrapper,
+  wrap_with: :wrap_with_wrapper do
+  My Block
+  %br
+
+- blocks.define :proxy_block do |*args|
+  - options = args.extract_options!
+  - item = args.shift
+  = options[:name]
+  %br
+
+- blocks.define :wrapper do |b, *args|
+  - options = args.extract_options!
+  - item = args.shift
+  = options[:name]
+  Before
+  %br
+  = b.call
+  = options[:name]
+  After
+  %br
+
+- blocks.define :wrap_all_wrapper,
+  name: "wrap_all Wrapper",
+  with: :wrapper
+
+- blocks.define :wrap_each_wrapper,
+  name: "wrap_each Wrapper",
+  with: :wrapper
+
+- blocks.define :wrap_with_wrapper,
+  name: "wrap_with Wrapper",
+  with: :wrapper
+
+- [:before_all,
+   :before,
+   :prepend,
+   :append,
+   :after,
+   :after_all].each do |hook|
+  - blocks.send(hook,
+      :my_block,
+      with: :proxy_block,
+      name: "\"#{hook}\" Hook")
+
+- [:around_all,
+   :around,
+   :surround].each do |hook|
+  - blocks.send(hook,
+      :my_block,
+      with: :wrapper,
+      name: "\"#{hook}\" Hook")
+```
+
+```ruby
+# where builder is an instance
+#  of Blocks::Builder
+builder.define :my_block,
+  wrap_all: :wrap_all_wrapper,
+  wrap_each: :wrap_each_wrapper,
+  wrap_with: :wrap_with_wrapper do
+  "My Block<br>".html_safe
+end
+
+builder.define :proxy_block do |*args|
+  options = args.extract_options!
+  item = args.shift
+  "#{options[:name]}<br>".html_safe +
+end
+
+builder.define :wrapper do |b, *args|
+  options = args.extract_options!
+  item = args.shift
+  "#{options[:name]} Before<br>".html_safe +
+  b.call +
+  "#{options[:name]} After<br>".html_safe +
+end
+
+builder.define :wrap_all_wrapper,
+  name: "wrap_all Wrapper",
+  with: :wrapper
+
+builder.define :wrap_each_wrapper,
+  name: "wrap_each Wrapper",
+  with: :wrapper
+
+builder.define :wrap_with_wrapper,
+  name: "wrap_with Wrapper",
+  with: :wrapper
+
+[:before_all,
+ :before,
+ :prepend,
+ :append,
+ :after,
+ :after_all].each do |hook|
+  builder.send(hook,
+    :my_block,
+    with: :proxy_block,
+    name: "\"#{hook}\" Hook")
+end
+
+[:around_all,
+ :around,
+ :surround].each do |hook|
+  builder.send(hook,
+    :my_block,
+    with: :wrapper,
+    name: "\"#{hook}\" Hook")
+end
+```
+
+Blocks may be skipped from rendering, such that whenever a render call occurs, no content will be rendered.
+
+<aside class="notice">
+  The code to the right is prerequistive code to the "Skipping Blocks" examples that follow
+</aside>
+
+Skips come in two forms: skipping a block only, and skipping a block with all of its hooks and wrappers.
+
+## Skipping the Block Only
+
+```erb
+<h2>Render Before Skip:</h2>
+<%= blocks.render :my_block %>
+
+<% blocks.skip :my_block %>
+<h2>Render After Skip:</h2>
+<%= blocks.render :my_block %>
+```
+
+```haml
+%h2 Render Before Skip:
+= blocks.render :my_block
+
+- blocks.skip :my_block
+%h2 Render After Skip:
+= blocks.render :my_block
+```
+
+```ruby
+output =
+  "<h2>Render Before Skip:</h2>".
+    html_safe +
+  builder.render :my_block
+
+builder.skip :my_block
+output +=
+  "<h2>Render After Skip:</h2>".
+    html_safe +
+  builder.render :my_block
+output
+```
+
+> The above code will output the following:
+
+```
+Render Before Skip:
+
+"before_all" Hook
+"around_all" Hook Before
+wrap_all Wrapper Before
+wrap_each Wrapper Before
+"around" Hook Before
+"before" Hook
+wrap_with Wrapper Before
+"surround" Hook Before
+"prepend" Hook
+My Block
+"append" Hook
+"surround" Hook After
+wrap_with Wrapper After
+"after" Hook
+"around" Hook After
+wrap_each Wrapper After
+wrap_all Wrapper After
+"around_all" Hook After
+"after_all" Hook
+
+Render After Skip:
+
+"before_all" Hook
+"around_all" Hook Before
+wrap_all Wrapper Before
+wrap_each Wrapper Before
+"around" Hook Before
+"before" Hook
+"after" Hook
+"around" Hook After
+wrap_each Wrapper After
+wrap_all Wrapper After
+"around_all" Hook After
+"after_all" Hook
+```
+
+A block may be skipped using the #skip method.
+
+Calling #skip has the effect of skipping rendering of the block itself, and any "prepend" hooks, "append" hooks, "surround" hooks, and the "wrap_with" wrapper that might have been associated with the block being skipped.
+
+Any "before" hooks, "before_all" hooks, "after" hooks, "after_all" hooks, "around" hooks, "around_all" hooks, the "wrap_all" wrapper, and the "wrap_each" wrapper will continue to be rendered when the block is skipped. See [Skipping the Block and its Hooks](#Skipping the Block and its Hooks) for skipping everything.
+
+### With a Collection
+
+```erb
+<% blocks.define :my_block,
+  collection: ["a", "b"] %>
+
+<h2>Render Before Skip:</h2>
+<%= blocks.render :my_block %>
+
+<% blocks.skip :my_block %>
+<h2>Render After Skip:</h2>
+<%= blocks.render :my_block %>
+```
+
+```haml
+- blocks.define :my_block,
+    collection: ["a", "b"]
+
+%h2 Render Before Skip:
+= blocks.render :my_block
+
+- blocks.skip :my_block
+%h2 Render After Skip:
+= blocks.render :my_block
+```
+
+```ruby
+output =
+  "<h2>Render Before Skip:</h2>".
+    html_safe +
+  builder.render :my_block
+
+builder.skip :my_block
+output +=
+  "<h2>Render After Skip:</h2>".
+    html_safe +
+  builder.render :my_block
+output
+```
+
+> The above code will output the following:
+
+```
+Render Before Skip:
+
+"before_all" Hook
+"around_all" Hook Before
+wrap_all Wrapper Before
+wrap_each Wrapper Before for item "a"
+"around" Hook Before for item "a"
+"before" Hook for item "a"
+wrap_with Wrapper Before for item "a"
+"surround" Hook Before for item "a"
+"prepend" Hook for item "a"
+My Block
+"append" Hook for item "a"
+"surround" Hook After for item "a"
+wrap_with Wrapper After for item "a"
+"after" Hook for item "a"
+"around" Hook After for item "a"
+wrap_each Wrapper After for item "a"
+wrap_each Wrapper Before for item "b"
+"around" Hook Before for item "b"
+"before" Hook for item "b"
+wrap_with Wrapper Before for item "b"
+"surround" Hook Before for item "b"
+"prepend" Hook for item "b"
+My Block
+"append" Hook for item "b"
+"surround" Hook After for item "b"
+wrap_with Wrapper After for item "b"
+"after" Hook for item "b"
+"around" Hook After for item "b"
+wrap_each Wrapper After for item "b"
+wrap_all Wrapper After
+"around_all" Hook After
+"after_all" Hook
+
+Render After Skip:
+
+"before_all" Hook
+"around_all" Hook Before
+wrap_all Wrapper Before
+wrap_each Wrapper Before for item "a"
+"around" Hook Before for item "a"
+"before" Hook for item "a"
+"after" Hook for item "a"
+"around" Hook After for item "a"
+wrap_each Wrapper After for item "a"
+wrap_each Wrapper Before for item "b"
+"around" Hook Before for item "b"
+"before" Hook for item "b"
+"after" Hook for item "b"
+"around" Hook After for item "b"
+wrap_each Wrapper After for item "b"
+wrap_all Wrapper After
+"around_all" Hook After
+"after_all" Hook
+```
+
+A block with a collection can also be skipped, though the resulting output may not be desired.
+
+Calling #skip on a block with a collection has the effect of skipping rendering of the block itself, and any "prepend" hooks, "append" hooks, "surround" hooks, and the "wrap_with" wrapper that might have been associated with the block being skipped.
+
+Any "before" hooks, "before_all" hooks, "after" hooks, "after_all" hooks, "around" hooks, "around_all" hooks, the "wrap_all" wrapper, and the "wrap_each" wrapper will continue to be rendered when the block is skipped. All the hooks and wrappers, with the exception of the "around_all", "wrap_all", "before_all", and "after_all" ones, will be rendered for each item in the collection (this behavior will likely change in a future release of Blocks).
+
+See [Skipping the Block and its Hooks](#Skipping the Block and its Hooks) for skipping everything.
+
+## Skipping the Block and its Hooks
+
+```erb
+<% blocks.skip_completely :my_block %>
+<%= blocks.render :my_block do %>
+  Hello
+<% end %>
+```
+
+```haml
+- blocks.skip_completely :my_block
+= blocks.render :my_block do
+  Hello
+```
+
+```ruby
+# where builder is an instance
+#  of Blocks::Builder
+builder.skip_completely :my_block
+builder.render :my_block do
+  "Hello"
+end
+```
+
+> There will be no output from the above command
+
+Because calling #skip can still have the effect of rendering some of the hooks and wrappers for a particular block (before, after, around, before_all, after_all, wrap_all, wrap_each will still be rendered), there is the need for a second type of skip, called #skip_completely, which will skip the block and all associated hooks and wrappers.