form_forms 0.1.0

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.rvmrc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.3
+  - jruby-18mode # JRuby in 1.8 mode
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-18mode
+  - rbx-19mode
+gemfile:
+  - gemfiles/Gemfile.rails3_0
+  - gemfiles/Gemfile.rails3_1
+  - gemfiles/Gemfile.rails3_2

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in formforms.gemspec
+gemspec
+
+gem 'rake'

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Holger Just
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE 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/README.md

@@ -0,0 +1,239 @@
+# FormForms [![Build Status](https://secure.travis-ci.org/meineerde/form_forms.png)](http://travis-ci.org/meineerde/form_forms) [![Dependency Status](https://gemnasium.com/meineerde/form_forms.png?travis)](https://gemnasium.com/meineerde/form_forms)
+
+Configurable forms for Rails 3, based on the excellent
+[simple_form](https://github.com/plataformatec/simple_form) gem.
+
+The goal of this gem is to provide forms (as in views) which are flexible
+enough to fulfill their intended usage but be able to be configured by
+plugins. Thus plugins can easily add, delete and edit form fields without
+having to override whole views (which are almost impossible to patch) or
+having to monkey patch existing code which is hard to maintain.
+
+form_forms is originally intended to be used with the simple_form gem and uses
+its API in several of its shipped element definitions. While it is possible
+to not use those and provide custom definitions, we require simple_form as
+a dependency right now.
+
+# Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'form_forms'
+
+and then run `bundle install`.
+
+Or install it yourself using
+
+    gem install form_forms
+
+# Usage
+
+form_forms is built around the idea that a Rails application is able to
+define arbitrary forms using a simple yet powerful DSL. These form
+definitions are typically contained in the `lib` directory and are loaded
+during initialization. During rendering of a request, the view simply
+retrieves an existing form definition and renders that form by parameterizing
+it with some data object (e.g. an ActiveRecord model instance).
+
+To handle several forms, form_forms ships with a simple registry. If you
+need a more powerful system, you are of course free to handle your form
+objects in any other way.
+
+## Defining Forms
+
+    FormForms::Registry[:my_form] = FormForms::Form.new() do |form|
+      form.field(:subject) {|f| f.input :subject}
+      form.field(:link) do |f|
+        content_tag :p do
+          content_tag(:a, :href => hint_path){ "This is a hint" }
+        end
+      end
+    end
+
+This will register a new form object under the name `:my_form` which will
+render two fields: an input field for the `subject` attribute of the passed
+model instance and a "static" hint. Each fields definition has a block which
+defines what will actually be rendered. This block will be executed in the
+context of the current view which allows you to use any helper methods you
+have defined in your application.
+
+Each of the fields is identified with a name, passed as the first parameter
+to the field definition. Using this name, plugins can later change or remove
+individual fields. As such, the name of each field has to be unique on each
+level of the form.
+
+The form can be rendered in a view by using something like this:
+
+    <%= FormForms::Registry[:my_form].render(@model, self) %>
+
+The render method takes two parameters: the model object that should be used
+as the base object for the form and a view instance (which can be almost
+always passed as `self`). The view instance is used to render the form fields.
+
+## Adapting an existing form from plugins
+
+Once a form is defined, it fields can be added, changed, and removed later on.
+
+New fields can be added either before or after already existing elements:
+
+    FormForms::Registry[:my_form].field_before(:description, :name) {|f| f.input :name}
+    FormForms::Registry[:my_form].field_after(:credit_card, :ccv) {|f| f.input :ccv}
+
+This will insert the new field `:name` before the already defined field
+`:description` and insert the field `:ccv` after the existing `:credit_card`
+field. You can also insert elements at the very beginning and the very end of
+the elements list:
+
+    FormForms::Registry[:my_form].field_first(:salutation) {|f| f.input :salutation}
+    FormForms::Registry[:my_form].field_last(:accept_terms) {|f| f.input :accept_terms}
+
+Each of the element types defines the five methods
+
+* `form.<type>`
+* `form.<type>_first`
+* `form.<type>_before`
+* `form.<type>_after`
+* `form.<type>_last` (an alias to `form.<type>`)
+
+Each of the methods accepts all parameters of the respective element type.
+Only the `form.<type>_before` and `form.<type>_after` methods take the name of
+the element that should act as the respective index as the first argument.
+
+Finally, there is the `form.delete` method which simply takes the name of an
+element as its parameter. It complete deletes this element from the element
+list, preventing it from rendering:
+
+    FormForms::Registry[:my_form].delete(:salutation)
+
+# Element Types
+
+form_forms already ships with different element types which allow you to
+create most of the common form elements. These elements are used to define
+the actual form body.
+
+## `field`
+
+The most basic element type is a `field` which is rendered to a basic form
+field or a snipped of static code. Fields are the most basic form of elements
+and typically made of the bulk of the form definition.
+
+For the definition, they take a `name` which is used for identifying the
+field in the form as well as a generator block to render the field. The name,
+always being the first attribute is *only* used for identifying the element
+later on and is not passed to the generator block during rendering and thus
+can be chosen arbitrarily. It must only be unique in the current scope.
+Generally, it is advisable to chose a name similar to the model field that is
+actually rendered.
+
+The block receives one argument during rendering: the form builder, i.e. the
+simple_form object. Alternatively to a block, you can also directly pass a
+string which will be emitted as-is. The usual HTML escape rules apply, i.e.
+you have to use `html_save` correctly to avoid rendering unsafe data.
+
+## `fieldset`
+
+A fieldset is used to group fields in a single form. During rendering, this
+elements will create an HTML `<fieldset>` tag and a `<legend>`. As a fieldset
+naturally contains  other fields, its generator block can be used to define
+fields.
+
+    FormForms::Registry[:user] = FormForms::Form.new() do |form|
+      form.field(:street) {|f| f.input :street }
+      form.field(:city) {|f| f.input :city }
+      form.fieldset(:payment, :id => "payment") do |fieldset|
+        fieldset.legend "Credit Card Data"
+        fieldset.field(:credit_card) {|f| f.input :credit_card}
+        fieldset.field(:ccv) {|f| f.input :ccv}
+      end
+    end
+
+The fieldset element creates a new scope (or sub-form) which can be
+arbitrarily nested. Apart from all the other elements types, it has a special
+sub element: the `legend`. It doesn't take a name as its first parameter.
+Instead, it just takes a string or a generator block (similar to a `field`)
+which is used to render the content of the `<legend>` tag of the fieldset.
+
+The fieldset tag receives one additional (optional) hash argument which
+allows to define additional options (e.g. additional HTML attributes) for the
+the fieldset tag. All options supported by Rails' `content_tag` helper are
+allowed here.
+
+## `block`
+
+A `block` creates a sub-form which nests form elements inside a HTML block
+(e.g. a `<div>`) which is sometimes necessary to further group elements and
+markup the form using custom CSS rules. This element works similar to the
+`fieldset` described above.
+
+    FormForms::Registry[:user] = FormForms::Form.new() do |form|
+      form.field(:street) {|f| f.input :street }
+      form.block(:box, :class => "red-and-blinky") do |block|
+        block.field(:sell_your_soul) {|f| f.input :sell_your_soul}
+      end
+    end
+
+## `fields`
+
+Using fields, you can create sub-forms for association of the model object.
+This allows you to create forms for nested elements.
+
+    FormForms::Registry[:user] = FormForms::Form.new() do |form|
+      form.field(:name) {|f| f.input :name}
+
+      args = lambda{|f| {:collection => Tag.all} }
+      form.fields(:tags, :tags, args) do |tags|
+        tags.field(:name) {|f| f.input :name}
+      end
+    end
+
+The fields element type takes four arguments. The first is the name of the
+element as usual. The second is the name of the association which is to be
+rendered. For the example above, the `User` model is defined as follows:
+
+    class User < ActiveRecord::Base
+      has_many :tags
+    end
+
+The third argument is an options hash which is passed to association render
+function of simple_form. In our example, we pass the `:collection` attribute
+which instructs simple_form to render a select box containing the elements of
+the passed collection.
+
+Here we have to do a little trick. If we simple pass the array here as in
+
+    form.fields(:tags, :tags, :collection => Tag.all) do |tags|
+
+the `Tags.all` would be evaluated just once, during the initialization of the
+application. New tags would not be included. To fix this, we pass a
+lambda block which is evaluated each time again during the form rendering.
+This lambda is expected to return an array of options to the `association`
+method of simple_form.
+
+# Development
+
+Install dependencies with
+
+    bundle install
+
+then run tests with
+
+    bundle exec rake
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+# License
+
+> take my code with you<br/>
+> and do whatever you want<br/>
+> but please don’t blame me<br/>
+
+[License Haiku](http://www.aaronsw.com/weblog/000360)
+
+This library is licensed under the MIT license. See the `LICENSE` file for
+more details.

data/Rakefile

@@ -0,0 +1,11 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+
+task :default => [:test]
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.test_files = FileList['test/**/*_test.rb']
+  test.verbose = true
+end

data/form_forms.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/form_forms/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Holger Just"]
+  gem.email         = ["hjust@meine-er.de"]
+  gem.description   = %q{Configurable forms for Rails}
+  gem.summary       = %q{Configurable forms for Rails}
+  gem.homepage      = "https://github.com/meineerde/form_forms"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "form_forms"
+  gem.require_paths = ["lib"]
+  gem.version       = Formforms::VERSION
+
+  gem.add_dependency "activesupport", "~> 3.0"
+  gem.add_dependency "actionpack", "~> 3.0"
+  gem.add_dependency "simple_form"
+
+  gem.add_development_dependency "activemodel", "~> 3.0"
+end

data/gemfiles/Gemfile.rails3_0

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gem "activesupport", "~> 3.0.0"
+gem "actionpack", "~> 3.0.0"
+gem "simple_form"
+
+group :test do
+  gem "activemodel", "~> 3.0.0"
+  gem "rake"
+end

data/gemfiles/Gemfile.rails3_1

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gem "activesupport", "~> 3.1.0"
+gem "actionpack", "~> 3.1.0"
+gem "simple_form"
+
+group :test do
+  gem "activemodel", "~> 3.1.0"
+  gem "rake"
+end

data/gemfiles/Gemfile.rails3_2

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gem "activesupport", "~> 3.2.0"
+gem "actionpack", "~> 3.2.0"
+gem "simple_form"
+
+group :test do
+  gem "activemodel", "~> 3.2.0"
+  gem "rake"
+end

data/lib/form_forms.rb

@@ -0,0 +1,10 @@
+require 'form_forms/elements'
+require 'form_forms/forms'
+
+require 'form_forms/form_registry'
+
+require "form_forms/version"
+
+module FormForms
+  # Your code goes here...
+end

data/lib/form_forms/elements.rb

@@ -0,0 +1,5 @@
+require 'form_forms/elements/base_element'
+require 'form_forms/elements/block'
+require 'form_forms/elements/field'
+require 'form_forms/elements/fields'
+require 'form_forms/elements/fieldset'

data/lib/form_forms/elements/base_element.rb

@@ -0,0 +1,189 @@
+require 'active_support/core_ext/string'
+
+module FormForms
+  module Elements
+    # The generic base class for the FormForms
+    class BaseElement
+      def initialize(*)
+        @elements = []
+        @generators = {}
+
+        yield self
+      end
+
+      attr_reader :elements
+
+      # Render all of the elements of the current FormForm in their defined
+      # order. This method is expected to be called by sub-classes in the
+      # rendering chain. The parameters are a form builder object and an
+      # action view instance.
+      #
+      # The form builder is typically created by a "special" FormForm class
+      # and passed on to its sub-elements. See +FormForms::Forms::Form+
+      # for an implementation of such a special form.
+      def render(builder, view)
+        render_elements(builder, view)
+      end
+
+      def delete(name)
+        @elements.delete(name)
+        @generators.delete(name)
+        nil
+      end
+
+    protected
+
+      # Allow the passed form type as a sub-element of the current form.
+      # Sub-elements must have a unique name inside the current form scope.
+      # They can be of any allowed type.
+      #
+      # Elements can be added to the form using the generated +type+,
+      # +type_before+, and +type_after+ methods. Element definitions can be
+      # overridden by setting the element again with the same name.
+      #
+      # Example:
+      #
+      #   class MyForm < BaseForm
+      #     allowed_sub_element(:field)
+      #   end
+      #
+      #   my_form = MyForm.new() do |form|
+      #     form.field(:subject) {|f| f.input :subject}
+      #     form.field(:description) {|f| f.text_field :description}
+      #   end
+      #
+      #   my_form.field_before(:description, :name) {|f| f.input :name}
+      #
+      #   my_form.elements
+      #   # => [:subject, :name, :description]
+
+      def self.allowed_sub_element(type, klass=nil)
+        klass ||= "::FormForms::Elements::#{type.to_s.classify}"
+
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{type}(name, *args, &block)
+            name = name.to_sym
+
+            if block_given?
+              element(name, #{klass}.new(*args, &block))
+            else
+              @generators[name]
+            end
+          end
+          alias_method :#{type}_last, :#{type}
+
+          def #{type}_first(name, *args, &block)
+            element_before(nil, name.to_sym, #{klass}.new(*args, &block))
+          end
+
+          def #{type}_before(before, name, *args, &block)
+            element_before(before.to_sym, name.to_sym, #{klass}.new(*args, &block))
+          end
+
+          def #{type}_after(after, name, *args, &block)
+            element_after(after.to_sym, name.to_sym, #{klass}.new(*args, &block))
+          end
+        RUBY
+      end
+
+      # Define a property of the element. Properties can either be given as
+      # a block, similar to the fields, or as a static object. Internally,
+      # we always use the block form.
+      def self.property(name, instance_variable=nil)
+        instance_variable ||= name
+
+        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{name}(param=indicator=true, &generator)   # def legend(param=indicator=true, &generator
+            if block_given?                               #   if block_given?
+              @#{instance_variable} = generator           #     @legend = generator
+            elsif indicator.nil?                          #   elsif indicator.nil?  # parameter was given
+              @#{instance_variable} = param               #     @legend = param
+            else                                          #   else
+              @#{instance_variable}                       #     @legend
+            end                                           #   end
+          end                                             # end
+        RUBY
+      end
+
+      # Get the actual value of a parameter. If the parameter was set with a
+      # block or a lambda, evaluate the lambda in the context of the view
+      # and return the result. This can be used for delayed evaluation of
+      # parameter arguments.
+      def eval_property(name, builder, view)
+        property = self.send(name.to_sym)
+        if property.is_a?(Proc)
+          view.instance_exec(builder, &property)
+        else
+          property
+        end
+      end
+
+      # Append a generic element to the end of the elements list. This method
+      # is supposed tpo be called by the generated public methods of each
+      # sub-element type.
+      def element(name, generator)
+        @elements << name unless @elements.include? name
+        @generators[name] = generator
+      end
+
+      # Insert an element directly after an existing alement. The element
+      # +name+ can not be defined in the current form scope yet. The +after+
+      # element has to exist or be nil. If it is nil, the new element is
+      # appended to the end of the element list.
+      def element_after(after, name, generator)
+        if @elements.include? name
+          # Only allow new elements. Existing fields can be changed with #element
+          raise ArgumentError.new("#{name} is already registered.")
+        end
+
+        after_index = @elements.index(after)
+        if !after.nil? && after_index.nil?
+          # This method makes only sense if the before element actually exists
+          raise ArgumentError.new("#{after} is not registered. I can't insert after it.")
+        elsif after.nil? || after_index == @elements.length-1
+          # Append at the end
+          element(name, generator)
+        else
+          # Perform an insert
+          @elements.insert(after_index+1, name)
+          @generators[name] = generator
+        end
+      end
+
+      # Inserts an element directly before an existing alement. The element
+      # +name+ can not be defined in the current form scope yet. The +before+
+      # element has to exist or be nil. If it is nil, the new element is added
+      # at the very beginning of the list.
+      def element_before(before, name, generator)
+        before_index = @elements.index(before)
+
+        if @elements.include? name
+          # Only allow new elements. Existing fields can be changed with #element
+          raise ArgumentError.new("#{name} is already registered.")
+        elsif !before.nil? && before_index.nil?
+          # This method makes only sense if the before element actually exists
+          raise ArgumentError.new("#{before} is not registered. I can't insert before it.")
+        end
+
+        # Perform an insert
+        if before.nil?
+          # insert at the beginning of the list
+          @elements.unshift(name)
+        else
+          # insert the element before the named one
+          @elements.insert(before_index, name)
+        end
+        @generators[name] = generator
+      end
+
+      # Render all elements in the current
+      def render_elements(builder, view, before="", after="\n")
+        @elements.each do |name|
+          view.concat before
+          view.concat @generators[name].render(builder, view)
+          view.concat after
+        end
+      end
+    end
+  end
+end