blocks 3.0.0.rc7 → 3.0.0.rc8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b2c9902373a222d24d5785b7485b9fada199f43d
-  data.tar.gz: 701646e71d0644b84e3380fe2d7120165e055c21
+  metadata.gz: 1981e0556f4728292d6fc55314cd8674c9f83429
+  data.tar.gz: edb4a53aae3a6ab5aa73535f571400486b55b91b
 SHA512:
-  metadata.gz: 9c747b34bcbdc47dd542fded6ac3794a36375dc34fa4ab9301557c7cf622a241d6be4fac2df10470024efc42e948db8ba58e4e22e4be75abf8e5c1f979f244bd
-  data.tar.gz: 10b5a023ae6ce04e9f32b22f0c9c58bcc3544d6c7fd404af618c2df542f7f6cada78433d1dd4dd19793b339c69e5d400e0af0130a64f4688a46c3ff933f38db1
+  metadata.gz: 925dc6a46ada68430d4066cf8d132b428e3a28e6c5f3eb1a733b9ab78444cca28a753112f8e46fd909cb84f9087d3d5d50e2c865ba11e972654ca9c88d8a269e
+  data.tar.gz: a89b434fe46a3222c2a57c8d511b649a979702d9188db5c658fe62f8abb0490ea42d025ab1081667012c4a7322fa1d7dbfb2cea950bd791cdedcabcf4bc538f9

data/docs/_includes/custom-builders.md

@@ -34,3 +34,94 @@ If #initialize is overridden in the subclass, it must, at a minimum call super w
 
 ## Custom Builders with Helper Methods
 
+{% highlight ruby %}
+class MyCustomBuilder < Blocks.builder_class
+  def tag(*args, &block)
+    options = args.extract_options!
+
+    wrapper_html = if options.is_a?(Blocks::RuntimeContext)
+      wrapper_option =
+        options[:wrapper_option] || :wrapper_html
+      options[wrapper_option] || {}
+    else
+      options
+    end
+
+    wrapper_tag = options[:wrapper_tag]
+    if !wrapper_tag
+      first_arg = args.first
+      wrapper_tag = if first_arg.is_a?(String) || first_arg.is_a?(Symbol)
+        first_arg
+      else
+        :div
+      end
+    end
+
+    content_tag wrapper_tag, wrapper_html, &block
+  end
+end
+{% endhighlight %}
+
+```erb
+<% builder = MyCustomBuilder.new(self) %>
+<%= builder.render :my_block,
+  wrapper: :tag,
+  wrapper_tag: :h2,
+  wrapper_html: { class: 'text-muted' } do %>
+  Hello
+<% end %>
+
+<!-- OR -->
+
+<%= builder.tag :h2, class: 'text-muted' do %>
+  Hello
+<% end %>
+```
+
+```haml
+- builder = MyCustomBuilder.new(self)
+= builder.render :my_block,
+  wrapper: :tag,
+  wrapper_tag: :h2,
+  wrapper_html: { class: 'text-muted' } do
+  Hello
+
+#- OR
+
+= builder.tag :h2, class: 'text-muted' do
+  Hello
+```
+
+```ruby
+builder = MyCustomBuilder.new(self)
+builder.render :my_block,
+  wrapper: :block_wrapper,
+  wrapper_tag: :h2,
+  wrapper_html: { class: 'text-muted' } do
+  "Hello"
+end
+
+# OR
+
+builder.tag :h2, class: 'text-muted' do
+  "Hello"
+end
+```
+
+> This will produce the following output:
+
+```html
+<h2 class='text-muted'>Hello</h2>
+```
+
+One of the primary reasons one might want to create a custom builder is to provide helper methods that are isolated within the builder. These helper methods may be invoked directly on the builder object, or indirectly by using a proxy or hook or wrapper.
+
+In the example to the right, tag is declared as a method (which is almost a direct port over of the "block_wrapper" block defined in the [Templating Example for Bootstrap Cards](#extracting-out-the-wrappers) it was defined as a Block). The code has been slightly modified to allow the method to be called directly from the builder, or indirectly as a wrapper or hook for a Block.
+
+<aside class="notice">
+  At this time, it is not possible to proxy to a builder method (by using the "with" keyword) that expects / allows a block as an argument (i.e. this wouldn't be possible: 'builder.render with: :tag do "Hello" end'. This will likely change in future versions).
+</aside>
+
+<aside class="notice">
+  If the method is called indirectly, either because it is registered as a hook or wrapper for a block, the options hash that is sent in to the method will be an instance of a Blocks::RuntimeContext. If the method is called directly on the builder, the options hash will be whatever is directly passed in or default to an empty hash.
+</aside>

data/docs/_includes/defining.md

@@ -582,7 +582,7 @@ end
 My options are { a: 1 }
 ```
 
-Every block that are defined with a Ruby block or a proxy to a Block that is defined with a Ruby block (or a proxy to a proxy to ... to a block that is defined with a Ruby block) can optionally receive the merged options as a parameter.
+Every block that is defined with a Ruby block - or a proxy to a Block that is defined with a Ruby block, etc. - can optionally receive the merged options as a parameter.
 
 ## Without a Name
 
@@ -612,4 +612,4 @@ Blocks may be defined without a name. When no block name is provided, an anonymo
 
 <aside class="notice">
   This is really only useful directly within the Ruby code or when extending the Blocks::Builder class.
-</aside>
+</aside>

data/docs/_includes/hooks.md

@@ -962,7 +962,7 @@ end
 "around_all" call after
 ```
 
-"around" hooks render content that surrounds the combination of "before" hooks, "surround" content, and "after" hooks. They can be surround by "around_all" hooks.
+"around" hooks render content that surrounds the combination of "before" hooks, "surround" content, and "after" hooks. They can be surrounded by "around_all" hooks.
 
 <aside class="notice">
   Take note that the second "around" call content rendered around the first.
@@ -1209,4 +1209,4 @@ builder.after :my_block,
   with: :some_proxy_block
 ```
 
-Hooks may also be defined with a proxy to another block using the "with" keyword.
+Hooks may also be defined with a proxy to another block using the "with" keyword.

data/docs/_includes/rendering.md

@@ -198,13 +198,13 @@ end
 }
 ```
 
-Just as options can be set for a block when the block is defined, they can also be applied at render time.
+Just as options can be set for a block when the block is defined, they can also be applied at render.
 
 Options provided to the render call can be either runtime options or default options (unlike defining blocks, there is no concept for render standard options).
 
 Default options are specified within a nested hash under the key "defaults".
 
-All other options are considered to be runtime options. Runtime options provided to the render call will take precedence over all other options included runtime options set on the block definition.
+All other options are considered to be runtime options. Runtime options provided to the render call will take precedence over all other options, including runtime options set on the block definition.
 
 ### Indifferent Access
 
@@ -418,7 +418,7 @@ Though this concept is still relatively limited in its potential uses at this ti
 
 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.
+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 fewer arguments are expected by the block than are sent, Blocks will send the lesser number of arguments.
 
 See the example to the right to make better sense out of what is being explained here.
 
@@ -674,12 +674,12 @@ If the block being rendered is not a partial, it will store "object" as a key in
 <%= blocks.render a: 1, b: 2,
   partial: "a_partial" %>
 
--# and a collection
+<!-- and a collection -->
 <%= blocks.render a: 1, b: 2,
   partial: "a_partial",
   collection: [1, 2, 3] %>
 
--# rendering with a proxy
+<!-- rendering with a proxy -->
 <%= blocks.render with:
   :some_proxy %>
 ```
@@ -723,4 +723,4 @@ Blocks may be rendered without a block name.
 
 This is usually done in combination with a wrapper, a proxy, or a partial.
 
-Use this when you don't need corresponding hooks for the block to be rendered or when wanting to render a partial or a proxy block.
+Use this when you don't need corresponding hooks for the block to be rendered or when wanting to render a partial or a proxy block.

data/docs/_includes/skipping.md

@@ -180,7 +180,7 @@ 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
+  The code to the right is prerequesite 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.
@@ -400,4 +400,4 @@ 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.
+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.

data/docs/_includes/templating/bootstrap_4_cards.md

@@ -124,9 +124,9 @@ If you look at the sample markup for a card, hopefully you notice a pattern. It'
 
 While not every Bootstrap 4 card will follow this exact pattern, it is a good starting point for beginning to break down a card into pieces.
 
-The code to the right breaks down the main :card block into pieces. Now, the :card block defines the card element and renders its two components: :card_image and :card_card.
+The code to the right defines the card element and breaks the main :card block into its two components: :card_image and :card_content.
 
-The :card_image block renders the hardcoded image tag and the :card_content block sets itself up to proxy to the :card_block block. This is done in anticipation (based on having read ahead in the Bootstrap 4 Card documentation) of using something of than a card-block for the content of the card (more on this shortly).
+The :card_image block renders the hardcoded image tag and the :card_content block sets itself up to proxy to the :card_block block. This is done in anticipation (based on having read ahead in the Bootstrap 4 Card documentation) of using something other than a card-block for the content of the card (more on this shortly).
 
 ### Extracting out the Wrappers
 
@@ -750,4 +750,4 @@ In the example to the right, a team-specific version of card is created as a tem
 
 <aside class="warning">
   Take note that with the team_card template, builder.render_with_overrides is used instead of just render_with_overrides. This is forcing the two templates to render using the same Blocks::Builder instance, i.e. to share a Blocks namespace. This is what allows the overrides block for the team_card template to affect the defaults in card template.
-</aside>
+</aside>

data/docs/_includes/wrappers.md

@@ -354,7 +354,6 @@ builder.render(:my_block,
 
 ```
 With Collection:
-With Collection:
 Wrap All Start
 Wrap Each Start a
 Around Start
@@ -626,4 +625,4 @@ end
 
 ```html
 <div>Hello</div>
-```
+```

data/lib/blocks/renderers/partial_renderer.rb

@@ -13,6 +13,7 @@ module Blocks
       else
         locals.symbolize_keys
       end
+      partial = partial.to_partial_path if partial.respond_to?(:to_partial_path)
       locals[:options] = options
       view.render(layout: partial, locals: locals) do |*args|
         if overrides_and_provided_content

data/lib/blocks/version.rb

@@ -1,3 +1,3 @@
 module Blocks
-  VERSION = "3.0.0.rc7"
+  VERSION = "3.0.0.rc8"
 end

metadata

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