wrap_it 0.1.5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 452ea9b6986b74655e20c2b05043adfee92a6f3b
-  data.tar.gz: 5f9afcec73b2e3fcd904f918df595a3c884cce54
+  metadata.gz: 505e7bd562594a96b7765484ddd4332d6d6142e4
+  data.tar.gz: 82ff97e143fb9867e5cc0c3bb743ae28eb34bab3
 SHA512:
-  metadata.gz: 4ced26c53ee1c80985c120ce7edde26b5a5a9306c8c37e25aee711bac374215f17a1b1dc9541bc279705cbd73664a6183e759c6c488b33ead6750a268c4b9c8a
-  data.tar.gz: d0565411c8abde8db3f6225adf5fe814a58ba100609573c3954887a3cab6e1b971c55e698a4b27cb2ea0a6a3ca10e0919aca8f422587cace395ec6171c423703
+  metadata.gz: bad8623fbebe0f97ab7ca7045f9c3a167254af82240147e282ee7d7d599925106bd1ec3d21ffe0418d2defb9d1987f3a890a986575e6d12070caebbef9a02624
+  data.tar.gz: 8c25e53fca0f92d4ba82e2c05d32b1be2d48e869ea21f03beb8759a78aeedd1f9b72553031f4800b4ee8dc38e5c0ba5337875d0b9c602e2c404d70158ba46731

data/.gitignore

@@ -1,12 +1,18 @@
-.rspec
-Gemfile.lock
-
-
-# Ignore bundler config.
-/.bundle
-
-# Ignore all logfiles and tempfiles.
-/log/*.log
-/tmp
-
 *.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+Gemfile.*.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Gemfile

@@ -2,6 +2,3 @@ source 'https://rubygems.org'
 
 gemspec
 
-group :test, :development do
-  gem 'rails', require: false
-end

data/Gemfile.rails4

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rails', '~> 4'

data/Gemfile.sinatra

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'sinatra'

data/README.md

@@ -5,22 +5,26 @@ This library provides set of classes and modules with simple DSL for quick and e
 For example, your designer makes perfect button style for some site. This element will appears in many places of site in some variations. The button have `danger`, `success` and `default` look, and can have `active` state. Button can have some icon. So, you make some CSS styles, and now you should place HTML markup of this element in many places of site. With `wrap_it` library you can do it with following code:
 
 ```ruby
-class PerfectButton < WrapIt::Container
-  include TextContainer
-  html_class 'button'
-  enum :look, [:default, :success, :danger], html_class_prefix: 'button-'
-  switch :active, html_class: 'button-active'
-  child :icon, [tag: 'img', class: 'button-icon']
-end
+WrapIt.register_module Helpers
+
+module Helpers
+  class PerfectButton < WrapIt::Container
+    include TextContainer
+    html_class 'button'
+    enum :look, [:default, :success, :danger], html_class_prefix: 'button-'
+    switch :active, html_class: 'button-active'
+    child :icon, [tag: 'img', class: 'button-icon']
+  end
 
-WrapIt.register :p_button, 'PerfectButton'
+  register :p_button, 'PerfectButton'
+end
 ```
 
 Now, include this helper into you template engine. For Rails:
 
 ```ruby
 class MyController < ApplicationController
-  helper WrapIt.helpers
+  helper Helpers
   ...
 end
 ```
@@ -51,6 +55,8 @@ This will produce following code:
 
 Note, that lines 2 and 3 produces same html markup.
 
+> **Wraning!** Module registration process changed since 0.2.0. So, if you migrate from 0.1.5, look above examples again and fix your startup code.
+
 # Status
 
 Project in pre-release state. First release version `1.0.0` planned to February of 2014.
@@ -81,9 +87,11 @@ Library have no specific configuration.
 
 # Usage
 
+> This library actively used in [BootstrapIt](https://github.com/cybernetlab/bootstrap_it) package, so explore this project, especially it's [lib/bootstrap_it/view_helpers](https://github.com/cybernetlab/bootstrap_it/tree/master/lib/bootstrap_it/view_helpers) folder for usage examples.
+
 All helpers classes derived from `WrapIt::Base` class, that provides allmost all functionality. For helpers, thats includes other helpers, use `WrapIt::Container` class. Where are some library-specific methods, defined directly in `WrapIt` module.
 
-Simple example explained above. More complex usage is to provide some logic to initalization, capturing and rendering process. To do this, use `after` or `before` `initialize`, `capture` and `reder` callbacks respectively. Usually `after` callbacks used. `initialize` callbacks runs around arguments and optioins parsed, `capture` callbacks runs around capturing content of element and `render` callbacks runs around wrapping content into element tag.
+Simple example explained above. More complex usage is to provide some logic to initalization, capturing and rendering process. To do this, use `after` or `before` `initialize`, `capture` and `reder` callbacks respectively. Usually `after` callbacks used. `initialize` callbacks runs around arguments and optioins parsing, `capture` callbacks runs around capturing element sections and `render` callbacks runs around wrapping content into element tag.
 
 Inside callbacks some usefull instance variables available.
 
@@ -93,9 +101,11 @@ Inside callbacks some usefull instance variables available.
 
 `@arguments` array available only in `after_initialize` callback and contains creation arguments. Its recommended to extract arguments, related to your class from this array if you plan to subclass your helper in future, so when subclasses `after_initialize` called these arguments will not available there.
 
-`@content` string available in `capture` and `render` callbacks and contains captured content. You can change it to any value. If you want to render some html markup with `@content`, use `html_safe` method (see below) to prevent HTML escaping.
+Inside `capture` callback you deals with sections. This mechanism described in [Sections explained](https://github.com/cybernetlab/wrap_it/blob/master/sections_explained.md) article.
+
+`@rendered` string available in `render` callbacks and contains rendered content. You can change it to any value. If you want to include some html markup use `html_safe` method (see below) to prevent HTML escaping.
 
-`@template` contains rendering template. Use this variable carefully, so if you call `@template.content_tag` or something else Rails-related, your library will not be portable to other frameworks. So, if you use this gem in user-end application, or Rails-only library, you are free to use all of `@template` methods.
+`@template` contains rendering template. Use this variable carefully, so if you call `@template.link_to` or something else Rails-related, your library will not be portable to other frameworks. So, if you use this gem in user-end application, or Rails-only library, you are free to use all of `@template` methods.
 
 *Examples*
 
@@ -110,31 +120,79 @@ end
 Including some simple HTML into content
 
 ```ruby
-class Helper < WrapIt::Base
+class IconHelper < WrapIt::Base
   after_initialize do
     @icon = optioins.delete(:icon)
   end
 
   after_capture do
     unless @icon.nil?
-      @content = html_safe("<i class=\"#{@icon}\"></i>") + @content
+      self[:content] = html_safe("<i class=\"#{@icon}\"></i>")
     end
   end
 ```
 
 ## WrapIt
 
-#### WrapIt.register(*args)
+#### WrapIt.register_module(*args)
+
+Registers helpers module and defines `register` and `unregister` class methods in this module for registering helper methods. You can specify module to register in first argument. If ommited, anonymous module will be created and returned from method. Use `prefix` option to add specified prefix to all methods in helper module.
+
+Typical usage of library and this method is:
+
+Define empty module and register it with `register_method`:
+
+```ruby
+module YourPerfectLib
+  module PerfectHelpers; end
+
+  WrapIt.register_module PerfectHelpers, prefix: 'perfect_'
+
+  # You can register all your helper methods right here, but in complex
+  # projects recommended to keep calls to register inside file where
+  # helper class defined.
+  #
+  # PerfectHelpers.register :button, 'YourPerfectLib::PerfectHelpers::Button'
+end
+```
+
+Describe your classes and register helper methods for it:
+
+```ruby
+module YourPerfectLib
+  module PerfectHelpers
+    class Button < WrapIt::Base
+      include WrapIt::TextContainer
+      html_class 'button'
+ 
+      ...
+    end
+  end
+
+  register :button, 'YourPerfectLib::PerfectHelpers::Button'
+end
+```
 
-Registers helper class. In arguments, first specify helper method names as `Symbols` and in last argument fully qualified helper class name as `String`.
+Include it in your template (example for Rails):
 
-#### WrapIt.unregister(*args)
+```ruby
+class MyController < ApplicationController
+  helper Helpers
+  ...
+end
+```
 
-Unregisters helper class. Just pass list of method names as `Symbols`.
+And now use it in templates:
 
-#### WrapIt.helpers
+```html
+<%= perfect_button 'button text' %>
+```
 
-Returns a module, that contains all registered helpers. Usefull to provide all helpers to template engine.
+will produce:
+
+```html
+<div class="button">button text</button>
+```
 
 ## WrapIt::Base
 
@@ -166,7 +224,7 @@ When `html_class` option specified and switch changes its state, HTML class for
       
 Also `aliases` option available. So if some of aliases founded in arguments it also changes switch state. You should pass only `Symbol` or `Array` if symbols to this optioin.
 
-If block given, it will be called each time switch changes its state in context of element with the switch state as argument.
+If block given, it will be called each time switch changes its state in context of element with the switch state as argument. If you return `false`  from this block, value is ommited.
 
 #### enum(name, options = {}, &block)
 
@@ -182,8 +240,28 @@ Also `aliases` option available. So if some of aliases founded in creation optio
 
 If block given, it will be called each time enum changes its value in context of element with the new value as argument.
 
+#### section(*args)
+
+Adds one ore more sections to element. Refer to [Sections explained](https://github.com/cybernetlab/wrap_it/blob/master/sections_explained.md) article for description.
+
+#### place(src, dst)
+
+Places section `src` to destination, specified in `dst` hash. `dst` is a single key-value Hash. Key can be `:before` and `:after`. Value can be `:begin`, `:end` or any section name. Refer to [Sections explained](https://github.com/cybernetlab/wrap_it/blob/master/sections_explained.md) article for description.
+
+#### sections
+
+Returns list of all sections, including derived from parent classes.
+
+#### placement
+
+Returns placed sections.
+
 ### Instance methods
 
+#### self[name] and self[name]=
+
+Retrieves or sets `name` section. Refer to [Sections explained](https://github.com/cybernetlab/wrap_it/blob/master/sections_explained.md) article for description.
+
 #### wrap(*args, &block)
 
 Wraps element with another.
@@ -258,11 +336,23 @@ Removes HTML data attribute named `name`.
 
 ## WrapIt::Container
 
+This class used for elements, that can hold other elements.
+
+At first, note, that children can be created by two ways. First - inside template and second - from code. If child created from template, you have two choises again: first to keep child in place, where it defined in template, second - to cut it from there and place together with other childs. Two variables affects on this process: `ommit_content`, defined in `WrapIt::Base` and `extarct_children`. If `ommit_content` is `true`, all content will be dropped and children placed inside `children` section. If `extract_children` is true, children also placed into `children` section, but `content` is keeped.
+
+At second, you have two choises of moment, when children rendered. If `deffered_render` set to `false`, that is as default, all children will be rendered immideately after creation, so you can't change any of them later. If you plan to render your container after children, you chould set it to `true`, so childrens are collected in buffer and will be rendered with parent.
+
+All children, added to container injected with `render_to` and `parent` methods, that are gives you rendering section name and container itself.
+
 ### DSL methods
 
-#### child(*args, &block)
+#### child(name, *args, &block)
 
-Creates your own DSL method to create child items. In arguments, you should specify list of method names (aliases if more that one). Then you can specify class name for shild. If ommited, `WrapIt::Base` will be used. and as last argument you can specify array of arguments, that will be passed to child constructor. This array will be mixed with arguments, specified by user, with higher priority. At last, you can define block, that will be called after creating child, but before its rendering. This child passed as argument to block.
+Creates your own DSL method to create child items. In arguments, you should specify name of method. Then you can specify class name or class itself for child. If ommited, `WrapIt::Base` will be used. All other arguments will be mixed with arguments, specified by user and passed to child constructor. **Warning!** Make shure, that your child arguments don't begins with `String` if you ommit class argument. As workaround, don't ommit class argument and specify it as 'WrapIt::Base'. At last, you can define block, that will be called after creating child, but before its rendering. This child passed as argument to block.
+
+You can render children to section, other than `:children`. To do this, specify `section` option with section name.
+
+Look into [lib/bootstrap_it/view_helpers](https://github.com/cybernetlab/bootstrap_it/tree/master/lib/bootstrap_it/view_helpers) folder for usage examples.
 
 # Todo
 
@@ -273,6 +363,12 @@ Creates your own DSL method to create child items. In arguments, you should spec
 
 # Changes
 
+`0.2.0`
+* added: sections mechanism
+* many fixes
+* testing improvement
+* preparing testing for multiple frameworks
+
 `0.1.5`
 * fixed: switches and enums can damage instance variables
 * fixed: process helper_name option before initialize callbacks
@@ -297,6 +393,25 @@ Creates your own DSL method to create child items. In arguments, you should spec
 `0.1.0`
 * initial version
 
+# Testing
+
+This package developed for different frameworks, so testing is not so simple. At first, prepare testing environment with:
+
+```sh
+bundle install
+bundle install --gemfile Gemfile.rails4
+bundle install --gemfile Gemfile.sinatra
+```
+
+And then you can run tests as follows:
+
+```sh
+FRAMEWORK=rails4 bundle exec rake spec
+FRAMEWORK=sinatra bundle exec rake spec
+```
+
+As sinatra support is in progress, its test will not pass yet.
+
 # License
 
 The MIT License (MIT)
@@ -320,4 +435,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
-

data/Rakefile

@@ -1,6 +1,19 @@
+# http://stackoverflow.com/questions/15752774/ \
+# strategies-for-gem-tests-to-ensure-the-gem-works-with-rails-3-x-and-4-0
+
+unless ENV['FRAMEWORK'].nil?
+  ENV['BUNDLE_GEMFILE'] = "Gemfile.#{ENV['FRAMEWORK']}"
+end
+
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
 require 'bundler/gem_tasks'
-# require 'yard'
 require 'rspec/core/rake_task'
+# require 'yard'
 # require 'rake/testtask'
 
 # Rake::TestTask.new do |t|

data/lib/wrap_it/base.rb

@@ -24,6 +24,7 @@ module WrapIt
 
     callback :initialize, :capture, :render
 
+    include Sections
     include HTMLClass
     include HTMLData
     include Switches
@@ -35,6 +36,11 @@ module WrapIt
     attr_reader :tag
     attr_reader :options
 
+    section :content, :render_arguments, :render_block
+    place :content, :after, :begin
+    place :render_block, :after, :begin
+    place :render_arguments, :after, :begin
+
     def initialize(template, *args, &block)
       @template, @arguments, @block = template, args, block
       self.options = @arguments.extract_options!
@@ -50,8 +56,6 @@ module WrapIt
           self.class.get_derived(:@default_tag) || 'div'
         @tag = @tag.to_s
       end
-
-      @arguments = nil
     end
 
     def omit_content?
@@ -72,16 +76,15 @@ module WrapIt
     # @return [String] rendered HTML for element
     def render(*args, &render_block)
       # return cached copy if it available
-      return @content unless @content.nil?
-      @content = empty_html
+      return @rendered unless @rendered.nil?
 
-      do_capture
+      capture_sections
 
       # add to content string args and block result if its present
-      args.flatten.each { |a| @content << a if a.is_a? String }
+      args.flatten.each { |a| self[:render_arguments] << a if a.is_a? String }
       if block_given?
         result = instance_exec(self, &render_block) || empty_html
-        result.is_a?(String) && @content << result
+        result.is_a?(String) && self[:render_block] << result
       end
 
       do_render
@@ -89,10 +92,10 @@ module WrapIt
 
       if @template.output_buffer.nil?
         # when render called from code, just return content as a String
-        @content
+        @rendered
       else
         # in template context, write content to templates buffer
-        concat(@content)
+        concat(@rendered)
         empty_html
       end
     end
@@ -137,11 +140,15 @@ module WrapIt
 
     #
     # @dsl
-    # Defines default tag name for element. This tag can be changed soon.
+    # Defines or gets default tag name for element. This tag can be changed
+    # soon. Without parameters returns current default_tag value.
     # @param  name [<Symbol, String>] Tag name. Converted to `String`.
+    # @param  override [Boolean] Whether to override default tag value if it
+    #   allready exists.
     #
-    # @return [void]
-    def self.default_tag(name, override = true)
+    # @return [String] new default_tag value.
+    def self.default_tag(name = nil, override = true)
+      return @default_tag if name.nil?
       name.is_a?(String) || name.is_a?(Symbol) ||
         fail(ArgumentError, 'Tag name should be a String or Symbol')
       override ? @default_tag = name.to_s : @default_tag ||= name.to_s
@@ -162,29 +169,49 @@ module WrapIt
       @options = hash
     end
 
-    private
-
-    def do_capture
+    def capture_sections
       run_callbacks :capture do
-        @content ||= empty_html
-        unless @block.nil? || omit_content?
-          @content << (capture(self, &@block) || empty_html)
+        unless @block.nil?
+          captured = capture(self, &@block) || empty_html
+          omit_content? || self[:content] << captured
         end
       end
     end
 
+    def render_sections(*sections)
+      opts = sections.extract_options!
+      sections.empty? && sections = self.class.sections
+      if opts.key?(:except)
+        opts[:except].is_a?(Array) || opts[:except] = [opts[:except]]
+        sections.reject! { |s| opts[:except].include?(s) }
+      end
+      # glew sections
+      self.class.placement
+        .select { |s| sections.include?(s) }
+        .reduce(empty_html) do |a, e|
+          a << self[e]
+          self[e] = empty_html
+          a
+        end
+    end
+
+    private
+
     def do_render
       # cleanup options from empty values
       @options.select! do |k, v|
         !v.nil? && (!v.respond_to?(:empty?) || !v.empty?)
       end
+      @rendered = render_sections
       run_callbacks :render do
-        @content = content_tag(tag, @content, options)
+        @rendered = content_tag(@tag, @rendered, @options)
       end
     end
 
     def do_wrap
-      @wrapper.is_a?(Base) && @content = @wrapper.render(html_safe(@content))
+      @wrapper.is_a?(Base) && @rendered = capture do
+        @wrapper.render(html_safe(@rendered))
+      end
     end
   end
 end

data/lib/wrap_it/callbacks.rb

@@ -12,18 +12,22 @@ module WrapIt
     end
 
     def run_callbacks(name)
-      self.class.collect_derived("@before_#{name}".to_sym).each do |cb|
+      self.class.collect_derived("@before_#{name}").each do |cb|
         if cb.is_a?(Symbol)
-          send(cb)# if respond_to?(cb)
+#          break if send(cb) == false # if respond_to?(cb)
+          send(cb) # if respond_to?(cb)
         else
+#          break if instance_eval(&cb) == false
           instance_eval(&cb)
         end
       end
       yield if block_given?
-      self.class.collect_derived("@after_#{name}".to_sym).reverse.each do |cb|
+      self.class.collect_derived("@after_#{name}").reverse.each do |cb|
         if cb.is_a?(Symbol)
-          send(cb)# if respond_to?(cb)
+#          break if send(cb) == false # if respond_to?(cb)
+          send(cb) # if respond_to?(cb)
         else
+#          break if instance_eval(&cb) == false
           instance_eval(&cb)
         end
       end
@@ -55,7 +59,8 @@ module WrapIt
             else
               instance_variable_set(var, [])
             end
-          arr << (block || method)
+          action = self == ancestors.first ? :unshift : :push
+          arr.send(action, block || method)
           instance_variable_set(var, arr)
         end
       end