blocks 3.0.0.rc4 → 3.0.0.rc5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1e022666ec160d8b6eee526393d150b0b84c6af8
-  data.tar.gz: 41b615d2770f0e0a065a9a86db133b9bc89c5f97
+  metadata.gz: f3181343926f563e7c9ae1a5a7d4754a3e2a32fb
+  data.tar.gz: f88aa1db3c2078d5dacbea759fca59c7d9b4a1d8
 SHA512:
-  metadata.gz: a37e882249043b9651fda7c422eb3e9af4714d205ad71bdf7377d368744508e342b60829434c47471ab08be0e7d62922b9b5e7767e40f5031d2a1da2f5d65f2b
-  data.tar.gz: 39da51207e66968d0e1d4df45ce8de3f2a483fb5b59a6689b93b0d7e84d43d2fb3277463d2d79bd31577de04a821bcaa24b0d281279d496d235d46839f886c08
+  metadata.gz: 1720042c59c57226a0a44785b9ea646a0b79e6ff90948414d801609a3cb52253342d22772c58ec4df3a2de6959e5911c17c2e057e9fb608f2f65c5a05f344dd3
+  data.tar.gz: 975c4e0b9ee87b4a6b35d293c2006ed84941033ce97bcf92bd690a847ec97a69785df215fa33418370995a0be79637b39ab7d549b8a090d00f5d643488d70b47

data/.gitignore

@@ -1,7 +1,9 @@
 /pkg/*
 .bundle
-.ruby-version
 .ruby-gemset
 Gemfile.lock
 .byebug_history
-coverage/
+coverage/
+_site/
+.sass-cache/
+.idea/

data/.ruby-version

@@ -0,0 +1 @@
+2.4

data/.travis.yml

@@ -1,6 +1,9 @@
 language: ruby
 cache: bundler
 
+before_install:
+  - gem update bundler
+
 rvm:
   - 1.9.3
   - 2.0.0

data/CHANGELOG.rdoc

@@ -1,3 +1,10 @@
+3.0.0 ()
+* Complete rewrite of the blocks gem
+* Extensive test coverage added
+* Jenkins CI integration
+* Extensive documentation added: http://hunterae.github.io/blocks/
+* Blocks branding and documentation styling applied: Thanks [Alexis Gormley](https://github.com/n2diving)
+
 2.8.0 (January 21, 2016)
 * When rendering a collection of blocks through blocks.render BLOCK_NAME, collection: COLLECTION,
 current_index will now be passed as a param for the options hash passed to the block. Example:

data/Gemfile

@@ -7,13 +7,20 @@ gem "capybara"
 gem "rspec", "~> 3.6.0"
 gem "arel", github: "rails/arel"
 gem "rails", github: "rails/rails"
-gem 'rack'
+gem "rack"
 gem "shoulda-matchers", "~> 2.0"
 gem "haml"
 
 # Extra development utilities
-gem 'ruby_dep'
-gem 'guard-rspec', '~> 4.7'
+gem "ruby_dep"
+gem "guard-rspec", "~> 4.7"
 gem "terminal-notifier-guard"
 gem "byebug"
 gem "codeclimate-test-reporter", "~> 1.0.8"
+
+group :development, :test do
+  gem "jekyll"
+  gem "jgd"
+  gem "jekyll-feed", "~> 0.6"
+  gem "jekyll-coffeescript"
+end

data/README.md

@@ -1,8 +1,23 @@
 # Blocks
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/blocks`. To experiment with that code, run `bin/console` for an interactive prompt.
+The Blocks gem is many things.
 
-TODO: Delete this and the text above, and describe your gem
+It acts as:
+
+* a container for reusable blocks of code and options
+* a common interface for rendering code, whether the code was defined previously in Ruby blocks, Rails partials, or proxies to other blocks of code
+* a series of hooks and wrappers that can be utilized to render code before, after, and around other blocks of code, as well as before each, after each, and around each item in a collection
+* a templating utility for easily building reusable and highly customizable UI components
+* a means for DRYing up oft-repeated code in your layouts and views
+* a simple mechanism for changing or skipping the rendering behavior for particular blocks of code
+
+Essentially, this all boils down to the following: Blocks makes it easy to define blocks of code that can be rendered either verbatim or with replacements and modifications at some later point in time.
+
+[![Build Status](https://travis-ci.org/hunterae/blocks.svg?branch=3-0-stable)](https://travis-ci.org/hunterae/blocks)
+
+## Usage
+
+Please checkout the documentation for the Blocks gem here: http://hunterae.github.io/blocks/.
 
 ## Installation
 
@@ -20,20 +35,21 @@ Or install it yourself as:
 
     $ gem install blocks
 
-## Usage
+## Development
 
-TODO: Write usage instructions here
+After checking out the repo, run `bundle install` (and possibly `gem install bundler` if you don't already have bundler installed) to install dependencies. Then, run `rake` to run the tests. You can also run `bundle console` for an interactive prompt that will allow you to experiment.
 
-## Development
+## Documentation
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+The documentation is generated using [Jekyll](https://jekyllrb.com/) and hosted on the [Blocks gh-pages branch](https://github.com/hunterae/blocks/tree/gh-pages).
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+The static content is generated based on the source code within the [docs directory](https://github.com/hunterae/blocks/tree/3-0-stable/docs).
 
-## Contributing
+To run the documentation locally or make changes for a corresponding pull request, follow the steps in the [Development Section above](#development). Then run `jekyll serve` and visit http://127.0.0.1:4000/blocks/.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/blocks.
+## Contributing
 
+Bug reports and pull requests are welcome on GitHub at https://github.com/hunterae/blocks.
 
 ## License
 

data/_config.yml

@@ -0,0 +1,20 @@
+title: Blocks Docs
+email: hunterae@gmail.com
+description: Blocks gives you total control over how your blocks of code render.
+baseurl: "/blocks" # the subpath of your site, e.g. /blog
+url: "" # the base hostname & protocol for your site, e.g. http://example.com
+github_username: hunterae
+google_analytics: "UA-104699666-1"
+markdown: kramdown
+source: docs
+destination: _site
+plugins:
+  - jekyll-feed
+  - jekyll-coffeescript
+sass:
+  sass_dir: _sass
+  style: compressed
+css_dir: blocks/stylesheets
+js_dir: blocks/javascripts
+images_dir: blocks/images
+fonts_dir: blocks/fonts

data/bin/deploy_docs

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+jgd -r 3-0-stable

data/docs/.gitignore

@@ -0,0 +1,4 @@
+_site
+.sass-cache
+.jekyll-metadata
+.asset-cache

data/docs/404.html

@@ -0,0 +1,23 @@
+---
+---
+
+<style type="text/css" media="screen">
+  .container {
+    margin: 10px auto;
+    max-width: 600px;
+    text-align: center;
+  }
+  h1 {
+    margin: 30px 0;
+    font-size: 4em;
+    line-height: 1;
+    letter-spacing: -1px;
+  }
+</style>
+
+<div class="container">
+  <h1>404</h1>
+
+  <p><strong>Page not found :(</strong></p>
+  <p>The requested page could not be found.</p>
+</div>

data/docs/_includes/acknowledgements.md

@@ -0,0 +1,13 @@
+# Acknowledgements
+
+The [blocks gem](http://github.com/hunterae/blocks) was written and is maintained by [Andrew Hunter](http://github.com/hunterae).
+
+If you think this looks somewhat familiar, there's good reason for that. Any similarities you may notice with [Rails's content_for with yield](http://api.rubyonrails.org/classes/ActionView/Helpers/CaptureHelper.html#method-i-content_for) and [rendering partials in Rails](https://apidock.com/rails/ActionController/Base/render) are intentional (the proxying feature may even remind you of [Ruby's Forwardable Module](http://ruby-doc.org/stdlib-2.0.0/libdoc/forwardable/rdoc/Forwardable.html)). Part of the original reasoning for the creating this gem was to provide a common interface for rendering both Ruby blocks and Rails' partials.
+
+Special thanks to the following people for helping advance this gem and its corresponding documentation forward:
+
+* [Todd Fisher](https://github.com/taf2) - For helping me visualize and create the initial inception of this gem back in 2011 and understand how Ruby blocks work
+* [Jon Phillips](https://github.com/elguapo1611) - For helping me work out syntax and use cases for the Blocks gem
+* [Various people and teams at LivingSocial](https://www.livingsocial.com/) - For allowing and believing in me to run with an experimental and unproven technology to help my gem start to take shape into what it is today.
+* [Various people at MobileCause](https://www.mobilecause.com/) - For helping me to advance my vision for this gem into what it is today and what is being documented here.
+* [Alexis Gormley](https://github.com/n2diving) - For suggesting the [Slate theme](https://github.com/lord/slate) for the documentation, designing the gem's branding, and proofing the documentation.

data/docs/_includes/caller-id.md

@@ -0,0 +1,3 @@
+# Caller ID
+
+TODO

data/docs/_includes/configuration.md

@@ -0,0 +1,3 @@
+# Configuration
+
+TODO

data/docs/_includes/custom-builders.md

@@ -0,0 +1,3 @@
+# Custom Builders
+
+TODO

data/docs/_includes/defining.md

@@ -0,0 +1,615 @@
+# Defining Blocks
+
+```erb
+<% blocks.define :my_block %>
+<!-- OR -->
+<% blocks.define "my_block" %>
+```
+
+```haml
+- blocks.define :my_block
+#- OR
+- blocks.define "my_block"
+```
+
+```ruby
+# where builder is an instance
+#  of Blocks::Builder
+builder.define :my_block
+# OR
+builder.define "my_block"
+```
+
+With Blocks, you can define a block of code for later rendering using Ruby blocks, Rails partials, and proxies to other blocks.
+
+A block consists of a name, a hash of options, and a rendering strategy (also called its definition).
+
+A block's name can be a symbol or a string. The underlying system treats symbols and strings the same. Therefore, any block that is defined with a String name can be accessed with its corresponding symbol name and vice-versa.
+
+## With a Ruby Block
+
+```erb
+<% blocks.define :my_block do %>
+  content
+<% end %>
+```
+
+```haml
+- blocks.define :my_block do
+  content
+```
+
+```ruby
+# where builder is an instance
+#  of Blocks::Builder
+builder.define :my_block do
+  "content"
+end
+```
+
+A Block may be defined as a standard Ruby block.
+
+### With a Proc
+
+```erb
+<% my_block =
+  Proc.new { "content" } %>
+<% blocks.define :my_block,
+          block: my_block %>
+<!-- OR -->
+<% blocks.define :my_block,
+                 &my_block %>
+```
+
+```haml
+- my_block = Proc.new { "content" }
+- blocks.define :my_block,
+         block: my_block
+-# OR
+- blocks.define :my_block, &my_block
+```
+
+```ruby
+# where builder is an instance
+#  of Blocks::Builder
+my_block = Proc.new { "content" }
+builder.define :my_block,
+  block: my_block
+#OR...
+builder.define :my_block, &my_block
+```
+
+It may also be defined with a Proc
+
+### With a Lambda
+
+```erb
+<% my_block = lambda { "content" } %>
+<% blocks.define :my_block,
+          block: my_block %>
+<!-- OR -->
+<% blocks.define :my_block, &my_block %>
+```
+
+```haml
+Lambdas are kind of a pain in Haml
+and Procs should be used instead
+```
+
+```ruby
+# where builder is an instance
+#  of Blocks::Builder
+my_block = lambda { "content" }
+builder.define :my_block,
+  block: my_block
+# OR...
+builder.define :my_block, &my_block
+```
+
+It may also be defined with a Lambda
+
+## With a Rails Partial
+
+```erb
+<%= blocks.define :my_block,
+         partial: "my_partial" %>
+```
+
+```haml
+- blocks.define :my_block,
+       partial: "my_partial"
+```
+
+```ruby
+# where builder is an instance
+#  of Blocks::Builder
+- builder.define :my_block,
+        partial: "my_partial"
+```
+
+A Block may be defined as a Rails partial using the "partial" keyword in the parameters. Whenever the Block gets rendered, the partial actually gets rendered.
+
+## With a Proxy to Another Block
+
+```erb
+<% blocks.define :my_block,
+           with: :some_proxy_block %>
+```
+
+```haml
+- blocks.define :my_block,
+          with: :some_proxy_block
+```
+
+```ruby
+# where builder is an instance
+#  of Blocks::Builder
+- builder.define :my_block,
+           with: :some_proxy_block
+```
+
+A Block may be defined as a proxy to another block using the "with" keyword in the parameters.
+
+### Proxying to a method
+
+```erb
+<% builder.define :my_block,
+            with: :column %>
+```
+
+```haml
+- builder.define :my_block,
+           with: :column
+```
+
+```ruby
+builder.define :my_block,
+         with: :column
+```
+
+> Where "builder" is an instance of a class that extends Blocks::Builder and has a method called "column".
+
+The "with" keyword may also specify the name of a method that will be called on the builder instance when the block is rendered. By default, this will be an instance of Blocks::Builder.
+
+Also, a Proxy block can point to a method on the builder instance (by default, this is an instance of Blocks::Builder).
+
+### Proxying to a Proxy
+
+```erb
+<% blocks.define :my_block,
+           with: :proxy_1 %>
+<% blocks.define :proxy_1,
+           with: :proxy_2 %>
+<% blocks.define :proxy_2 do %>
+  My proxied proxied content
+<% end %>
+```
+
+```haml
+- blocks.define :my_block,
+          with: :proxy_1
+- blocks.define :proxy_1,
+          with: :proxy_2
+- blocks.define :proxy_2 do
+  My proxied proxied content
+```
+
+```ruby
+# where builder is an instance
+#  of Blocks::Builder
+builder.define :my_block,
+         with: :proxy_1
+builder.define :proxy_1,
+         with: :proxy_2
+builder.define :proxy_2 do
+  "My proxied proxied content"
+end
+```
+
+Proxy Blocks can also be chained together though separate definitions. The order of Block definitions is irrelevant - with two caveats:
+
+1. Proxies must be setup before attempting to render them
+2. If the same block name is defined multiple times with different proxy names, the first one defined will be used
+
+## With Multiple Definitions
+
+```erb
+<% blocks.define :my_block,
+        partial: "my_partial" %>
+<% blocks.define :my_block,
+        with: :my_proxy %>
+<% blocks.define :my_block do %>
+  My Block Definition
+<% end %>
+```
+
+```haml
+- blocks.define :my_block,
+       partial: "my_partial"
+- blocks.define :my_block,
+          with: :my_proxy
+- blocks.define :my_block do
+  My Block Definition
+```
+
+```ruby
+# where builder is an instance
+#  of Blocks::Builder
+builder.define :my_block,
+      partial: "my_partial"
+builder.define :my_block,
+         with: :my_proxy
+builder.define :my_block do
+  "My Block Definition"
+end
+```
+
+> :my_block will use the partial: "my_partial" when rendered
+
+When multiple definitions for the same block name are provided, Blocks will utilize the first definition to occur, whether it's a Ruby block, a Rails partial, or a Proxy to another block.
+
+## Without a Definition
+
+```erb
+<% blocks.define :my_block %>
+```
+
+```haml
+- blocks.define :my_block
+```
+
+```ruby
+# where builder is an instance
+#  of Blocks::Builder
+builder.define :my_block
+```
+
+Blocks do not need to have a definition provided. When they are rendered, no output is generated.
+
+This, in itself, is not particularly useful, but can become more and more useful when block options and hooks and wrappers are combined.
+
+## With a Collection
+
+```erb
+<% blocks.define :my_block,
+  collection: [1, 2, 3, 4] do |item| %>
+  <li>Item: <%= item %></li>
+<% end %>
+```
+
+```haml
+- blocks.define :my_block,
+  collection: [1, 2, 3, 4] do |item|
+  %li= "Item: #{item}"
+```
+
+```ruby
+# where builder is an instance
+#  of Blocks::Builder
+builder.define :my_block,
+  collection: [1, 2, 3, 4] do |item|
+  builder.content_tag :li,
+    "Item #{item}"
+end
+```
+
+A collection may be defined for a block, in which case, when that block is rendered, it will actually render the block multiple times, once for each item in the collection.
+
+<aside class="warning">
+When the block definition is a Ruby block, the block should be prepared to take each item from the collection as a parameter.
+</aside>
+
+
+### With an Alias
+
+```erb
+<% blocks.define :my_block,
+     collection: [1, 2, 3, 4],
+             as: :item,
+        partial: "my_partial" %>
+```
+
+```haml
+- blocks.define :my_block,
+    collection: [1, 2, 3, 4],
+            as: :item,
+       partial: "my_partial"
+```
+
+```ruby
+# where builder is an instance
+#  of Blocks::Builder
+builder.define :my_block,
+   collection: [1, 2, 3, 4],
+           as: :item,
+      partial: "my_partial"
+```
+
+Additionally, you can set an alias for each item in the collection as the collection is iterated over. This is done using the "as" option.
+
+If the block being rendered is a partial, it will alias each item in the collection with the specified option (i.e. the value of the "as" option will become the name of the variable available in the partial being rendered and will contain each item in the collection being rendered). Additionally, "current_index" will also be a variable that can be accessed within the partial, and will correspond to the item's index in the collection.
+
+If the block being rendered is not a partial, it will store the alias name as a key in an options hash that will be optionally passed to the block when it is rendered. Additionally, "current_index" will store the item's current index within the collection.
+
+### Without an Alias
+
+When no alias is specified and the block being rendered is a partial, it will alias each item in the collection as "object" (i.e. "object" will become the name of the variable available in the partial being rendered and will contain each item in the collection being rendered).
+Additionally, "current_index" will also be a variable that can be accessed within the partial, and will correspond to the item's index in the collection.
+
+If the block being rendered is not a partial, it will store "object" as a key in an options hash that will be optionally passed to the block when it is rendered. Additionally, "current_index" will store the item's current index within the collection.
+
+## With Options
+
+```erb
+<% blocks.define :my_block,
+  a: "First setting of a" %>
+<% blocks.define :my_block,
+  a: "Second setting of a",
+  b: "First setting of b" %>
+<% blocks.define :my_block,
+  a: "Third setting of a",
+  b: "Second setting setting of b",
+  c: "First setting of c" %>
+```
+
+```haml
+- blocks.define :my_block,
+  a: "First setting of a"
+- blocks.define :my_block,
+  a: "Second setting of a",
+  b: "First setting of b"
+- blocks.define :my_block,
+  a: "Third setting of a",
+  b: "Second setting setting of b",
+  c: "First setting of c"
+```
+
+```ruby
+# where builder is an instance
+#  of Blocks::Builder
+builder.define :my_block,
+  a: "First setting of a"
+builder.define :my_block,
+  a: "Second setting of a",
+  b: "First setting of b"
+builder.define :my_block,
+  a: "Third setting of a",
+  b: "Second setting setting of b",
+  c: "First setting of c"
+```
+
+> After running the above code, the options for :my_block will look like this:
+
+```JavaScript
+{
+  a: "First setting of a",
+  b: "First setting of b",
+  c: "First setting of c"
+}
+```
+
+Blocks are maintaining a merged, mutable options hash. This set is mutated with repeated calls to "define".
+
+When the same option key is used in successive "define" calls, the first call to define a key's value is given priority.
+
+### Indifferent Access
+
+```erb
+<% blocks.define :my_block,
+  a: "First setting of a",
+  "b" => "First setting of b" %>
+<% blocks.define :my_block,
+  "a" => "Second setting of a",
+  b: "Second setting of b" %>
+```
+
+```haml
+- blocks.define :my_block,
+  a: "First setting of a",
+  "b" => "First setting of b"
+- blocks.define :my_block,
+  "a" => "Second setting of a",
+  b: "Second setting of b"
+```
+
+```ruby
+# where builder is an instance of
+#  Blocks::Builder
+builder.define :my_block,
+  a: "First setting of a",
+  "b" => "First setting of b"
+builder.define :my_block,
+  "a" => "Second setting of a",
+  b: "First setting of b"
+```
+
+> After running the above code, the options for :my_block will look like this:
+
+```JavaScript
+{
+  a: "First setting of a",
+  b: "First setting of b"
+}
+```
+
+Like the name of the block itself, the options hash does not care whether a symbol or a string is provided as a hash key; they are treated the same.
+
+### Deep Merging of Options
+
+```erb
+<% blocks.define :my_block,
+              a: 1,
+     shared_key: {
+       a: "a1"
+     } %>
+<% blocks.define :my_block,
+              b: 1,
+     shared_key: {
+       a: "a2",
+       b: "b1"
+     } %>
+```
+
+```haml
+- blocks.define :my_block,
+             a: 1,
+    shared_key: { a: "a1" }
+- blocks.define :my_block,
+             b: 1,
+    shared_key: { a: "a2",
+                  b: "b1" }
+```
+
+```ruby
+# where builder is an instance of
+#  Blocks::Builder
+builder.define :my_block,
+            a: 1,
+   shared_key: {
+     a: "a1"
+   }
+builder.define :my_block,
+            b: 1,
+   shared_key: {
+     a: "a2",
+     b: "b1"
+   }
+```
+
+> After running the above code, the options for :my_block will look like this:
+
+```JavaScript
+{
+  a: 1,
+  shared_key: {
+    a: "a1",
+    b: "b1"
+  },
+  b: 1
+}
+```
+
+When the same option key is used in successive "define" calls and the values for the duplicate key are both hashes, they are deep merged, giving precedence for duplicate nested keys to whatever key was defined first.
+
+### Runtime and Default Options
+
+```erb
+<% blocks.define :my_block,
+  a: "standard",
+  b: "standard",
+  runtime: {
+    a: "runtime",
+    c: "runtime"
+  },
+  defaults: {
+    a: "default",
+    d: "default"
+  } %>
+```
+
+```haml
+- blocks.define :my_block,
+  a: "standard",
+  b: "standard",
+  runtime: { a: "runtime",
+             c: "runtime" },
+  defaults: { a: "default",
+              d: "default" }
+```
+
+```ruby
+# where builder is an instance of
+#  Blocks::Builder
+builder.define :my_block,
+  a: "standard",
+  b: "standard",
+  runtime: {
+    a: "runtime",
+    c: "runtime"
+  },
+  defaults: {
+    a: "default",
+    d: "default"
+  }
+```
+
+> After running the above code, the options for :my_block will look like this:
+
+```JavaScript
+{
+  a: "runtime",
+  c: "runtime",
+  b: "standard",
+  d: "default"
+}
+```
+
+There are three levels of options: runtime, standard, and default. They are given merge precedence in that order.
+
+Runtime options are specified as a nested hash with "runtime" as the key.
+
+Default options are specified as a nested hash with "defaults" as the key.
+
+All other keys in the hash are considered standard options.
+
+## With Parameters
+
+```erb
+<% blocks.define :my_block,
+  a: 1 do |options| %>
+  My options are <%= options.inspect %>
+<% end %>
+```
+
+```haml
+- blocks.define :my_block,
+  a: 1 do |options|
+  My options are
+  = options.inspect
+```
+
+```ruby
+# where builder is an instance of
+#  Blocks::Builder
+builder.define :my_block,
+  a: 1 do |options|
+  "My options are #{options.inspect}"
+end
+```
+> If this block were rendered, the output would be:
+
+```
+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.
+
+## Without a Name
+
+```erb
+See Ruby tab
+```
+
+```haml
+See Ruby tab
+```
+
+```ruby
+# where builder is an instance of
+#  Blocks::Builder
+anonymous_block = builder.define do
+  "hello"
+end
+
+puts anonymous_block.name
+# Outputs "anonymous_block_1"
+
+puts anonymous_block.anonymous
+# Outputs true
+```
+
+Blocks may be defined without a name. When no block name is provided, an anonymous name will be generated.
+
+<aside class="notice">
+  This is really only useful directly within the Ruby code or when extending the Blocks::Builder class.
+</aside>