blocks 3.0.0.rc5 → 3.0.0.rc6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f3181343926f563e7c9ae1a5a7d4754a3e2a32fb
-  data.tar.gz: f88aa1db3c2078d5dacbea759fca59c7d9b4a1d8
+  metadata.gz: '018a7c22841a5dd37edc183e18a0a105c52dfdbb'
+  data.tar.gz: b869d230657f1eb1740a135b3a46694cd7edc737
 SHA512:
-  metadata.gz: 1720042c59c57226a0a44785b9ea646a0b79e6ff90948414d801609a3cb52253342d22772c58ec4df3a2de6959e5911c17c2e057e9fb608f2f65c5a05f344dd3
-  data.tar.gz: 975c4e0b9ee87b4a6b35d293c2006ed84941033ce97bcf92bd690a847ec97a69785df215fa33418370995a0be79637b39ab7d549b8a090d00f5d643488d70b47
+  metadata.gz: 954c8fcaa1290b02b06ecc32b1fedcf1b3f23f89fd74d2578a83763b7b53492ee43cb3af80f759f38ad19505b9f10e20eac11e6e750817373768da0e6de297a5
+  data.tar.gz: 8897465d0814eec1ac500ad1ce24616217d2a38cfef6055f7f48466a19c66be2a9b50a2024764512f38a9b19399bc4dd80050f1284bcf22f4ff641e27a532824

data/docs/_includes/configuration.md

@@ -1,3 +1,62 @@
 # Configuration
 
-TODO
+Blocks is customized by adding an initializer to config/initializers directory called blocks.rb.
+
+{% highlight erb %}
+Blocks.configure do |config|
+  # Configuration code goes here
+end
+{% endhighlight %}
+
+## Configuring Global Options
+
+Global Options are merged into the set of options generated when rendering a block or hook or wrapper for a block. They are given the lowest precedence when merging options.
+
+### Global Runtime Options
+{% highlight erb %}
+Blocks.configure do |config|
+  config.
+    global_options_set.
+    add_options runtime: {
+      a: 1, b: 2
+    }
+end
+{% endhighlight %}
+
+### Global Standard Options
+{% highlight erb %}
+Blocks.configure do |config|
+  config.
+    global_options_set.
+    add_options a: 1, b: 2
+end
+{% endhighlight %}
+
+### Global Default Options
+{% highlight erb %}
+Blocks.configure do |config|
+  config.
+    global_options_set.
+    add_options defaults: {
+      a: 1, b: 2
+    }
+end
+{% endhighlight %}
+
+## Configuring Caller ID
+{% highlight erb %}
+Blocks.configure do |config|
+  config.lookup_caller_location = true
+end
+{% endhighlight %}
+
+Caller ID is a debugging feature that is turned off by default, and should really only ever be turned on in Development mode and perhaps Test mode. It is enabled by running the configuration code to the right. Setting this flag to true will noticeably affect the execution speed of page rendering. This is because for every option that is added to a Block, a Proxy to a Block, or when rendering a block, the code will figure out what line of code triggered the setting of that option.
+
+## Configuring the Builder Class
+{% highlight erb %}
+Blocks.configure do |config|
+  config.builder_class = LayoutBuilder
+end
+{% endhighlight %}
+
+The Builder Class is Blocks::Builder by default, but can be changed to something else using this configuration option. Whatever it is changed to, the new class should be a subclass of Blocks::Builder. Configuring the Builder Class is useful when you want to add in block definitions or shared functionality for the entire application.

data/docs/_includes/custom-builders.md

@@ -1,3 +1,36 @@
 # Custom Builders
 
