lotus-helpers 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 97a8fa23a2691afc98472ad1155025367148d2ca
-  data.tar.gz: 731d5dca8b9da7d4177ca6e8f51c260e88055f53
+  metadata.gz: c48523257c329e031af02471ad83b63a56290bca
+  data.tar.gz: ec1dba8d370b280d0fb14992b2955c916e9c96da
 SHA512:
-  metadata.gz: 7298684737de0d27f28beaf7d1ba969ee37f0cc7de543c0e81d6063d2b915bf39a12e1794ad7d479956ba6c8854d49b439b4c4cab614ae1e1f959de5fca11c61
-  data.tar.gz: 142c218a581680c85c7d6f207988d787436d85467fdacfd9a0a7d54a29c74d3adb77960fabb5a1f0a18d030f25f26e4bbe2058dda57b184276a89877fc5dca48
+  metadata.gz: ee14aad1c7167c3dd942f22b59a15776c3ed6381d8eef769322b4f377716e62fe07fbe0b2666f7d1e2ce0ab0ad637560e6dbcc5649dd3515cdad60b80d2dacd0
+  data.tar.gz: 9bf9dcaf0da1206f54d11188dc36d0ebc876d76d80c9c1a1498f177560096c66d79c1725255ee1311a349bc183390a4f209270c303be554c97743edca81b738a

data/README.md

@@ -92,6 +92,142 @@ Output:
 </aside>
 ```
 
+### Form Helper
+
+Form generator for HTML5 (`#form_for`)
+
+#### Template Usage
+
+Template:
+
+```erb
+<%=
+  form_for :book, routes.books_path do
+    text_field :title
+
+    submit 'Create'
+  end
+%>
+```
+
+Output:
+
+```html
+<form action="/books" method="POST" accept-charset="utf-8" id="book-form">
+  <input type="text" name="book[title]" id="book-id" value="">
+  <button type="submit">Create</button>
+</form>
+```
+
+#### View Usage
+
+View:
+
+```ruby
+module Books
+  class New
+    include Lotus::Helpers
+
+    def form
+      form_for :book, routes.books_path do
+        text_field :title
+
+        submit 'Create'
+      end
+    end
+  end
+end
+```
+
+Template:
+
+```erb
+<%= form %>
+```
+
+Output:
+
+```html
+<form action="/books" method="POST" accept-charset="utf-8" id="book-form">
+  <input type="text" name="book[title]" id="book-id" value="">
+  <button type="submit">Create</button>
+</form>
+```
+
+#### Reuse Code
+
+Views:
+
+```ruby
+module Books
+  class New
+    include Lotus::Helpers
+
+    def form
+      Form.new(:book, routes.books_path)
+    end
+
+    def submit_label
+      'Create'
+    end
+  end
+
+  class Edit
+    include Lotus::Helpers
+
+    def form
+      Form.new(:book, routes.book_path(id: book.id), {book: book}, {method: :patch})
+    end
+
+    def submit_label
+      'Update'
+    end
+  end
+end
+```
+
+Templates:
+
+```erb
+# books/new.html.erb
+<%= render partial: 'books/form' %>
+```
+
+```erb
+# books/edit.html.erb
+<%= render partial: 'books/form' %>
+```
+
+```erb
+# books/_form.html.erb
+<%=
+  form_for form, class: 'form-horizontal' do
+    text_field :title
+
+    submit submit_label
+  end
+%>
+```
+
+Output for new:
+
+```html
+<form action="/books" method="POST" accept-charset="utf-8" id="book-form">
+  <input type="text" name="book[title]" id="book-id" value="">
+  <button type="submit">Create</button>
+</form>
+```
+
+Output for edit:
+
+```html
+<form action="/books/23" method="POST" accept-charset="utf-8" id="book-form">
+  <input type="hidden" name="_method" value="PATCH">
+  <input type="text" name="book[title]" id="book-id" value="TDD">
+  <button type="submit">Update</button>
+</form>
+```
+
 ### Escape helper
 
 HTML (`#h`), HTML attribute (`#ha`) and URL (`#hu`) escape helpers.
