action_widget 0.5.1 → 0.6.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b0064d71b6d2394b297e64a6fa7dcbe74de2c8bb
-  data.tar.gz: 84ced9363a9d26829c241ec189d18d318609be25
+  metadata.gz: 65f04e0efe22c4a80632c8bb2788b48f60c0d1d9
+  data.tar.gz: 2319ca299e05f2611cef8a1f420f886dcaebadfa
 SHA512:
-  metadata.gz: 72f994bbf840c022f8c6c0038e26b78c9454a7e816806e9b6a7826e72de5ed187bddf9fa6597dfc0f66af6c619e57d6fbf025cf442bcb5b31382e7911fdb0025
-  data.tar.gz: 58a3598ec1cfef5167831f3657a44db4c6c3f01080e6a6579b7f7f576ab93ec49041cf03a6a086fd23d558f4418127ad4c146fd6cefb5d71b2f7fba96c29cb83
+  metadata.gz: 90bda59277298cee6d43f1e98580fd812def0f5a6de6a1066ac762a470cf04d0ef2b4dac78798e264f5cd197dc51ea13f448ba7b1371fb44e9cde66024c19efb
+  data.tar.gz: d715ab381e066c58275390dda86e5f1156bfba030519c8292db06fcd0ecf017a61ca3624ea00f199e97b1e6996d1f908e0891be776d0e9a3988a2ca804dc985f

data/.gitignore

@@ -16,3 +16,4 @@ test/tmp
 test/version_tmp
 tmp
 .rvmrc
+.rspec

data/.travis.yml

@@ -0,0 +1,5 @@
+rvm:
+  - 2.2.2
+  - 1.9.3
+
+bundler_args: --without documentation

data/README.md

@@ -1,6 +1,23 @@
 # ActionWidget
 