-TODO
+{% highlight ruby %}
+class MyCustomBuilder < Blocks.builder_class
+  def initialize(view, options={})
+    super view, options
+
+    # Additional initialization /
+    #  block definitions could happen here
+  end
+end
+{% endhighlight %}
+
+{% highlight ruby %}
+# From a controller action:
+builder = MyCustomBuilder.new(view_context)
+builder.define :some_block do
+  "Hello"
+end
+builder.render :some_block
+{% endhighlight %}
+
+> This will output "Hello"
+
+Blocks::Builder is the main class for storing information about block definitions and their corresponding hooks and wrappers.
+
+Wherever a Block is defined, or a hook is registered for a Block, or a block is skipped, or a Block is rendered, all actions will be executed on an instance of Blocks::Builder.
+
+When the "blocks" keyword is called from the view for the first time, it will instantiate a new instance of a Blocks::Builder (or a subclass of Blocks::Builder if the Blocks.builder_class is configured to something else - [See Configuring the Builder Class](#configuring-the-builder-class)).
+
+A custom builder is just a subclass of Blocks::Builder. Instead of extending the Blocks::Builder class directly though, it is usually better to extend Blocks.builder_class (which will be Blocks::Builder unless it has been configured to something else). The one general exception to this rule is on the class that is configured to be the Blocks.builder_class - this should extend Blocks::Builder directly.
+
+If #initialize is overridden in the subclass, it must, at a minimum call super with a reference to the view or view_context, and optionally, the init options hash.
+
+## Custom Builders with Helper Methods
+

data/docs/_includes/hooks.md

@@ -1111,7 +1111,63 @@ end
 
 ## With Options
 
-TODO
+```erb
+<% blocks.define :my_block,
+  a: "Block def",
+  b: "Block def" %>
+
+<% blocks.around :my_block,
+  a: "Hook def",
+  c: "Hook def" do |block, options| %>
+  Options are <%= options.inspect %>
+  <%= block.call %>
+<% end %>
+
+<%= blocks.render :my_block %>
+```
+
+```haml
+- blocks.define :my_block,
+  a: "Block def",
+  b: "Block def"
+
+- blocks.around :my_block,
+  a: "Hook def",
+  c: "Hook def" do |block, options|
+  Options are
+  = options.inspect
+  = block.call
+
+= blocks.render :my_block
+```
+
+```ruby
+# where builder is an instance
+#  of Blocks::Builder
+builder.define :my_block,
+  a: "Block def",
+  b: "Block def"
+
+builder.around :my_block,
+  a: "Hook def",
+  c: "Hook def" do |block, options|
+
+  "Options are #{options.inspect} #{block.call}"
+end
+builder.render :my_block
+```
+
+> When rendered, this will produce the following output:
+
+```
+Options are {
+  "a"=>"Hook def",
+  "c"=>"Hook def",
+  "b"=>"Block def"
+}
+```
+
+Just as Blocks may be defined with options, so too may hooks be defined with options. When the hook is rendered, these options will take a higher merge precedence than the options that were defined on the block itself. They will however take a lower merge precedence than any render items that were specified when the render call was made for the block being hooked (however, any of the reserved-keywords that are sent to the render call will have already been stripped out).
 
 ## With a Partial
 

data/docs/_includes/rendering.md

@@ -320,7 +320,111 @@ When the block definition and the render options share a duplicate key with hash
 
 ## With Parameters
 
-TODO
+```erb
+<% blocks.define :my_block do |param_1, param_2, param_3, param_4| %>
+  Param 1: <%= param_1.inspect %>
+  <br>
+  Param 2: <%= param_2.inspect %>
+  <br>
+  Param 3: <%= param_3.inspect %>
+  <br>
+  Param 4: <%= param_4.inspect %>
+  <br>
+<% end %>
+
+Without a Collection:
+<br>
+<%= blocks.render :my_block,
+  "foo", "bar", a: 1, b: 2 %>
+<br>
+With a Collection:
+<br>
+<%= blocks.render :my_block,
+  "foo", "bar", a: 1, b: 2,
+  collection: ["Item1", "Item2"] %>
+```
+
+```haml
+- blocks.define :my_block do |param_1,
+    param_2, param_3, param_4|
+  Param 1:
+  = param_1.inspect
+  %br
+  Param 2:
+  = param_2.inspect
+  %br
+  Param 3:
+  = param_3.inspect
+  %br
+  Param 4:
+  = param_4.inspect
+  %br
+
+Without a Collection:
+%br
+= blocks.render :my_block,
+  "foo", "bar", a: 1, b: 2
+%br
+With a Collection:
+%br
+= blocks.render :my_block,
+  "foo", "bar", a: 1, b: 2,
+  collection: ["Item1", "Item2"]
+```
+
+```ruby
+# where builder is an instance
+#  of Blocks::Builder
+builder.define :my_block do |param_1,
+    param_2, param_3, param_4|
+  "Param 1: #{param_1.inspect}<br>".html_safe +
+  "Param 2: #{param_2.inspect}<br>".html_safe +
+  "Param 3: #{param_3.inspect}<br>".html_safe +
+  "Param 4: #{param_4.inspect}".html_safe +
+end
+
+"Without a Collection:<br>".html_safe +
+builder.render(:my_block,
+  "foo", "bar", a: 1, b: 2) +
+"<br>With a Collection:<br>".html_safe +
+builder.render(:my_block,
+  "foo", "bar", a: 1, b: 2,
+  collection: ["Item1", "Item2"])
+```
+
+> This will produce the following output
+
+```
+Without a Collection:
+Param 1: "foo"
+Param 2: "bar"
+Param 3: {"a"=>1, "b"=>2}
+Param 4: nil
+
+With a Collection:
+Param 1: "Item1"
+Param 2: "foo"
+Param 3: "bar"
+Param 4: {"a"=>1, "b"=>2, "object"=>"Item1", "current_index"=>0}
+Param 1: "Item2"
+Param 2: "foo"
+Param 3: "bar"
+Param 4: {"a"=>1, "b"=>2, "object"=>"Item2", "current_index"=>1}
+```
+
+Blocks are also capable of taking additional parameters besides potentially the options and the item if a collection is being rendered.
+
+Though this concept is still relatively limited in its potential uses at this time (and some additional use cases probably still need to be hammered out), it can be used to pass an arbitrary number of additional parameters to a defined block.
+
+At this time, this will not do anything meaningful if the Block is defined to render a partial. However, if the Block is defined to be a Ruby block or a Proxy to a Block defined with a Ruby block, Blocks will attempt to match up the number of arguments the block expects with the number of arguments that could be sent to it from the render call.
+
+Remember, options will always be the last argument, and if rendering a collection, item will be the first. Any additional params passed to the render call will then be sent as the second argument onward, followed by the options hash. However, if less arguments are expected by the block than are to be sent, Blocks will send the less number of arguments.
+
+See the example to the right to make better sense out of what is being explained here.
+
+<aside class="notice">
+  Take note that passing a collection into the render call changes the first parameter to the block to the item in the collection and shifts the rest of the arguments over.
+</aside>
 
 ## With a Collection
 

data/docs/index.md

@@ -21,9 +21,9 @@ includes:
   - templating
   - configuration
   - custom-builders
-  - option-merging
-  - caller-id
-  - use-cases
+  #- option-merging
+  #- caller-id
+  #- use-cases
   - acknowledgements
 
 search: true

data/lib/blocks/renderers/runtime_context.rb

@@ -140,7 +140,7 @@ module Blocks
         [
           parent_runtime_context.render_options_set.clone,
           block_options_set,
-          parent_runtime_context.block_options_set.clone,
+          parent_runtime_context.block_options_set.try(:clone),
           # TODO: figure out how to deal with these - they don't technically belong here
           parent_runtime_context.proxy_options_set.clone,
           builder_options_set,

data/lib/blocks/version.rb

@@ -1,3 +1,3 @@
 module Blocks
-  VERSION = "3.0.0.rc5"
+  VERSION = "3.0.0.rc6"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: blocks
 version: !ruby/object:Gem::Version
-  version: 3.0.0.rc5
+  version: 3.0.0.rc6
 platform: ruby
 authors:
 - Andrew Hunter
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-09-18 00:00:00.000000000 Z
+date: 2017-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: call_with_params