@@ -128,7 +264,7 @@ Output:
 <code>puts "Hello, World!"</code>
 ```
 
-### Routing helper
+### Routing Helper
 
 Lotus and Lotus::Router integration (`#routes`).
 
@@ -158,6 +294,36 @@ Output:
 <a href="/">Home</a>
 ```
 
+### Number Formatting Helper
+
+Format numbers (`#format_number`).
+
+View:
+
+```ruby
+module Home
+  class Index
+    include Lotus::Helpers
+
+    def visitors_count
+      format_number '1000'
+    end
+  end
+end
+```
+
+Template:
+
+```erb
+<p><%= visitors_count %></p>
+```
+
+Output:
+
+```html
+<p>1,000</p>
+```
+
 ## Philosophy
 
 All the Lotus helpers are modules to include.

data/lib/lotus/helpers.rb

@@ -2,6 +2,9 @@ require 'lotus/helpers/version'
 require 'lotus/helpers/html_helper'
 require 'lotus/helpers/escape_helper'
 require 'lotus/helpers/routing_helper'
+require 'lotus/helpers/link_to_helper'
+require 'lotus/helpers/form_helper'
+require 'lotus/helpers/number_formatting_helper'
 
 module Lotus
   # View helpers for Ruby applications
@@ -21,6 +24,9 @@ module Lotus
         include Lotus::Helpers::HtmlHelper
         include Lotus::Helpers::EscapeHelper
         include Lotus::Helpers::RoutingHelper
+        include Lotus::Helpers::LinkToHelper
+        include Lotus::Helpers::FormHelper
+        include Lotus::Helpers::NumberFormattingHelper
       end
     end
   end

data/lib/lotus/helpers/form_helper.rb

