lotus-view 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 73dd8583d5b48a96229bf72a847120710d701d0e
-  data.tar.gz: 99c9a9ce462407779c7a14113dddd4c8129c4dfb
+  metadata.gz: 6054b04ffdb4d4b0bc17f0de1b4d239a45fa1062
+  data.tar.gz: 3fdec77bf94ab52bf27916b979661619cc053b71
 SHA512:
-  metadata.gz: 098ee9925947868c1f65424e0d443ba6722866f904ba4279fc9d9a79a9f7cb41229723b8f79ddd1aedb80dc521fb880056ce04344a8ad210175f776051a717b8
-  data.tar.gz: 3fd4ac2c4c5738c15aed901ea82df7e2fb26234df758e1eea35794721ae4f6adc50cd9d7744e8fccd38a2077e0d9eab6b2e1d64265a9f586e91fd4ba10924490
+  metadata.gz: ebf1e5d0839acda038d449cb18b9c9b12f49d7de7ec8c6460f7b4c7cef84cf685364e5d3e6ccd0882536024cc47e91f18a05f7aa6afb0cdff08587761d5f2b2f
+  data.tar.gz: 73eecc96f67474d79ca0f21f4440d10aa0a510d3172966fe3939d811c1d2d623170328140097ed81f0b17f53bc3537baff7d8f9d5c8a6955cb95e8c0d0083a9c

data/CHANGELOG.md

