blocks 3.0.0.rc4 → 3.0.0.rc5

data/docs/_includes/slate/assets.html

@@ -0,0 +1,34 @@
+{% assign css_url = '/' | prepend: site.css_dir | prepend: '/' | prepend: include.site_url %}
+{% assign fonts_url = '/' | prepend: site.fonts_dir | prepend: '/' %}
+{% assign js_url = '/' | prepend: site.js_dir | prepend: '/' | prepend: include.site_url %}
+{% assign images_url = '/' | prepend: site.images_dir | prepend: '/' | prepend: include.site_url %}
+<style>
+  @font-face {
+    font-family: 'slate';
+    src:url("{{ 'slate.eot?-syv14m' | prepend: fonts_url }}");
+    src:url("{{ 'slate.eot?#iefix-syv14m' | prepend: fonts_url }}") format('embedded-opentype'),
+        url("{{ 'slate.woff2?-syv14m' | prepend: fonts_url }}") format('woff2'),
+        url("{{ 'slate.woff?-syv14m' | prepend: fonts_url }}") format('woff'),
+        url("{{ 'slate.ttf?-syv14m' | prepend: fonts_url }}") format('truetype'),
+        url("{{'slate.svg?-syv14m#slate' | prepend: fonts_url }}") format('svg');
+    font-weight: normal;
+    font-style: normal;
+  }
+  /* bundle exec rougify style base16.monokai > _sass/_syntax.scss */
+  /* Rouge::Themes::Base16::Monokai.render(:scope => '.highlight') */
+</style>
+<link href="{{ 'screen.css' | prepend: css_url }}" media="screen" rel="stylesheet" type="text/css">
+<link href="{{ 'print.css' | prepend: css_url }}" media="print" rel="stylesheet" type="text/css">
+<link rel="icon" type="image/x-icon" href="{{'favicon.ico' | prepend: images_url }}">
+
+<script src="{{ 'lib/energize.js' | prepend: js_url }}"></script>
+<script src="{{ 'lib/jquery.js' | prepend: js_url }}"></script>
+<script src="{{ 'lib/jquery_ui.js' | prepend: js_url }}"></script>
+<script src="{{ 'lib/jquery.tocify.js' | prepend: js_url }}"></script>
+<script src="{{ 'lib/imagesloaded.min.js' | prepend: js_url }}"></script>
+<script src="{{ 'lib/lunr.js' | prepend: js_url }}"></script>
+<script src="{{ 'app/lang.js' | prepend: js_url }}"></script>
+{% if page.search %}
+  <script src="{{ 'app/search.js' | prepend: js_url }}"></script>
+{% endif %}
+<script src="{{ 'app/toc.js' | prepend: js_url }}"></script>

data/docs/_includes/slate/language-tabs.html

@@ -0,0 +1,11 @@
+{% if include.languages %}
+  <div class="lang-selector">
+    {% for lang in include.languages %}
+      {% if lang.is_a? Hash %}
+        <a href="#" data-language-name="{{ lang.keys.first }}">{{ lang.values.first }}</a>
+      {% else %}
+        <a href="#" data-language-name="{{ lang }}">{{ lang }}</a>
+      {% endif %}
+    {% endfor %}
+  </div>
+{% endif %}

data/docs/_includes/templating.md

@@ -0,0 +1,48 @@
+# Templating
+
+> Sample Syntax
+
+```erb
+<%= render_with_overrides partial:
+  "PATH_TO_PARTIAL" do |builder| %>
+  <!-- Perform overrides here
+        using the builder.
+        Whatever happens here
+        happens first. -->
+<% end %>
+```
+
+```haml
+= render_with_overrides partial: "PATH_TO_PARTIAL" do |b|
+  #- Perform overrides here using the builder.
+  #- Whatever happens here happens first.
+```
+
+```ruby
+builder = Blocks::Builder.new(view_context)
+builder.render_with_overrides partial:
+  "PATH_TO_PARTIAL" do |builder|
+  # Perform overrides here
+  #  using the builder.
+  #  Whatever happens here
+  #  happens first.
+end
+```
+
+Templating is one of the most powerful concepts within the Blocks gem. It is the bedrock on which reusable UI components can be built.
+
+A template is nothing more than a Rails partial (in future releases, this concept will likely expand to Ruby blocks as well) that has a reference to an instance of a Blocks::Builder object, and uses it to invoke Blocks functionality. It may consist of multiple block definitions, block render calls, block wrappers and hooks, and other content.
+
+By default, a Blocks::Builder instance will be passed in as a variable called "builder", but this can be overridden by specifying the "builder_variable" option. When rendering this template, it should produce either a standard / default definition for your template or a sample output of your template complete with dummy data.
+
+<aside class="warning">
+  This functionality can be invoked on an existing instance of a Blocks::Builder, but this should be done with caution, as all block definitions will share a namespace. For this reason, it is usually best to invoke the functionality on a new instance of a Blocks::Builder.
+</aside>
+
+However, this standard / default / sample definition can be overridden at runtime with an overrides block that will execute before the template is rendered by the code that is rendering the template.
+
+There are two ways to invoke this functionality, either using the #render_with_overrides method (also aliased as #with_template) that is injected into ActionView as a helper method, or by calling #render_with_overrides on an existing or new instance of a Blocks::Builder.
+
+<img src="{{'/templating.png' | prepend: site.images_dir | prepend: '/'}}" />
+
+{% include templating/bootstrap_4_cards.md %}