@@ -0,0 +1,423 @@
+require 'lotus/helpers/form_helper/form_builder'
+
+module Lotus
+  module Helpers
+    # Form builder
+    #
+    # By including <tt>Lotus::Helpers::FormHelper</tt> it will inject one public method: <tt>form_for</tt>.
+    # This is a HTML5 form builder.
+    #
+    # To understand the general HTML5 builder syntax of this framework, please
+    # consider to have a look at <tt>Lotus::Helpers::HtmlHelper</tt> documentation.
+    #
+    # This builder is independent from any template engine.
+    # This was hard to achieve without a compromise: the form helper should be
+    # used in one output block in a template or as a method in a view (see the examples below).
+    #
+    # Features:
+    #
+    #   * Support for complex markup without the need of concatenation
+    #   * Auto closing HTML5 tags
+    #   * Support for view local variables
+    #   * Method override support (PUT/PATCH/DELETE HTTP verbs aren't understood by browsers)
+    #   * Automatic generation of HTML attributes for inputs: <tt>id</tt>, <tt>name</tt>, <tt>value</tt>
+    #   * Allow to override HTML attributes
+    #   * Extract values from request params and fill <tt>value</tt> attributes
+    #   * Automatic selection of current value for radio button and select inputs
+    #   * Infinite nested fields
+    #
+    # Supported tags and inputs:
+    #
+    #   * <tt>color_field</tt>
+    #   * <tt>date_field</tt>
+    #   * <tt>datetime_field</tt>
+    #   * <tt>datetime_local_field</tt>
+    #   * <tt>email_field</tt>
+    #   * <tt>hidden_field</tt>
+    #   * <tt>file_field</tt>
+    #   * <tt>fields_for</tt>
+    #   * <tt>form_for</tt>
+    #   * <tt>label</tt>
+    #   * <tt>text_field</tt>
+    #   * <tt>password_field</tt>
+    #   * <tt>radio_button</tt>
+    #   * <tt>select</tt>
+    #   * <tt>submit</tt>
+    #
+    # @since x.x.x
+    #
+    # @see Lotus::Helpers::FormHelper#form_for
+    # @see Lotus::Helpers::HtmlHelper
+    #
+    # @example One output block (template)
+    #   <%=
+    #     form_for :book, routes.books_path do
+    #       text_field :title
+    #
+    #       submit 'Create'
+    #     end
+    #   %>
+    #
+    # @example Method (view)
+    #   require 'lotus/helpers'
+    #
+    #   class MyView
+    #     include Lotus::Helpers::FormHelper
+    #
+    #     def my_form
+    #       form_for :book, routes.books_path do
+    #         text_field :title
+    #       end
+    #     end
+    #   end
+    #
+    #   # Corresponding template:
+    #   #
+    #   #  <%= my_form %>
+    module FormHelper
+      # Default HTTP method for form
+      #
+      # @since x.x.x
+      # @api private
+      DEFAULT_METHOD = 'POST'.freeze
+
+      # Default charset
+      #
+      # @since x.x.x
+      # @api private
+      DEFAULT_CHARSET = 'utf-8'.freeze
+
+      # CSRF Token session key
+      #
+      # This key is shared with <tt>lotusrb</tt>, <tt>lotus-controller</tt>.
+      #
+      # @since x.x.x
+      # @api private
+      CSRF_TOKEN = :_csrf_token
+
+      # Form object
+      #
+      # @since x.x.x
+      class Form
+        # @return [Symbol] the form name
+        #
+        # @since x.x.x
+        # @api private
+        attr_reader :name
+
+        # @return [String] the form action
+        #
+        # @since x.x.x
+        # @api private
+        attr_reader :url
+
+        # @return [::Hash] the form values
+        #
+        # @since x.x.x
+        # @api private
+        attr_reader :values
+
+        # Initialize a form
+        #
+        # It accepts a set of values that are used in combination with request
+        # params to autofill <tt>value</tt> attributes for fields.
+        #
+        # The keys of this Hash, MUST correspond to the structure of the (nested)
+        # fields of the form.
+        #
+        # For a given input where the <tt>name</tt> is `book[title]`, Lotus will
+        # look for `:book` key in values.
+        #
+        # If the current params have the same key, it will be PREFERRED over the
+        # given values.
+        #
+        # For instance, if <tt>params.get('book.title')</tt> equals to
+        # <tt>"TDD"</tt> while <tt>values[:book].title</tt> returns
+        # <tt>"No test"</tt>, the first will win.
+        #
+        # @param name [Symbol] the name of the form
+        # @param url [String] the action of the form
+        # @param values [Hash,NilClass] a Hash of values to be used to autofill
+        #   <tt>value</tt> attributes for fields
+        # @param attributes [Hash,NilClass] a Hash of attributes to pass to the
+        #   <tt>form</tt> tag
+        #
+        # @since x.x.x
+        #
+        # @example Pass A Value
+        #   # Given the following view
+        #
+        #   module Web::Views::Deliveries
+        #     class Edit
+        #       include Web::View
+        #
+        #       def form
+        #         Form.new(:delivery, routes.delivery_path(id: delivery.id),
+        #         {delivery: delivery, customer: customer},
+        #         {method: :patch})
+        #       end
+        #     end
+        #   end
+        #
+        #   # And the corresponding template:
+        #
+        #   <%=
+        #     form_for form do
+        #       date_field :delivered_on
+        #
+        #       fields_for :customer do
+        #         text_field :name
+        #
+        #         fields_for :address do
+        #           # ...
+        #           text_field :city
+        #         end
+        #       end
+        #
+        #       submit 'Update'
+        #     end
+        #   %>
+        #
+        #   # It will render:
+        #   #
+        #   #  <form action="/deliveries/1" method="POST" accept-charset="utf-8">
+        #   #    <input type="hidden" name="_method" value="PATCH">
+        #   #
+        #   #    # Value taken from delivery.delivered_on
+        #   #    <input type="date" name="delivery[delivered_on]" id="delivery-delivered-on" value="2015-05-27">
+        #   #
+        #   #    # Value taken from customer.name
+        #   #    <input type="text" name="delivery[customer][name]" id="delivery-customer-name" value="Luca">
+        #   #
+        #   #    # Value taken from customer.address.city
+        #   #    <input type="text" name="delivery[customer][address][city]" id="delivery-customer-address-city" value="Rome">
+        #   #
+        #   #    <button type="submit">Update</button>
+        #   #  </form>
+        def initialize(name, url, values = {}, attributes = {})
+          @name       = name
+          @url        = url
+          @values     = values
+          @attributes = attributes || {}
+        end
+
+        # Return the method specified by the given attributes or fall back to
+        # the default value
+        #
+        # @return [String] the method for the action
+        #
+        # @since x.x.x
+        # @api private
+        #
+        # @see Lotus::Helpers::FormHelper::DEFAULT_METHOD
+        def verb
+          @attributes.fetch(:method, DEFAULT_METHOD)
+        end
+      end
+
+      # Instantiate a HTML5 form builder
+      #
+      # @overload form_for(name, url, options, &blk)
+      #   Use inline values
+      #   @param name [Symbol] the toplevel name of the form, it's used to generate
+      #     input names, ids, and to lookup params to fill values.
+      #   @param url [String] the form action URL
+      #   @param options [Hash] HTML attributes to pass to the form tag and form values
+      #   @option options [Hash] :values An optional payload of objects to pass
+      #   @param blk [Proc] A block that describes the contents of the form
+      #
+      # @overload form_for(form, attributes, &blk)
+      #   Use Form
+      #   @param form [Lotus::Helpers::FormHelper::Form] a form object
+      #   @param attributes [Hash] HTML attributes to pass to the form tag and form values
+      #   @param blk [Proc] A block that describes the contents of the form
+      #
+      # @return [Lotus::Helpers::FormHelper::FormBuilder] the form builder
+      #
+      # @since x.x.x
+      #
+      # @see Lotus::Helpers::FormHelper
+      # @see Lotus::Helpers::FormHelper::Form
+      # @see Lotus::Helpers::FormHelper::FormBuilder
+      #
+      # @example Inline Values In Template
+      #   <%=
+      #     form_for :book, routes.books_path, class: 'form-horizontal' do
+      #       div do
+      #         label      :title
+      #         text_field :title, class: 'form-control'
+      #       end
+      #
+      #       submit 'Create'
+      #     end
+      #   %>
+      #
+      #   Output:
+      #     # <form action="/books" method="POST" accept-charset="utf-8" id="book-form" class="form-horizontal">
+      #     #   <div>
+      #     #     <label for="book-title">Title</label>
+      #     #     <input type="text" name="book[title]" id="book-title" value="Test Driven Development">
+      #     #   </div>
+      #     #
+      #     #   <button type="submit">Create</button>
+      #     # </form>
+      #
+      #
+      #
+      # @example Use In A View
+      #
+      #   module Web::Views::Books
+      #     class New
+      #
+      #     def form
+      #       form_for :book, routes.books_path, class: 'form-horizontal' do
+      #         div do
+      #           label      :title
+      #           text_field :title, class: 'form-control'
+      #         end
+      #
+      #         submit 'Create'
+      #       end
+      #     end
+      #   end
+      #
+      #   <%= form %>
+      #
+      #   Output:
+      #     # <form action="/books" method="POST" accept-charset="utf-8" id="book-form" class="form-horizontal">
+      #     #   <div>
+      #     #     <label for="book-title">Title</label>
+      #     #     <input type="text" name="book[title]" id="book-title" value="Test Driven Development">
+      #     #   </div>
+      #     #
+      #     #   <button type="submit">Create</button>
+      #     # </form>
+      #
+      # @example Share Code Between Views
+      #
+      #   # Given the following views to create and update a resource
+      #   module Web::Views::Books
+      #     class New
+      #       include Web::View
+      #
+      #       def form
+      #         Form.new(:book, routes.books_path)
+      #       end
+      #
+      #       def submit_label
+      #         'Create'
+      #       end
+      #     end
+      #
+      #     class Edit
+      #       include Web::View
+      #
+      #       def form
+      #         Form.new(:book, routes.book_path(id: book.id),
+      #           {book: book}, {method: :patch})
+      #       end
+      #
+      #       def submit_label
+      #         'Update'
+      #       end
+      #     end
+      #   end
+      #
+      #   # The respective templates can be identical:
+      #
+      #   ## books/new.html.erb
+      #   <%= render partial: 'books/form' %>
+      #
+      #   ## books/edit.html.erb
+      #   <%= render partial: 'books/form' %>
+      #
+      #   # While the partial can have the following markup:
+      #
+      #   ## books/_form.html.erb
+      #   <%=
+      #     form_for form, class: 'form-horizontal' do
+      #       div do
+      #         label      :title
+      #         text_field :title, class: 'form-control'
+      #       end
+      #
+      #       submit submit_label
+      #     end
+      #   %>
+      #
+      #   Output:
+      #     # <form action="/books" method="POST" accept-charset="utf-8" id="book-form" class="form-horizontal">
+      #     #   <div>
+      #     #     <label for="book-title">Title</label>
+      #     #     <input type="text" name="book[title]" id="book-title" value="Test Driven Development">
+      #     #   </div>
+      #     #
+      #     #   <button type="submit">Create</button>
+      #     # </form>
+      #
+      # @example Method override
+      #   <%=
+      #     form_for :book, routes.book_path(id: book.id), method: :put do
+      #       text_field :title
+      #
+      #       submit 'Update'
+      #     end
+      #   %>
+      #
+      #   Output:
+      #     # <form action="/books/23" accept-charset="utf-8" id="book-form" method="POST">
+      #     #   <input type="hidden" name="_method" value="PUT">
+      #     #   <input type="text" name="book[title]" id="book-title" value="Test Driven Development">
+      #     #
+      #     #   <button type="submit">Update</button>
+      #     # </form>
+      #
+      # @example Nested fields
+      #   <%=
+      #     form_for :delivery, routes.deliveries_path do
+      #       text_field :customer_name
+      #
+      #       fields_for :address do
+      #         text_field :city
+      #       end
+      #
+      #       submit 'Create'
+      #     end
+      #   %>
+      #
+      #   Output:
+      #     # <form action="/deliveries" accept-charset="utf-8" id="delivery-form" method="POST">
+      #     #   <input type="text" name="delivery[customer_name]" id="delivery-customer-name" value="">
+      #     #   <input type="text" name="delivery[address][city]" id="delivery-address-city" value="">
+      #     #
+      #     #   <button type="submit">Create</button>
+      #     # </form>
+      def form_for(name, url, options = {}, &blk)
+        form = if name.is_a?(Form)
+          options = url
+          name
+        else
+          Form.new(name, url, options.delete(:values))
+        end
+
+        attributes = { action: form.url, method: form.verb, :'accept-charset' => DEFAULT_CHARSET, id: "#{ form.name }-form" }.merge(options)
+        FormBuilder.new(form, attributes, self, &blk)
+      end
+
+      # Returns CSRF Protection Token stored in session.
+      #
+      # It returns <tt>nil</tt> if sessions aren't enabled or the value is missing.
+      #
+      # @return [String,NilClass] token, if present
+      #
+      # @since x.x.x
+      def csrf_token
+        if defined?(session)
+          session[CSRF_TOKEN]
+        elsif defined?(locals) && locals[:session]
+          locals[:session][CSRF_TOKEN]
+        end
+      end
+    end
+  end
+end