@@ -0,0 +1,105 @@
+## v0.2.0
+### Jun 23, 2014
+
+f053805 2014-06-20 **Luca Guidi** [breaking] Make Rendering::TemplatesFinder to look recursively for templates, starting from the root
+
+5a5ed1b 2014-06-18 **Luca Guidi** Depend on lotus-utils ~> 0.2
+
+d7858df 2014-06-18 **Luca Guidi** Ensure to handle correctly the namespace for views, when it's configured as nil
+
+8f9e876 2014-06-18 **Luca Guidi** Renamed Lotus::View methods: .duplicate => .dupe, .generate => .duplicate
+
+199c1d6 2014-06-11 **Luca Guidi** Introducing Lotus::View.generate as shortcut for .duplicate and .configure
+
+d3e65d9 2014-06-11 **Luca Guidi** Ensure lazy loading and correct namespace of the layout class when using configuration's "layout" DSL
+
+850c9b9 2014-06-11 **Luca Guidi** Specify different scenario for template name in a standalone application
+
+6199419 2014-06-06 **Luca Guidi** Ensure to return the correct template name for namespaced views
+
+71d502f 2014-06-06 **Luca Guidi** Ensure independent configurations between the framework, the views and its children. Lotus::View::Dsl.root now internally uses the configuration.
+
+dd0ec4c 2014-06-06 **Luca Guidi** Lazily load layout for Configuration. This mechanism solves eventual race conditions between the loading of the framework and the application.
+
+d2e0775 2014-06-05 **Luca Guidi** [breaking] Lotus::View can be safely duplicated. Moved views and layout registries into Configuration. Configuration is now able to duplicated and (un)load itself. Layouts can be looked up in a given Ruby namespace.
+
+a619bd2 2014-06-05 **Luca Guidi** Implemented Lotus::View::Configuration#views and #layouts
+
+e4e892e 2014-06-04 **Luca Guidi** [breaking] Removed Lotus::View's class accessor for root, in favor of the API of Lotus::View::Configuration
+
+1aa68c6 2014-06-04 **Luca Guidi** [breaking] Removed Lotus::View's class accessor for layout, in favor of the API of Lotus::View::Configuration
+
+da9bee4 2014-06-04 **Luca Guidi** Implemented Lotus::View::Configuration#layout
+
+da31e3e 2014-06-04 **Luca Guidi** Implemented Lotus::View::Configuration#load_paths
+
+1471cdd 2014-06-03 **Luca Guidi** Introduced Lotus::View::Configuration with a bare minimum behavior
+
+425c79e 2014-05-21 **Grant Ammons** Support arguments for methods inside templates
+
+d4d407b 2014-05-10 **Luca Guidi** Support Ruby 2.1.2
+
+593f1a5 2014-04-07 **Luca Guidi** Ensure outermost locals to not shadow innermost inside templates/partials. Closes #3
+
+## v0.1.0
+### Mar 23, 2014
+
+af70191 2014-03-22 **Luca Guidi** Introduced Lotus::View::MissingFormatError in order to force a rendering context to specify the requested format (mime type)
+
+320f322 2014-03-22 **Luca Guidi** Changed signature of Lotus::View.render: it now accepts only a context for the view
+
+9d5de63 2014-03-21 **Luca Guidi** Test with other engines than ERb, HAML in this case.
+
+a5ade35 2014-03-21 **Luca Guidi** Erubis is no longer a dependency.
+
+257e342 2014-03-21 **Luca Guidi** Performance: prefer `Hash#fetch(key) { default }`, over `#fetch(key, default)`.
+
+426eaf7 2014-03-21 **Luca Guidi** Allow custom rendering policies. Views can override #render and decide how to return the output.
+
+b2759f8 2014-03-18 **Luca Guidi** Lotus::View::Layout => Lotus::Layout
+
+c0c04a8 2014-03-17 **Luca Guidi** Remove private method for Presenter: #object
+
+74ca485 2014-03-13 **Luca Guidi** Introduced Lotus::Presenter
+
+0ee9c10 2014-03-13 **Luca Guidi** Render partial from a layout
+
+dc4a74f 2014-03-12 **Luca Guidi** Support for Tilt 2.0
+
+728fe70 2014-02-20 **Luca Guidi** Added Lotus::View#locals
+
+11c7e5a 2013-08-08 **Luca Guidi** Don't use global class vars.
+
+570a20c 2013-08-07 **Luca Guidi** Scope templates discovery to registered engines
+
+4b45b11 2013-08-06 **Luca Guidi** Added support for layouts.
+
+96a2c66 2013-08-02 **Luca Guidi** Allow templates to be rendered from templates.
+
+ba5acdc 2013-08-01 **Luca Guidi** Allow partials to be rendered from templates.
+
+04474d4 2013-08-01 **Luca Guidi** Render template in the Lotus::View::Rendering::Scope context
+
+d108767 2013-08-01 **Luca Guidi** Freeze at subclasses level too
+
+04a3093 2013-08-01 **Luca Guidi** Let views to specify relative template filename
+
+e7c832d 2013-08-01 **Luca Guidi** Lotus::View::Rendering::Template => Lotus::View::Template
+
+f603ea9 2013-08-01 **Luca Guidi** Rework
+
+5df49f1 2013-07-23 **Luca Guidi** Removed unnecessary indirection
+
+683741c 2013-07-22 **Luca Guidi** Views can now transparently inheriths variables from locals, in order to reuse them.
+
+3a31f63 2013-07-19 **Luca Guidi** Removed templates as class variable for views: introduced a registry for runtime resolution
+
+f27e19f 2013-07-18 **Luca Guidi** WIP rendering resolver
+
+05e1d8c 2013-07-18 **Luca Guidi** Allow views inheritance.
+
+8236523 2013-07-18 **Luca Guidi** Refactoring: Engine is not relevant, let Tilt to deal with it. View has multiple templates. Intoduced DSL for format. Introduced resolver for runtime rendering. Dependency injection. :tophat:
+
+f7f3d25 2013-07-17 **Luca Guidi** Extracted Lotus::View::Template::Finder
+
+11d3c47 2013-07-15 **Luca Guidi** Initial mess

data/README.md

@@ -8,20 +8,20 @@ A _view_ is an object that encapsulates the presentation logic of a page.
 A _template_ is a file that defines the semantic and visual elements of a page.
 In order to show a result to an user, a template must be _rendered_ by a view.
 
-Keeping things separated, helps to declutter templates and models from presentation logic.
-Also, since views are objects they are easily testable.
+Keeping things separated helps to declutter templates and models from presentation logic.
+Also, since views are objects, they are easily testable.
 If you ever used [Mustache](http://mustache.github.io/), you are already aware of the advantages.
 
-Like all the other Lotus compontents it can be used as a standalone framework, or within a full Lotus application.
+Like all the other Lotus compontents, it can be used as a standalone framework or within a full Lotus application.
 
 ## Status
 
-[![Gem Version](https://badge.fury.io/rb/lotus-view.png)](http://badge.fury.io/rb/lotus-view)
-[![Build Status](https://secure.travis-ci.org/lotus/view.png?branch=master)](http://travis-ci.org/lotus/view?branch=master)
-[![Coverage](https://coveralls.io/repos/lotus/view/badge.png?branch=master)](https://coveralls.io/r/lotus/view)
-[![Code Climate](https://codeclimate.com/github/lotus/view.png)](https://codeclimate.com/github/lotus/view)
-[![Dependencies](https://gemnasium.com/lotus/view.png)](https://gemnasium.com/lotus/view)
-[![Inline docs](http://inch-pages.github.io/github/lotus/view.png)](http://inch-pages.github.io/github/lotus/view)
+[![Gem Version](http://img.shields.io/gem/v/lotus-view.svg)](https://badge.fury.io/rb/lotus-view)
+[![Build Status](http://img.shields.io/travis/lotus/view/master.svg)](https://travis-ci.org/lotus/view?branch=master)
+[![Coverage](http://img.shields.io/coveralls/lotus/view/master.svg)](https://coveralls.io/r/lotus/view)
+[![Code Climate](http://img.shields.io/codeclimate/github/lotus/view.svg)](https://codeclimate.com/github/lotus/view)
+[![Dependencies](http://img.shields.io/gemnasium/lotus/view.svg)](https://gemnasium.com/lotus/view)
+[![Inline docs](http://inch-ci.org/github/lotus/view.svg?branch=master)](http://inch-ci.org/github/lotus/view)
 
 ## Contact
 
@@ -30,6 +30,7 @@ Like all the other Lotus compontents it can be used as a standalone framework, o
 * API Doc: http://rdoc.info/gems/lotus-view
 * Bugs/Issues: https://github.com/lotus/view/issues
 * Support: http://stackoverflow.com/questions/tagged/lotus-ruby
+* Chat: https://gitter.im/lotus/chat
 
 ## Rubies
 
@@ -53,10 +54,10 @@ Or install it yourself as:
 
 ### Conventions
 
-  * Templates are searched under `Lotus::View.root`, set this value according to your app structure (eg. `"app/templates"`).
+  * Templates are searched under `Lotus::View.configuration.root`, set this value according to your app structure (eg. `"app/templates"`).
   * A view will look for a template with a file name that is composed by its full class name (eg. `"articles/index"`).
   * A template must have two concatenated extensions: one for the format one for the engine (eg. `".html.erb"`).
-  * The framework must be loaded before to render for the first time: `Lotus::View.load!`.
+  * The framework must be loaded before rendering the first time: `Lotus::View.load!`.
 
 ### Views
 
@@ -83,10 +84,13 @@ module Articles
   end
 end
 
-Lotus::View.root = 'app/templates'
+Lotus::View.configure do
+  root 'app/templates'
+end
+
 Lotus::View.load!
 
-path     = Lotus::View.root.join('articles/index.html.erb')
+path     = Lotus::View.configuration.root.join('articles/index.html.erb')
 template = Lotus::View::Template.new(path)
 articles = ArticleRepository.all
 
@@ -109,7 +113,10 @@ module Articles
   end
 end
 
-Lotus::View.root = 'app/templates'
+Lotus::View.configure do
+  root 'app/templates'
+end
+
 Lotus::View.load!
 
 articles = ArticleRepository.all
@@ -151,13 +158,13 @@ end
 </article>
 ```
 
-All the methods defined in the view are accessible in the template:
+All the methods defined in the view are accessible from the template:
 
 ```erb
 <h2><%= authors %></h2>
 ```
 
-For convenience, they are also available as an Hash `locals` in the view.
+For convenience, they are also available to the view as a Hash, accessed through the `locals` method.
 
 ```ruby
 require 'lotus/view'
@@ -166,11 +173,11 @@ module Articles
   class Show
     include Lotus::View
 
-    # This view, already responds to `#article` because there is an element in
+    # This view already responds to `#article` because there is an element in
     # the locals with the same key.
     #
     # In order to allow developers to override those methods, and decorate a
-    # single locals object, a view has an Hash with the same values.
+    # single locals object, a view has a Hash with the same values.
     #
     # If we had implemented this method like this:
     #
@@ -232,7 +239,7 @@ Articles::Show.render({format: :custom, article: article})
 
 The builtin rendering engine is [ERb](http://en.wikipedia.org/wiki/ERuby).
 However, Lotus::View supports countless rendering engines out of the box.
-Require your library of choice **before** of requiring `'lotus/view'`, and it will just work.
+Require your library of choice **before** requiring `'lotus/view'`, and it will just work.
 
 ```ruby
 require 'haml'
@@ -369,7 +376,7 @@ For instance, if [ERubis](http://www.kuwata-lab.com/erubis/) is loaded, it will
 
 ### Root
 
-Templates lookup is performed under the `Lotus::View.root` directory. Single views can specify a different path:
+Template lookup is performed under the `Lotus::View.configuration.root` directory. You can specify a different path on a per view basis:
 
 ```ruby
 class ViewWithDifferentRoot
@@ -384,8 +391,8 @@ end
 The template file must be located under the relevant `root` and must match the class name:
 
 ```ruby
-puts Lotus::View.root     # => #<Pathname:app/templates>
-Articles::Index.template  # => "articles/index"
+puts Lotus::View.configuration.root # => #<Pathname:app/templates>
+Articles::Index.template            # => "articles/index"
 ```
 
 Each view can specify a different template:
@@ -410,7 +417,7 @@ Partials can be rendered within a template:
 <%= render partial: 'articles/form', locals: { secret: 23 } %>
 ```
 
-It will look for a template `articles/_form.html.erb` and it will make available both the view's and partial's locals (eg. `article` and `secret`).
+It will look for a template `articles/_form.html.erb` and make available both the view's and partial's locals (eg. `article` and `secret`).
 
 ### Templates
 
@@ -420,11 +427,11 @@ Templates can be rendered within another template:
 <%= render template: 'articles/new', locals: { errors: {} } %>
 ```
 
-It will render `articles/new.html.erb` and it will make available both the view's and templates's locals (eg. `article` and `errors`).
+It will render `articles/new.html.erb` and make available both the view's and templates's locals (eg. `article` and `errors`).
 
 ### Layouts
 
-Layouts are wrappers for views, they can be a way to reuse common markup.
+Layouts are wrappers for views. Layouts may serve to reuse common markup.
 
 ```ruby
 class ApplicationLayout
@@ -455,11 +462,11 @@ Articles::Index.render(format: :html) # => Will use ApplicationLayout
 Articles::Index.render(format: :rss)  # => Will use nothing
 ```
 
-As per convention, layouts' templates are located under `Lotus::View.root` or `ApplicationLayout.root` and they uses the underscored name (eg. `ApplicationLayout => application.html.erb`).
+As per convention, layout templates are located under `Lotus::View.root` or `ApplicationLayout.root` and use the underscored name (eg. `ApplicationLayout => application.html.erb`).
 
 ### Presenters
 
-They are a way to wrap and reuse presentational logic for an object.
+The goal of a presenter is to wrap and reuse presentational logic for an object.
 
 ```ruby
 class Map
@@ -497,7 +504,7 @@ presenter = MapPresenter.new(map)
 puts presenter.locations # => ['Rome', 'Boston']
 
 # access presenter concrete methods
-puts presenter.count # => 1
+puts presenter.count # => 2
 
 # uses super to access original object implementation
 puts presenter.location_names # => 'ROME, BOSTON'
@@ -506,6 +513,88 @@ puts presenter.location_names # => 'ROME, BOSTON'
 puts presenter.inspect_object # => #<Map:0x007fdeada0b2f0 @locations=["Rome", "Boston"]>
 ```
 
+### Configuration
+
+Lotus::View can be configured with a DSL that determines its behavior.
+It supports a few options:
+
+```ruby
+require 'lotus/view'
+
+Lotus::View.configure do
+  # Set the root path where to search for templates
+  # Argument: String, Pathname, #to_pathname, defaults to the current directory
+  #
+  root '/path/to/root'
+
+  # Set the Ruby namespace where to lookup for views
+  # Argument: Class, Module, String, defaults to Object
+  #
+  namespace 'MyApp::Views'
+
+  # Set the global layout
+  # Argument: Symbol, defautls to nil
+  #
+  layout :application
+end
+```
+
+All those global configurations can be overwritten at a finer grained level:
+views. Each view and layout has its own copy of the global configuration, so
+that changes are inherited from the top to the bottom, but not bubbled up in the
+opposite direction.
+
+```ruby
+require 'lotus/view'
+
+Lotus::View.configure do
+  root '/path/to/root'
+end
+
+class Show
+  include Lotus::View
+  root '/another/root'
+end
+
+Lotus::View.configuration.root # => #<Pathname:/path/to/root>
+Show.root                      # => #<Pathname:/another/root>
+```
+
+### Reusability
+
+Lotus::View can be used as a singleton framework as seen in this README.
+The application code includes `Lotus::View` or `Lotus::Layout` directly
+and the configuration is unique per Ruby process.
+
+While this is convenient for tiny applications, it doesn't fit well for more
+complex scenarios, where we want micro applications to coexist together.
+
+```ruby
+require 'lotus/view'
+
+Lotus::View.configure do
+  root '/path/to/root'
+end
+
+module WebApp
+  View = Lotus::View.duplicate(self)
+end
+
+module ApiApp
+  View = Lotus::View.duplicate(self) do
+    root '/another/root'
+  end
+end
+
+Lotus::View.configuration.root  # => #<Pathname:/path/to/root>
+WebApp::View.configuration.root # => #<Pathname:/path/to/root>, inherited from Lotus::View
+ApiApp::View.configuration.root # => #<Pathname:/another/root>
+```
+
+The code above defines `WebApp::View` and `WebApp::Layout`, to be used for
+the `WebApp` views, while `ApiApp::View` and `ApiApp::Layout` have a different
+configuration.
+
 ### Thread safety
 
 **Lotus::View**'s is thread safe during the runtime, but it isn't during the loading process.

data/lib/lotus/layout.rb

@@ -1,3 +1,4 @@
+require 'lotus/utils/class_attribute'
 require 'lotus/view/rendering/layout_registry'
 require 'lotus/view/rendering/layout_scope'
 require 'lotus/view/rendering/null_layout'
@@ -21,12 +22,18 @@ module Lotus
     #     include Lotus::Layout
     #   end
     def self.included(base)
+      conf = Lotus::View::Configuration.for(base)
+      conf.add_layout(base)
+
       base.class_eval do
         extend Lotus::View::Dsl.dup
         extend ClassMethods
-      end
 
-      Lotus::View.layouts.add(base)
+        include Utils::ClassAttribute
+        class_attribute :configuration
+
+        self.configuration = conf.duplicate
+      end
     end
 
     # Class level API
@@ -49,7 +56,7 @@ module Lotus
       #
       # @see Lotus::View::Rendering::LayoutRegistry
       def registry
-        @@registry ||= View::Rendering::LayoutRegistry.new(self)
+        @registry ||= View::Rendering::LayoutRegistry.new(self)
       end
 
       # Template name
@@ -91,7 +98,7 @@ module Lotus
       #
       # @see Lotus::View.load!
       def load!
-        registry.freeze
+        # registry.freeze
       end
     end