data/docs/_includes/templating/bootstrap_4_cards.md

@@ -0,0 +1,753 @@
+## Building a Bootstrap 4 Card
+
+> According to Bootstrap's documentation, a standard card has the following markup:
+
+```html
+<div class="card" style="width: 20rem;">
+  <img class="card-img-top" src="..." alt="Card image cap">
+  <div class="card-block">
+    <h4 class="card-title">Card title</h4>
+    <p class="card-text">
+      Some quick example text
+    </p>
+    <a href="#" class="btn btn-primary">Go somewhere</a>
+  </div>
+</div>
+```
+
+Templating is best demonstrated through example. In the following set of iterative examples, a template for rendering a [Bootstrap 4 Card](https://v4-alpha.getbootstrap.com/components/card/) will be defined and expanded upon with Blocks functionality.
+
+### Creating a Template
+
+> The following code would be added to a new file located at /app/views/shared/\_card.html.erb:
+
+{% highlight erb %}
+<% builder.define :card do %>
+  <div class="card" style="width: 20rem;">
+    <img class="card-img-top" src="..." alt="Card image cap">
+    <div class="card-block">
+      <h4 class="card-title">Card title</h4>
+      <p class="card-text">
+        Some quick example text
+      </p>
+      <a href="#" class="btn btn-primary">Go somewhere</a>
+    </div>
+  </div>
+<% end %>
+<%= builder.render :card %>
+{% endhighlight %}
+
+> Now, when the template is rendered, it will match the markup above exactly.
+
+```erb
+<%= render_with_overrides partial: "shared/card" %>
+<!-- Since no overrides block is provided, this
+     call is synonymous with: -->
+<%= Blocks::Builder.new(self).render(partial: "shared/card") %>
+```
+
+```haml
+= render_with_overrides partial: "shared/card"
+#- Since no overrides block is provided, this
+#-  call is synonymous with:
+= Blocks::Builder.new(self).render(partial: "shared/card")
+```
+
+```ruby
+builder = Blocks::Builder.new(view_context)
+builder.render_with_overrides partial: "shared/card"
+# Since no overrides block is provided, this
+#  call is synonymous with:
+builder.render partial: "shared/card"
+```
+
+Setting up a Template is simple. Simply create a Rails partial. That's the bare minimum that needs to be done, although an empty partial won't do anything useful.
+
+In this example, we define a block called :card and then render it using the "builder" variable that is automatically defined within the partial.
+
+Our output will match the sample markup above but that is because we have hardcoded the markup within the :card block definition. We'll need to make the block definitions more dynamic but before we do that, we should extract out more block definitions.
+
+### Extracting Out Block Definitions
+
+> /app/views/shared/\_card.html.erb:
+
+{% highlight erb %}
+<% builder.define :card do %>
+  <div class="card" style="width: 20rem;">
+    <%= builder.render :card_image %>
+    <%= builder.render :card_content %>
+  </div>
+<% end %>
+
+<% builder.define :card_image do %>
+  <img class="card-img-top" src="..." alt="Card image cap">
+<% end %>
+
+<% builder.define :card_block do %>
+  <div class="card-block">
+    <%= builder.render :card_title %>
+    <%= builder.render :card_text %>
+    <%= builder.render :card_action %>
+  </div>
+<% end %>
+
+<% builder.define :card_title do %>
+  <h4 class="card-title">Card title</h4>
+<% end %>
+
+<% builder.define :card_text do %>
+  <p class="card-text">
+    Some quick example text
+  </p>
+<% end %>
+
+<% builder.define :card_action do %>
+  <a href="#" class="btn btn-primary">Go somewhere</a>
+<% end %>
+
+<% builder.define :card_content,
+  with: :card_block %>
+
+<%= builder.render :card %>
+{% endhighlight %}
+
+> The output from rendering this template will be the same as before
+
+If you look at the sample markup for a card, hopefully you notice a pattern. It's something like this:
+
+* A Card is an element with an associated CSS class and is made up of a card image and card content
+  * A Card image is an image tag with an associated CSS class and an image path
+  * Card Content is an element with an associated CSS class and is made up of a card title, card text, and a card action
+    * A Card title is a h4 tag with an associated CSS class and text for the title
+    * Card text is a p tag with an associated CSS class and text
+    * A Card Action is a link button with associated CSS classes, a label for the button, and a path for the action.
+
+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 :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).
+
+### Extracting out the Wrappers
+
+> /app/views/shared/\_card.html.erb:
+
+{% highlight erb %}
+<% builder.define :block_wrapper,
+  defaults: {
+    wrapper_tag: :div,
+    wrapper_html: {},
+    wrapper_option: :wrapper_html
+  } do |block, options| %>
+  <%= content_tag options[:wrapper_tag],
+    options[options[:wrapper_option]],
+    &block %>
+<% end %>
+
+<% builder.define :card,
+  wrapper: :block_wrapper,
+  wrapper_option: :card_html,
+  defaults: {
+    card_html: { class: "card" },
+  } do %>
+  <%= builder.render :card_image %>
+  <%= builder.render :card_content %>
+<% end %>
+
+<% builder.define :card_image do %>
+  <img class="card-img-top" src="..." alt="Card image cap">
+<% end %>
+
+<% builder.define :card_block,
+  wrapper: :block_wrapper,
+  wrapper_option: :card_content_html,
+  defaults: {
+    card_content_html: {
+      class: "card-block"
+    }
+  } do %>
+  <%= builder.render :card_title %>
+  <%= builder.render :card_text %>
+  <%= builder.render :card_action %>
+<% end %>
+
+<% builder.define :card_title,
+  wrapper: :block_wrapper,
+  wrapper_option: :card_title_html,
+  wrapper_tag: :h4,
+  defaults: {
+    card_title_html: {
+      class: "card-title",
+    }
+  } do %>
+  Card title
+<% end %>
+
+<% builder.define :card_text,
+  wrapper: :block_wrapper,
+  wrapper_option: :card_text_html,
+  wrapper_tag: :p,
+  defaults: {
+    card_text_html: { class: "card-text" }
+  } do %>
+  Some quick example text
+<% end %>
+
+<% builder.define :card_action do %>
+  <a href="#" class="btn btn-primary">Go somewhere</a>
+<% end %>
+
+<% builder.define :card_content,
+  with: :card_block %>
+
+<%= builder.render :card %>
+{% endhighlight %}
+
+> The output from rendering this template will be the same as before
+
+Perhaps it will also be noticed that every block defined renders an HTML element with nested content. This code is ripe for extraction into a common wrapper block.
+
+In the code to the right, this is exactly what is happening. A new block is defined called :block_wrapper. The :block_wrapper block is setup to take a content_block as its first argument, which will automatically be passed in when :block_wrapper is used as a wrapper for another block. :block_wrapper also defines a couple default options, such as :wrapper_tag being set to :div, :wrapper_html being set to an empty hash, and :wrapper_option being set to :wrapper_html. These options are all used within the :block_wrapper definition, where it builds an HTML element around the content_block. The element will be the :wrapper_tag option type and have attributes specified by the option specified by the :wrapper_option option, which will be :wrapper_html by default.
+
+Because all of :block_wrapper's options are default options, they are easily overridden by the block being wrapper. For example, the :card block sets wrapper to :block_wrapper and its :wrapper_option to :card_html. Then it sets its default options for :card_html to { class: "card" }. By setting :card_html as a default option for :card, it can easily be overridden by the "render_with_overrides" call that will be demonstrated shortly.
+
+<aside class="notice">Notice that :card did not need to declare it's :wrapper_tag as :div since it is already being defaulted to :div by :block_wrapper</aside>
+
+:card_block, :card_title, and :card_text each follow the same paradigm. Notice that :card_text overrides the :wrapper_tag to :p and :card_title overrides it to :h4.
+
+<aside class="notice">This paradigm of using a block wrapper that wraps a block within an HTML element is so common, that Blocks provides a similar block by default called :content_tag_wrapper (also accessible as the constant Blocks::Builder::CONTENT_TAG_WRAPPER_BLOCK). If this automatically defined block is used instead, the code to the right would only need to change by removing the :block_wrapper definition and changing all references to :block_wrapper to Blocks::Builder::CONTENT_TAG_WRAPPER_BLOCK.</aside>
+
+<aside class="notice">The only two blocks that are not using the :block_wrapper are :card_image and :card_action. While both could utilize the :block_wrapper wrapper, it makes more sense not to do so. This will enable us to utilize Rails' link_to and image_tag helper methods instead, since links and images need a bit more fine-tuning than regular HTML elements.</aside>
+
+
+### Making the Blocks more Dynamic
+
+> /app/views/shared/\_card.html.erb:
+
+{% highlight erb %}
+<% builder.define :block_wrapper,
+  defaults: {
+    wrapper_tag: :div,
+    wrapper_html: {},
+    wrapper_option: :wrapper_html
+  } do |block, options| %>
+  <%= content_tag options[:wrapper_tag],
+    options[options[:wrapper_option]],
+    &block %>
+<% end %>
+
+<% builder.define :card,
+  wrapper: :block_wrapper,
+  wrapper_option: :card_html,
+  defaults: {
+    card_html: { class: "card" },
+  } do %>
+  <%= builder.render :card_image %>
+  <%= builder.render :card_content %>
+<% end %>
+
+<% builder.define :card_image,
+  defaults: {
+    card_image: "placeholder.jpg",
+    card_image_html: { class: "card-img-top" }
+  } do |options| %>
+  <%= image_tag options[:card_image],
+    options[:card_image_html] %>
+<% end %>
+
+<% builder.define :card_block,
+  wrapper: :block_wrapper,
+  wrapper_option: :card_block_html,
+  defaults: {
+    card_block_html: {
+      class: "card-block"
+    }
+  } do %>
+  <%= builder.render :card_title %>
+  <%= builder.render :card_text %>
+  <%= builder.render :card_action %>
+<% end %>
+
+<% builder.define :card_title,
+  wrapper: :block_wrapper,
+  wrapper_option: :card_title_html,
+  wrapper_tag: :h4,
+  defaults: {
+    card_title_html: {
+      class: "card-title",
+    },
+    card_title: "Card title"
+  } do |options| %>
+  <%= options[:card_title] %>
+<% end %>
+
+<% builder.define :card_text,
+  wrapper: :block_wrapper,
+  wrapper_option: :card_text_html,
+  wrapper_tag: :p,
+  defaults: {
+    card_text_html: { class: "card-text" },
+    card_text: "Some quick example text"
+  } do |options| %>
+  <%= options[:card_text] %>
+<% end %>
+
+<% builder.define :card_action,
+  defaults: {
+    card_action_path: '#',
+    card_action_text: 'Go somewhere',
+    card_action_html: { class: "btn btn-primary" }
+  } do |options| %>
+  <%= link_to options[:card_action_text],
+    options[:card_action_path],
+    options[:card_action_html] %>
+<% end %>
+
+<% builder.define :card_content,
+  with: :card_block %>
+
+<%= builder.render :card %>
+{% endhighlight %}
+
+> The output from rendering this template will be the same as before
+
+To round out the Bootstrap 4 Card template, we now specify each block definition that requires dynamic content in it's definition to take the options hash as a parameter. Any hardcoded context is then moved into the defaults hash for that block as an option and the Blocks gem will take. Where the hardcoded content previously was, we can now replace with dynamic code that utilizes the options hash that is passed in.
+
+Now we have a more or less complete template (though lacking in several features described in the Bootstrap 4 documentation) for rendering and customizing Bootstrap 4 Cards.
+
+### Rendering the Template with Option Overrides
+
+```erb
+<%= render_with_overrides partial: "shared/card",
+  card_html: { id: "my-card" },
+  card_action_text: "Go",
+  card_action_html: { class: "btn btn-danger" },
+  card_title: "My Title",
+  card_text: "My Text",
+  card_action_path: 'http://mobilecause.com',
+  card_image: "my-image.png" %>
+```
+
+```haml
+= render_with_overrides partial: "shared/card",
+  card_html: { id: "my-card" },
+  card_action_text: "Go",
+  card_action_html: { class: "btn btn-danger" },
+  card_title: "My Title",
+  card_text: "My Text",
+  card_action_path: 'http://mobilecause.com',
+  card_image: "my-image.png"
+```
+
+```ruby
+builder = Blocks::Builder.new(view_context,
+  card_html: { id: "my-card" },
+  card_action_text: "Go",
+  card_action_html: { class: "btn btn-danger" },
+  card_title: "My Title",
+  card_text: "My Text",
+  card_action_path: 'http://mobilecause.com',
+  card_image: "my-image.png")
+builder.render_with_overrides partial: "shared/card"
+```
+
+> The above code will output the following:
+
+```html
+<div class="card" id="my-card">
+  <img class="card-img-top"
+    src="/images/my-image.png"
+    alt="My image" />
+
+  <div class="card-block">
+    <h4 class="card-title">
+      My Title
+    </h4>
+    <p class="card-text">
+      My Text
+    </p>
+    <a class="btn btn-danger"
+      href="http://mobilecause.com">
+      Go
+    </a>
+  </div>
+</div>
+```
+
+Now that the template is defined, we can start rendering it with actual overrides. Since many of the blocks had some of their options defined as defaults, they can easily be overridden by the render_with_overrides options.
+
+<aside class="warning">
+  When calling the #render_with_overrides helper method from the view, any options that are passed in when automatically be passed to a new instance of a Blocks::Builder as init options. Therefore, if you're the one initializing the Blocks::Builder object (as is demonstrated in the Ruby example to the right), the options will need to be specified to the Blocks::Builder#new method instead of to the subsequent render_with_overrides call on the Blocks::Builder instance. This will likely be fixed in future releases.
+</aside>
+
+<aside class="notice">
+  Notice also that the wrapper div maintained both the default class and the provided style. This is because the card_html options were deep merged and there was no clash in keys.
+</aside>
+
+### Rendering the Template with Block Overrides
+
+```erb
+<%= render_with_overrides partial:
+  "shared/card" do |builder| %>
+  <% builder.define :card do %>
+    I am a complete replacement for the card
+  <% end %>
+<% end %>
+
+<%= render_with_overrides partial:
+  "shared/card" do |builder| %>
+  <%# Change card_title's tag to h2 %>
+  <% builder.define :card_title,
+    wrapper_tag: :h2,
+    card_title: "I had my wrapper tag changed" %>
+
+  <%# Change card_action's definition completely %>
+  <% builder.define :card_action do |options| %>
+    <button onclick="alert('clicked');">
+      <%= options[:card_action_text] %>
+    </button>
+  <% end %>
+  <%# turn off card_text's wrapper %>
+  <%#  and change it's definition %>
+  <% builder.define :card_text, wrapper: nil do %>
+    This is custom card text.
+  <% end %>
+<% end %>
+```
+
+```haml
+= render_with_overrides partial: "shared/card" do |builder|
+  - builder.define :card do
+    I am a complete replacement for the card
+
+= render_with_overrides partial: "shared/card" do |builder|
+  -# Change card_title's tag to h2
+  - builder.define :card_title,
+    wrapper_tag: :h2,
+    card_title: "I had my wrapper tag changed"
+
+  -# Change card_action's definition completely
+  - builder.define :card_action do |options|
+    %button{onclick: "alert('clicked');"}
+      = options[:card_action_text]
+  -# turn off card_text's wrapper
+  -#  and change it's definition
+  - builder.define :card_text,
+    wrapper: nil do
+    This is custom card text.
+```
+
+```ruby
+builder = Blocks::Builder.new(view_context)
+text = builder.render_with_overrides partial:
+  "shared/card" do |builder|
+  builder.define :card do
+    "I am a complete replacement for the card"
+  end
+end
+
+builder = Blocks::Builder.new(view_context)
+text2 = builder.render_with_overrides partial:
+  "shared/card" do |builder|
+  # Change card_title's tag to h2
+  builder.define :card_title,
+    wrapper_tag: :h2,
+    card_title: "I had my wrapper tag changed"
+
+  # Change card_action's definition completely
+  builder.define :card_action do |options|
+    %%"<button onclick='alert('clicked');'>
+      #{options[:card_action_text]}
+    </button>%.html_safe
+  end
+  # turn off card_text's wrapper
+  #  and change it's definition
+  builder.define :card_text, wrapper: nil do
+    "This is custom card text."
+  end
+end
+text + text2
+```
+
+> The above code will output the following:
+
+```html
+<div class="card">
+  I am a complete replacement for the card
+</div>
+<div class="card">
+  <img class="card-img-top"
+    src="/assets/placeholder.jpg"
+    alt="Placeholder">
+  <div class="card-block">
+    <h2 class="card-title">
+      I had my wrapper tag changed
+    </h2>
+    This is custom card text.
+    <button onclick="alert('clicked');">
+      Go somewhere
+    </button>
+  </div>
+</div>
+```
+
+Finding the option overrides aren't enough? There's always block overrides. Any block defined within the template can be overridden by an overrides block that executes before the template is rendered.
+
+### Hooking and Skipping Template Definitions
+
+> The following code would be added to /app/views/shared/\_card.html.erb, just before the builder.render :card call:
+
+{% highlight erb %}
+<% builder.define :card_subtitle,
+  wrapper: :block_wrapper,
+  wrapper_option: :card_subtitle_html,
+  wrapper_tag: :h6,
+  defaults: {
+    card_subtitle_html: {
+      class: "card-subtitle mb-2 text-muted"
+    },
+    card_subtitle: "Card subtitle"
+  } do |options| %>
+  <%= options[:card_subtitle] %>
+<% end %>
+
+<% builder.define :card_list_group,
+  wrapper: :block_wrapper,
+  wrapper_option: :card_list_group_html,
+  wrapper_tag: :ul,
+  defaults: {
+    card_list_group_html: {
+      class: "list-group list-group-flush"
+    }
+  } %>
+
+<% builder.define :card_list_group_item,
+  wrapper: :block_wrapper,
+  wrapper_option: :card_list_group_item_html,
+  wrapper_tag: :li,
+  defaults: {
+    card_list_group_item_html: {
+      class: "list-group-item"
+    },
+    card_list_group_item: "Item"
+  } do |options| %>
+  <%= options[:card_list_group_item] %>
+<% end %>
+
+<% builder.define :card_header,
+  wrapper: :block_wrapper,
+  wrapper_option: :card_header_html,
+  defaults: {
+    card_header_html: {
+      class: "card-header"
+    },
+    card_header: "Card Header"
+  } do |options| %>
+  <%= options[:card_header] %>
+<% end %>
+
+<% builder.define :card_footer,
+  wrapper: :block_wrapper,
+  wrapper_option: :card_footer_html,
+  defaults: {
+    card_footer_html: {
+      class: "card-footer"
+    },
+    card_footer: "Card Footer"
+  } do |options| %>
+  <%= options[:card_footer] %>
+<% end %>
+{% endhighlight %}
+
+```erb
+<%= render_with_overrides partial:
+  "shared/card" do |builder| %>
+  <% builder.skip :card_image %>
+  <% builder.after :card_title do %>
+    <%= builder.render :card_subtitle %>
+  <% end %>
+  <% builder.prepend :card do %>
+    <%= builder.render :card_header %>
+  <% end %>
+  <% builder.append :card do %>
+    <%= builder.render :card_footer %>
+  <% end %>
+  <% builder.define :card_content,
+    with: :card_list_group %>
+  <% builder.append :card_content do %>
+    <%= builder.render :card_list_group_item,
+      card_list_group_item: "Item 1" %>
+  <% end %>
+
+  <% builder.prepend :card_content do %>
+    <%= builder.render :card_list_group_item,
+      card_list_group_item: "Item 0" %>
+  <% end %>
+<% end %>
+```
+
+```haml
+= render_with_overrides partial: "shared/card" do |builder|
+  - builder.skip :card_image
+  - builder.after :card_title do
+    = builder.render :card_subtitle
+  - builder.prepend :card do
+    = builder.render :card_header
+  - builder.append :card do
+    = builder.render :card_footer
+  - builder.define :card_content,
+    with: :card_list_group
+  - builder.append :card_content do
+    = builder.render :card_list_group_item,
+      card_list_group_item: "Item 1"
+  - builder.prepend :card_content do
+    = builder.render :card_list_group_item,
+      card_list_group_item: "Item 0"
+```
+
+```ruby
+builder = Blocks::Builder.new(view_context)
+builder.render_with_overrides partial:
+  "shared/card" do |builder|
+  builder.skip :card_image
+  builder.after :card_title do
+    builder.render :card_subtitle
+  end
+  builder.prepend :card do
+    builder.render :card_header
+  end
+  builder.append :card do
+    builder.render :card_footer
+  end
+  builder.define :card_content,
+    with: :card_list_group
+  builder.append :card_content do
+    builder.render :card_list_group_item,
+      card_list_group_item: "Item 1"
+  end
+
+  builder.prepend :card_content do
+    builder.render :card_list_group_item,
+      card_list_group_item: "Item 0"
+  end
+end
+```
+
+> The above code will output the following:
+
+```html
+<div class="card">
+  <div class="card-header">
+    Card Header
+  </div>
+  <ul class="list-group list-group-flush">
+    <li class="list-group-item">
+      Item 0
+    </li>
+    <li class="list-group-item">
+      Item 1
+    </li>
+  </ul>
+  <div class="card-footer">
+    Card Footer
+  </div>
+</div>
+```
+Scanning through the Bootstrap 4 Cards documentation, it can be plainly observed that the current card template only scratches the surface of available features for cards. In the code to the right, a few of these features are added to the template: :card_subtitle, :card_list_group with :card_list_group_item's, :card_header, and :card_footer. Though all of these features are defined as blocks, none of them are actually used by default. This is actually a good approach, in that these additional features can be added or swapped in as desired while the default output will be unaffected.
+
+We also have access to the full arsenal of hooks, wrapper with relation to the various block definitions within the template. We can also skip blocks or replace the definitions with new definitions.
+
+### Extending the Template
+
+> Assume the following partial exists in /app/views/shared/\_team_card.html.erb:
+
+{% highlight erb %}
+<%= builder.render_with_overrides partial:
+  "shared/card" do |builder| %>
+  <% builder.define :card_title,
+    card_title: team.name %>
+  <% builder.define :card_text,
+    card_text: team.description %>
+  <% builder.define :card_action,
+    card_action_text: 'Donate' %>
+<% end %>
+{% endhighlight %}
+
+> Then when the following code runs:
+
+```erb
+<% team = OpenStruct.new(
+  name: "Andrew's Campaign",
+  npo: "Innogive",
+  description: "Donate money"
+) %>
+<%= render_with_overrides partial:
+  "shared/team_card",
+  team: team do |builder| %>
+  <% builder.after :card_title,
+    with: :card_subtitle,
+    card_subtitle: team.npo %>
+<% end %>
+```
+
+```haml
+- team = OpenStruct.new(name: "Andrew's Campaign",
+  npo: "Innogive",
+  description: "Donate money")
+= render_with_overrides partial: "shared/team_card",
+  team: team do |builder|
+  - builder.after :card_title do
+    = builder.render :card_subtitle,
+      card_subtitle: team.npo
+```
+
+```ruby
+team = OpenStruct.new(
+  name: "Andrew's Campaign",
+  npo: "Innogive",
+  description: "Donate money"
+)
+builder = Blocks::Builder.new(view_context)
+builder.render_with_overrides partial:
+  "shared/team_card",
+  team: team do |builder|
+    builder.after :card_title do
+      builder.render :card_subtitle,
+        card_subtitle: team.npo
+    end
+end
+```
+
+> It will produce the following output:
+
+```html
+<div class="card">
+  <img class="card-img-top"
+    src="/assets/placeholder.jpg"
+    alt="Placeholder">
+  <div class="card-block">
+    <h4 class="card-title">
+      Andrew's Campaign
+    </h4>
+    <h6 class="card-subtitle mb-2 text-muted">
+      Innogive
+    </h6>
+    <p class="card-text">
+      Donate money
+    </p>
+    <a class="btn btn-primary" href="#">
+      Donate
+    </a>
+  </div>
+</div>
+```
+
+Templates may also be extended to form new templates, which may also be extended as many times as necessary.
+
+An example might be create new templates that render different versions of a card. For example, maybe one type of card is detailed, while another is an overview. Or maybe one type of card displays information about a team and another about an organization. Or maybe one is meant for conveying information on a dashboard while the other in meant purely for frontend pages. Perhaps then the dashboard card template could be extended multiple times as well to represent different types of objects that may be displayed on the dashboard.
+
+In the example to the right, a team-specific version of card is created as a template. Code then renders this new template with some overrides of if its own. The overrides have been kept very basic in order to clearly demonstrate how to setup a template that extends another template.
+
+<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>