floere / contexts

# Contexts
# A Rails Plugin
#
# Feedback please to florian.hanke@gmail.com, thanks! :)
#
# This plugin is a simple alternative for components.
# It is not a full replacement, however. It aims lower, namely:
# - Sub-per-action component definitions.
# - Built-in caching.
#
# It is good, when:
# 1. You wish to define certain view parts that are used for many controller actions.
# 2. You wish to cache these view parts.
# 3. You wish to not have specific controllers to load the content for these view parts.
#
# Good use cases:
# - Checkout Cart displayed in site sidebar.
# - Explorative Elements (e.g. Top Ten Books) in Sidebars.
# - Navigational Elements on almost all pages.
# - And so on…
 
# In the view, e.g. application.haml call
render_context context_category_name
 
# Example:
render_context :left_sidebar
# In this case, the specific context is determined by the controller, just
# define the context for this controller as follows.
context context_category_name,
  default_context_name,
  [action_name, other_action_name] => action_specific_context_name,
  some_other_action_name => yet_another_action_specific_context_name # etc.
# OR by using a block
context context_category_name do
  # determine a context type as you wish (e.g. randomly), then return the context name
end
# Use top_ten_books as context for the context category left_sidebar in _all_ actions.
context :left_sidebar, :top_ten_books
# Use top_ten_books as context for the context category left_sidebar in all actions
# _except_ buy, browse and login. Use other_books_you_might_like for buy and browse,
# and welcome for the login action.
context :left_sidebar, :top_ten_books,
  [:buy, :browse] => :other_books_you_might_like,
  :login => :welcome
 
# OR if the specific context type should _not_ be determined by the controller.
render_context context_category_name, context_type_name
# This just renders the context for the top ten books in the left sidebar without
# asking the controller to determine which context type should be used for the left sidebar.
render_context :left_sidebar, :top_ten_books
 
# Loading variables for your contexts is done in the ApplicationController (or if it should not be
# available everywhere in the Controller needed)
#
# In your ApplicationController call the following to load instance variables for the context in category and type.
# Currently supported options are:
#   :cache => 7.minutes
load_context(category, type, options = {}, &loading_instance_variables_block)
 
# Example
#
load_context :left_sidebar, :top_ten_books, :cache => 5.minutes do
  @books = Books.top(10)
end

# This loads the top ten books into the variable @books, which can then be used in the partial 
contexts/left_sidebar/_top_ten_books.html.haml:
%h1 Top Ten Books
- for book in @books do
  %h2= book.title
  %p= book.description
  = link_to_add_to_cart(book)

# The context view files should be in views/contexts/<category>/<type>.html.haml (or .text.erb or
# what have you, depending on the request format)
#
# The file in the example above would be in:
# app/views/contexts/left_sidebar/top_ten_books.html.haml