-TODO: Write a gem description
+`ActionWidget` is a light-weight widget system for [Ruby on
+Rails](http://rubyonrails.com) and [Middleman](http://middlemanapp.com). It is
+essentially a minimal tool set for building desktop-like UI components. The
+main idea behind `ActionWidget` is the separation of the concept of an UI
+component and its representation. While the representation of component might
+easily change over time, the concept of a component is unlikely to change
+significantly. Think of a button for instance: Most developers will agree that
+a button is conceptually something that has a caption and when clicked triggers
+an action.  When we think about the visual representation of a button, however,
+things get more complicated. While most people will agree to a certain degree
+on what can visually be considered a button and what is something else, people
+tend to have different ideas about a button's exact representation. There are
+buttons with icons, without icons, round ones, rectangular ones, and so on.
+Despite their different appearances, the functionality and in this sense the
+component's concept stays the same: when clicked an action is triggered.
+ActionWidget provides developers with a tool set that helps them to strictly
+decouple a component's concept from its representation to support future
+change.
 
 ## Installation
 
@@ -18,7 +35,274 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+`ActionWidget` can be used to build arbitrarily complex view components. To
+illustrate the basic usage of `ActionWidget`, however, we start with a simple
+example, a widget for representing a button. We then continue with widgets that
+except blocks. We will use a widget representing panels as an example. Finally,
+we see discuss how to build widgets that utilize widgets themselves for
+constructing navigation components.
+
+### Simple Widgets
+
+The goal of this section is to build a widget that represents a button. The
+button we are designing must have a `caption` and a `type`. The type can either
+be `regular`, `accept`, or `cancel`. The button further must have a specified
+`size`, which can be `small`, `medium`, or `large`. Finally, the button
+requires a `target` that defines the resource it links to.  `ActionWidget`
+compentens utilize [SmartProperties](http://github.com/t6d/smart_properties) to
+define attributes that can be configured to automatically enforce these
+constraints and provide sensible defaults.
+
+In the example below, we simple use an `<a>` tag to represent a button. The
+attributes `size` and `type` are simply translated into CSS classes. The
+`caption` will be used as the text encolsed by the `<a>` tag and the `target`
+will be used as the value the the `<a>` tag's `href` attribute.
+
+```ruby
+class ButtonWidget < ActionWidget::Base
+  property :caption,
+    converts: :to_s,
+    required: true
+
+  property :target,
+    converts: :to_s,
+    accepts: lambda { |uri| URI.parse(uri) rescue false },
+    required: true
+
+  property :type,
+    converts: :to_sym,
+    accepts: [:regular, :accept, :cancel],
+    default: :regular
+
+  property :size,
+    converts: :to_sym,
+    accepts: [:small, :medium, :large],
+    default: :medium
+
+  def render
+    content_tag(:a, caption, href: target, class: css_classes)
+  end
+
+protected
+
+  def css_classes
+    css_classes = ['btn']
+    css_classes << "btn-#{size}" unless size == :regular
+    css_classes << "btn-#{type}" unless type == :medium
+    css_classes
+  end
+end
+```
+
+By convention, a widget's class name should end in "Widget". This way,
+`ActionWidget` automatically generates `ActionView` helper methods for more
+convenient instantiation and rendering of a widget.
+
+In our example, the widget can be instantiated by simply calling the helper
+method `button_widget` and providing it with all necessary attributes:
+
+```erb
+<%= button_widget caption: 'Go to Admin Area', size: :small, target: '/admin' %>
+```
+
+Instead of using the provided helper method, a widget can always be instantiated
+manually:
+
+```erb
+<%= ButtonWidget.new(self, caption: 'Go to Admin Area', size: :small, target: '/admin').render %>
+```
+
+In both cases, the resulting HTML looks as follows:
+
+```html
+<a class="btn btn-small" href="/admin">Go to Admin Area</a>
+```
+
+### Widgets that Accept Blocks
+
+The panel widget we are building requires a `title` and a block that defines the
+widgets content.
+
+```ruby
+require 'action_widget'
+
+class PanelWidget < ActionWidget::Base
+  property :title, required: true, converts: :to_s
+
+  def render(&block)
+    content_tag(:div, class: 'panel') do
+      content_tag(:h2, title, class: 'title') +
+        content_tag(:div, class: 'content', &block)
+    end
+  end
+end
+```
+
+Again, the automatically generated helper method, `#panel_widget` in this case,
+can be used to instantiate and render the widget:
+
+```erb
+<%= panel_widget title: "Important Notice" do %>
+  The system will be down for maintanence today.
+<% end %>
+```
+
+Executing the code above results in the follwing HTML:
+
+```html
+<div class="panel">
+  <h2 class="title">Important Notice</h2>
+  <div class="content">
+    The system will be down for maintanence today.
+  </div>
+</div>
+```
+
+Since widgets are simple Ruby classes, they naturally support inheritance.
+Let's assume we require a special panel widget for sidebars that renders a
+different header. There are two options:
+
+1. we can provide the tag that is chosen for the header as a property, or
+2. we restructure the `PanelWidget` class and then subclass it.
+
+Let's take the second approach and extract the header rendering and the content
+rendering into their own methods so we can overwrite either one of them in a
+potential subclass.
+
+```ruby
+class PanelWidget < ActionWidget::Base
+  property :title, required: true, converts: :to_s
+
+  def render(&block)
+    header + content(&block)
+  end
+
+  protected
+
+  def header
+    content_tag(:h2, title)
+  end
+
+  def content(&block)
+    content_tag(:div, &block)
+  end
+end
+```
+
+After this refactoring, we are able to subclass `PanelWidget` and customize the
+`header` method:
+
+```ruby
+class SidebarPanelWidget < PanelWidget
+  protected
+
+  def header
+    content_tag(:h3, title)
+  end
+end
+```
+
+### Nested Widgets
+
+Let's assume we want to implement a widget that simplifies the rendering of
+navigational menus. The widget only exposes one property, `orientation`, which
+can either be `horizontal` or `vertical`.
+
+```ruby
+class MenuWidget < ActionWidget::Base
+  property :orientation,
+    accepts: [:horizontal, :vertical],
+    converts: :to_sym,
+    default: :horizontal,
+    required: true
+
+  def render(&block)
+    content_tag(:nav, class: orientation) do
+      content_tag(:ul) do
+        capture(self, &block)
+      end
+    end
+  end
+
+  def item(caption, target)
+    content_tag(:li) do
+      content_tag(:a, caption, href: target)
+    end
+  end
+
+  def submenu(caption, &block)
+    content_tag(:li) do
+      content_tag(:span, caption) +
+        self.class.new(view, orientation: orientation).render(&block)
+    end
+  end
+end
+```
+
+The following example demonstrates how to use this widget:
+
+```erb
+<%= menu_widget do |m| %>
+  <%= m.item "Dashboard", "/" %>
+  <%= m.submenu "Admin" do |m| %>
+    <%= m.item "Manage Users", "/admin/users" %>
+    <%= m.item "Manage Groups", "/admin/groups" %>
+  <% end %>
+<% end %>
+```
+
+Executing the code above, will result in the following HTML being generated:
+
+```html
+<nav class="horizontal">
+  <ul>
+    <li> <a href="/">Dashboard</a> </li>
+    <li>
+      <span>Admin</span>
+      <nav class="horizontal">
+        <ul>
+          <li><a href="/admin/users">Manage Users</a></li>
+          <li><a href="/admin/groups">Manage Groups</a></li>
+        </ul>
+      </nav>
+    </li>
+  </ul>
+</nav>
+```
+
+### Option Capturing and Positional Argument Forwarding
+
+`ActionWidget` instances capture all initializer keyword
+arguments that do not correspond to a property in a general `options` hash.
+All positional arguments supplied to an autogenerated helper are
+forwarded to the `render` method.
+
+```ruby
+class ParagraphWidget < ActionWidget::Base
+  def render(content, &block)
+    content = capture(&block) if block
+    content_tag(:p, content, class: options[:class])
+  end
+end
+```
+
+This widget can be used in the following two ways:
+
+```erb
+<%= paragraph_widget("Some content", class: 'important') %>
+
+<%= paragraph_widget(class: 'important') do %>
+  Some content
+<% end %>
+```
+
+In both cases, the resulting HTML reads as follows:
+
+```html
+<p class="important">
+  Some content
+</p>
+```
 
 ## Contributing
 

data/Rakefile

@@ -1,2 +1,6 @@
 #!/usr/bin/env rake
 require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+task :default => :spec

data/action_widget.gemspec

@@ -10,7 +10,11 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.name          = "action_widget"
   gem.require_paths = ["lib"]
-  gem.version       = "0.5.1"
+  gem.version       = "0.6.0.pre"
 
-  gem.add_dependency 'smart_properties', '~> 1.1'
+  gem.add_dependency 'smart_properties', '~> 1.10'
+
+  gem.add_development_dependency 'rake', '~> 10.0'
+  gem.add_development_dependency 'rspec', '~> 3.3'
+  gem.add_development_dependency 'actionview', '~> 4.0'
 end

data/lib/action_widget/base.rb

@@ -1,31 +1,21 @@
-require 'smart_properties'
-
 module ActionWidget
-  class Base
+  class Base < SimpleDelegator
+    alias view __getobj__
     include SmartProperties
 
-    def initialize(view, *args)
-      @view = view
-      super(*args)
+    attr_reader :options
+
+    def initialize(view, attributes = {})
+      properties = self.class.properties
+      attributes, options = attributes.partition { |name, value| properties.key?(name) }
+
+      @options = Hash[options]
+      super(view, Hash[attributes])
     end
 
     def render
       raise NotImplementedError, "#{self.class} must implement #render"
     end
-
-    protected
-
-      attr_reader :view
-
-      undef :capture if method_defined?(:capture)
-
-      def method_missing(method, *args, &block)
-        view.send(method, *args, &block)
-      rescue NoMethodError
-        # Double check - the NoMethodError might have occurred somewhere else.
-        view.respond_to?(method) ? raise : super
-      end
-
   end
 end
 

data/lib/action_widget/view_helper.rb

@@ -2,18 +2,19 @@ module ActionWidget
   module ViewHelper
 
     def method_missing(name, *args, &block)
-      return super unless name =~ /_widget$/
+      return super unless ActionWidget.helper?(name)
 
       klass = begin
-        "#{name.to_s.camelcase}".constantize
+        ActionWidget.class_for(name)
       rescue NameError, LoadError
         return super
       end
 
       ActionWidget::ViewHelper.module_eval <<-RUBY
-        def #{name}(*args, &block)                  # def example_widget(*args, &block)
-          #{klass}.new(self, *args).render(&block)  #   ExampleWidget.new(self, *args).render(&block)
-        end                                         # end
+        def #{name}(*args, &block)                          # def example_widget(*args, &block)
+          attrs = args.last.kind_of?(Hash) ? args.pop : {}
+          #{klass}.new(self, attrs).render(*args, &block)   #   ExampleWidget.new(self, attrs).render(*args, &block)
+        end                                                 # end
       RUBY
 
       send(name, *args, &block)

data/lib/action_widget.rb

@@ -1,3 +1,45 @@
+require 'smart_properties'
+
+module ActionWidget
+  class Configuration
+    include SmartProperties
+    property :prefix
+    property :suffix
+
+    attr_reader :pattern
+
+    def initialize(*)
+      super
+
+      @pattern = Regexp.new([
+        (prefix.underscore if prefix.presence),
+        "(.*)",
+        (suffix.underscore if suffix.presence)
+      ].compact.join("_"))
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new(suffix: "Widget")
+    end
+
+    def configure(&block)
+      @configuration = Configuration.new(&block)
+    end
+
+    def helper?(name)
+      !!configuration.pattern.match(name)
+    end
+
+    def class_for(helper_name)
+      basename = configuration.pattern.match(helper_name)[1]
+      classname = [configuration.prefix, basename.camelcase, configuration.suffix].join("")
+      classname.constantize
+    end
+  end
+end
+
 require 'action_widget/base'
 require 'action_widget/view_helper'
-require 'action_widget/extensions'
+require 'action_widget/extensions'

data/spec/action_widget_spec.rb

@@ -0,0 +1,45 @@
+require 'spec_helper'
+
+class DummyWidget < ActionWidget::Base
+  property :type
+
+  def render(content = nil)
+    classes = [options[:class], type].compact
+    if classes.empty?
+      content_tag(:p, content)
+    else
+      content_tag(:p, content, class: classes)
+    end
+  end
+end
+
+class ViewContext < ActionView::Base
+  include ActionWidget::ViewHelper
+end
+
+RSpec.describe DummyWidget do
+  let(:view) { ViewContext.new }
+
+  it "should delegate unknown method calls to the view context" do
+    expect(described_class.new(view).render).to eq("<p></p>")
+  end
+
+  context "option capturing and positional argument forwarding" do
+    let(:expected_html) { '<p class="wide teaser">Hello World</p>' }
+
+    it "should be possible to reference a property using a symbol" do
+      attributes = {type: 'teaser', class: 'wide'}
+      expect(view.dummy_widget("Hello World", attributes)).to eq(expected_html)
+    end
+
+    it "should be possible to reference a property using a string" do
+      attributes = {"type" => 'teaser', class: 'wide'}
+      expect(view.dummy_widget("Hello World", attributes)).to eq(expected_html)
+    end
+
+    specify "keyword arguments that do not correspond to a property should be captured as options" do
+      instance = described_class.new(view, class: 'wide')
+      expect(instance.options).to eq({class: 'wide'})
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,82 @@
+require 'bundler/setup'
+require 'rspec'
+require 'action_view'
+
+require 'action_widget'
+
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    #     be_bigger_than(2).and_smaller_than(4).description
+    #     # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #     # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+  # These two settings work together to allow you to limit a spec run
+  # to individual examples or groups you care about by tagging them with
+  # `:focus` metadata. When nothing is tagged with `:focus`, all examples
+  # get run.
+  config.filter_run :focus
+  config.run_all_when_everything_filtered = true
+
+  # Allows RSpec to persist some state between runs in order to support
+  # the `--only-failures` and `--next-failure` CLI options. We recommend
+  # you configure your source control system to ignore this file.
+  #
+  # config.example_status_persistence_file_path = "spec/examples.txt"
+
+  # Limits the available syntax to the non-monkey patched syntax that is
+  # recommended. For more details, see:
+  #   - http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax
+  #   - http://www.teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+  #   - http://myronmars.to/n/dev-blog/2014/05/notable-changes-in-rspec-3#new__config_option_to_disable_rspeccore_monkey_patching
+  config.disable_monkey_patching!
+
+  # This setting enables warnings. It's recommended, but in some cases may
+  # be too noisy due to issues in dependencies.
+  config.warnings = true
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  if config.files_to_run.one?
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = 'doc'
+  end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  config.profile_examples = 10
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  Kernel.srand config.seed
+end

metadata

@@ -1,29 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: action_widget
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0.pre
 platform: ruby
 authors:
 - Konstantin Tennhard
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-08-22 00:00:00.000000000 Z
+date: 2015-10-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: smart_properties
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '1.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 description: 
 email:
 - me@t6d.de
@@ -31,7 +73,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
+- ".travis.yml"
 - Gemfile
 - LICENSE
 - README.md
@@ -45,6 +88,8 @@ files:
 - lib/action_widget/extensions/rails/generators.rb
 - lib/action_widget/extensions/rails/railtie.rb
 - lib/action_widget/view_helper.rb
+- spec/action_widget_spec.rb
+- spec/spec_helper.rb
 - support/templates/widget.rb.erb
 - support/templates/widget_spec.rb.erb
 homepage: http://github.com/t6d/action_widget
@@ -56,19 +101,21 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.6
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: Reusable view components for your Ruby web application
-test_files: []
+test_files:
+- spec/action_widget_spec.rb
+- spec/spec_helper.rb
 has_rdoc: