express_templates 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fa578b4bff63a2306c2281d561cf315fa245230c
-  data.tar.gz: e717b4ddb4f8d244ed21cd48a39c4613c98f3738
+  metadata.gz: 833fc8181d87deb3b99763fb91dfdad3b48c6c9e
+  data.tar.gz: cb4037d2a9bcd7c2e3084ea9ec2026693f71da5e
 SHA512:
-  metadata.gz: 76620daed87fdd884e9ea2089858c76d7fb1bac437af8c8983bea28c904b718f98f63cab711ce41762d40a59e709eced84744a17431d6d56076c0fc45ae39337
-  data.tar.gz: f5f198c833e6afbb2dd92eda33deb1fe81f384947ccf5972f4dc11825d675a30e84105bfa010a978729ea15f8bda89e5161684309fbb087f26e8d3ce17b31016
+  metadata.gz: e2040b7bf2a3fb485bd6d454532c41b3467700efaac36f50333fcd9d8c16d0055f77bd3888640f11f9dc972540504697cf9e92818aaab8ba19c24ecbcc9cd71b
+  data.tar.gz: 79e23baf7ea8315fbd06f85b6433b658c233847973de3ddc07d20ddc7cb086c183aee8858bc856e1d24a7c3dd9e2ad234a6151715c096245b8223217f76994aa

data/README.md

@@ -58,11 +58,11 @@ ExpressTemplates introduces an earlier step in this process, "expansion", which
 
 ## Constraints - Important!
 
-ExpressTemplates imposes some constraints.  The most important constraint is that your view templates must be declaritive in syntax and style.  Declaritve code is easier to read and reason about.  It also requires fewer tests since declarative code is build on presumably well-tested primitives.
+ExpressTemplates imposes some constraints.  The most important constraint is that your view templates must be declarative in style.  They should not contain conditional logic.  Declarative code is easier to read and reason about.  It also requires fewer tests since declarative code is build on presumably well-tested primitives.
 
-With ExpressTemplates, one *must not* simply introduce conditional logic or iterators anywhere one feels like it in template code.  All logic *must* be encapsulated in components.  Strange things will happen if you try to put logic in the template or a template fragment.
+With ExpressTemplates, one *must not* place conditional logic or iterators anywhere in template code.  All logic *must* be encapsulated in components.  Strange things will happen if you try to put logic in the template or a template fragment.  In the future I may issue warnings or disallow it by examinging the output of Ruby's tokenizer.
 
-If you have been around long enough to see a few Rails codebases grow out of control, and you have had to manage or watch the efforts of less-experienced developers closely, you know that one of the major causes of trouble and wasted effort is copy-and-paste code and logic errors in the view.  Another common problem is the "blank slate" issue wherein every view must be constructed new with little chance for proper reuse of code.  Diligent use of partials and helpers can do much to DRY up view code but deciding where to put them or how to share them between projects can be difficult.  Rarely is view logic tested except in integration.
+If you have been around long enough to see a few Rails codebases grow out of control, and you have had to manage or watch the efforts of less-experienced developers closely, you know that one of the major causes of trouble and wasted effort is copy-and-paste code and logic errors in the view.  Another common problem is the "blank slate" issue wherein every view must be constructed new with little chance for higher-level reuse of code.  Diligent use of partials and helpers can do much to DRY up view code but deciding where to put them or how to share them between projects can be difficult.  Rarely is view logic tested except in integration.
 
 ExpressTemplates only enforces what is already considered a best practice by many, while introducing new possilibities for well-ordered UX libraries similar to what developers working with commercial frameworks for desktop operating systems or mobile devices enjoy.
 
@@ -82,7 +82,13 @@ ul {
 
 Let us suppose that an @three variable exists in the view context with the value "three".  This would yield the following markup:
 
-    <ul><li>one</li><li>two</li><li>three</li>
+```html
+<ul>
+  <li>one</li>
+  <li>two</li>
+  <li>three</li>
+</ul>
+```
 
 yield and local variables which we may expect to be available in a ViewContext are also wrapped for evaluation later.
 
@@ -129,7 +135,15 @@ div.active {
 
 Now when the template renders, it will yield:
 
-    <div class="active"><ul><li>one</li><li>two</li><li>three</li></ul></div>
+```html
+<div class="active">
+  <ul>
+    <li>one</li>
+    <li>two</li>
+    <li>three</li>
+  </ul>
+</div>
+```
 
 ## Background
 

data/lib/express_templates/components.rb

@@ -12,5 +12,7 @@ require 'express_templates/components/unless_block'
 require 'express_templates/components/row'
 require 'express_templates/components/column'
 require 'express_templates/components/form_rails_support'
+require 'express_templates/components/form_for'
 require 'express_templates/components/content_for'
 require 'express_templates/components/table_for'
+require 'express_templates/components/tree_for'

data/lib/express_templates/components/capabilities/parenting.rb

@@ -45,7 +45,7 @@ module ExpressTemplates
 
           def compile
             null_wrapped_children = "null_wrap { #{compile_children} }"
-            wrap_children_src = self.class[:markup].source.gsub(/\W_yield\W/, null_wrapped_children)
+            wrap_children_src = self.class[:markup].source.gsub(/(\s)_yield(\s)/, '\1'+null_wrapped_children+'\2')
             _compile_fragment(Proc.from_source(wrap_children_src))
           end
 

data/lib/express_templates/components/capabilities/wrapping.rb

@@ -16,7 +16,7 @@ module ExpressTemplates
       #
       #     for_each -> { menu_items }
       #
-      #     wrap_with :wrapper
+      #     wrap_with :menu_wrapper
       #
       #   end
       #

data/lib/express_templates/components/content_for.rb

@@ -10,6 +10,10 @@ module ExpressTemplates
     #   h1 "Title"
     # }
     # ```
+    # Or:
+    # ```ruby
+    # content_for(:page_title), "People"
+    # ```
     class ContentFor < Container
       include Capabilities::Configurable
       def compile
@@ -35,4 +39,4 @@ module ExpressTemplates
       end
     end
   end
-end
+end

data/lib/express_templates/components/for_each.rb

@@ -25,4 +25,4 @@ module ExpressTemplates
       end
     end
   end
-end
+end

data/lib/express_templates/components/form_for.rb

@@ -5,15 +5,382 @@ module ExpressTemplates
     #
     # Example:
     #
-    # ```ruby
-    # form_for(:people) do |t|
-    #   t.text_field  :name
-    #   t.email_field :email
-    #   t.phone_field :phone
+    # ````ruby
+    # form_for(:people) do |f|
+    #   f.text_field  :name
+    #   f.email_field :email
+    #   f.phone_field :phone, wrapper_class: 'field phone'
+    #   f.submit 'Save'
     # end
-    # ```
+    # ````
     #
-    class FormFor < Container
+    # This assumes that @people variable will exist in the
+    # view and that it will be a collection whose members respond to :name, :email etc.
+    #
+    # This will result in markup like the following:
+    #
+    # ````
+    # <form action="/people" method="post">
+    #   <div style="display:none">
+    #     <input name="utf8" type="hidden" value="✓">
+    #     <input type="hidden" name="_method" value="post">
+    #     <input type="hidden" name="authenticity_token" value="5ZDztTe1N4tc03QSjmMdSVqAw==">
+    #   </div>
+    #
+    #   <div>
+    #     <label for="person_name">Name</label>
+    #     <input type="text" name="person[name]" id="person_name" />
+    #   </div>
+    #
+    #   <div>
+    #     <label for="person_email">Email</label>
+    #     <input type="email" name="person[email]" id="person_email" />
+    #   </div>
+    #
+    #   <div class="field phone">
+    #     <label for="person_phone">Phone</label>
+    #     <input type="tel" name="person[phone]" id="person_phone" />
+    #   </div>
+    #
+    #   <div>
+    #     <input type="submit" name="commit" value="Save" />
+    #   </div>
+    # </form>
+    # ````
+    #
+    # As seen above, each field is accompanied by a label and is wrapped by a div.
+    # The div can be further styled by adding css classes to it via the `wrapper_class` option.
+    #
+    # Example:
+    #
+    # ````ruby
+    # form_for(:posts) do
+    #   f.text_field :title, wrapped_class: 'string optional'
+    # end
+    #
+    # Will result to generating HTML like so:
+    #
+    # ````
+    #   ...
+    #   <div class='string optional'>
+    #     <label for='post_title'>Title</label>
+    #     <input type="text" name="post[title]" id="post_title" />
+    #   </div>
+    #   ...
+    # ````
+    #
+    # In addition to this, label text can also be customized using the `label` option:
+    #
+    # ````ruby
+    #   f.email_field :email_address, label: 'Your Email'
+    # ````
+    #
+    # Compiles to;
+    # ````
+    #   <label for='user_email'>Your Email</label>
+    #   <input type='email' name='user[email]' id='user_email' />
+    # ````
+    class FormFor < Base
+      include Capabilities::Configurable
+      include Capabilities::Building
+
+      def initialize(*args)
+        # TODO: need a better way to select the form options
+        @form_options = args.select { |x| x.is_a?(Hash) }
+        super(*args)
+        _process_args!(args) # from Configurable
+        yield(self) if block_given?
+      end
+
+      attr :fields
+
+      # Express Templates uses Rails' form helpers to generate the fields with labels
+      #
+      # Example:
+      #
+      # ````ruby
+      # form_for(:people) do |f|
+      #   f.phone_field :phone
+      # end
+      # ````
+      #
+      # This will precompile as
+      #
+      # ````ruby
+      #    ...
+      #    phone_field_tag :phone, @people.phone, {}
+      #    ...
+      # ````
+      #
+      # Fields can also have custom classes via the `class` option:
+      #
+      # Example:
+      #
+      # ````ruby
+      #    f.url_field :website_url, class: 'url-string'
+      # ````
+      #
+      # Compiles to:
+      #
+      # ````
+      #    <input type='url' name='post[website_url]' id='post_website_url' class='url-string' />
+      # ````
+      #
+      # You can also add in the basic options supported by the
+      # phone_field_tag [here](http://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html#method-i-phone_field_tag)
+      #
+      # This applies to all the other '_field_tags' listed
+      # [here](http://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html)
+      #
+      #
+      # = Fields
+      # ````ruby
+      # f.text_field :name
+      # #   <div>
+      # #    <label for="person_name">Name</label>
+      # #    <input type="text" name="person[name]" id="person_name" />
+      # #   </div>
+      #
+      # f.text_field :name, label: 'post title'
+      # #   <div>
+      # #    <label for="person_name">Post Title</label>
+      # #    <input type="text" name="person[name]" id="person_name" />
+      # #   </div>
+      #
+      # f.text_field :name, class: 'string'
+      # #   <div>
+      # #    <label for="person_name">Name</label>
+      # #    <input type="text" name="person[name]" class='string' id="person_name" />
+      # #   </div>
+      #
+      # f.text_field :name, wrapper_class: 'field input'
+      # #   <div class="field input">
+      # #    <label for="person_name">Name</label>
+      # #    <input type="text" name="person[name]" id="person_name" />
+      # #   </div>
+      #
+      # ````
+      %w(email phone text password color date datetime
+        datetime_local hidden number range
+        search telephone time url week).each do |type|
+        define_method("#{type}_field") do |name, options={}|
+          @fields ||= []
+          @fields << Field.new(name, options, type.to_sym)
+        end
+      end
+
+      # ==== Examples
+      #   f.select :gender, ['Male', 'Female'], selected: 'Male'
+      #   # <div>
+      #   #   <label for="person_gender">Gender</label>
+      #   #   <select id="person_gender" name="person[gender]">
+      #   #     <option selected="selected" value="Male">Male</option>
+      #   #     <option selected="selected" value="Female">Female</option>
+      #   #   </select>
+      #   # </div>
+      #   f.select :name, options_from_collection_for_select(@people, "id", "name")
+      #   # <div>
+      #   #   <label for="person_name">Name</label>
+      #   #   <select id="people_name" name="people[name]"><option value="1">David</option></select>
+      #   # </div>
+      #
+      def select(name, select_options, options = {})
+        @fields ||= []
+        @fields << Select.new(name, options.merge!(select_options: select_options))
+      end
+
+      # ==== Examples
+      #   f.radio :card, [[1, 'One'], [2, 'Two']], :first, :last
+      #   # <div>
+      #   #   <label class="radio" for="user_age_1"><input type="radio" value="1" name="user[age]" id="user_age_1">One</label>
+      #   #   <label class="radio" for="user_age_2"><input type="radio" value="2" name="user[age]" id="user_age_2">Two</label>
+      #   # </div>
+      #
+      def radio(name, collection, value_method, text_method, options = {})
+        @fields ||= []
+        @fields << Radio.new(name, options.merge!(collection: collection, value_method: value_method, text_method: text_method))
+      end
+
+      # ==== Examples
+      #   f.checkbox :age, [[1, 'One'], [2, 'Two']], :first, :last
+      #   # <div>
+      #   #   <label class="checkbox" for="user_age_1">
+      #   #     <input type="checkbox" value="1" name="user[age][]" id="user_age_1">
+      #   #     "One"
+      #   #   </label>
+      #   #   <label>
+      #   #     <input type="checkbox" value="2" name="user[age][]" id="user_age_2">
+      #   #     "Two"
+      #   #   </label>
+      #   # </div>
+      #
+      def checkbox(name, collection, value_method, text_method, options = {})
+        @fields ||= []
+        @fields << Checkbox.new(name, options.merge!(collection: collection, value_method: value_method, text_method: text_method))
+      end
+
+      # ==== Examples
+      #   f.text_area :name
+      #   # <div>
+      #   #   <label for="user_name">Name</label>
+      #   #   <textarea name="user[name]" id="user_name" >
+      #   # </div>
+      #   f.text_area :name, label: 'post title'
+      #   # <div>
+      #   #   <label for="user_name">Post Title</label>
+      #   #   <textarea name="user[name]" id="user_name" >
+      #   # </div>
+      #   f.text_area :name, wrapper_class: 'field input'
+      #   # <div class="field input">
+      #   #   <label for="user_name">Name</label>
+      #   #   <textarea name="user[name]" id="user_name" >
+      #   # </div>
+      #   f.text_area :name, class: 'string'
+      #   # <div>
+      #   #   <label for="user_name>Name</label>
+      #   #   <textarea name="user[name] id="user_name" class="string" >
+      #   # </div>
+      #
+      def text_area(name, options = {})
+        @fields ||= []
+        @fields << TextArea.new(name, options)
+      end
+
+      # ==== Examples
+      #   f.submit "Save Changes"
+      #   # <div>
+      #   #   <input type="submit" name="commit" value="Save Changes" />
+      #   # </div>
+      #
+      def submit(name = 'Submit Changes', options = {})
+        @fields ||=[]
+        @fields << Field.new(name, options, :submit)
+      end
+
+      emits -> {
+        resource_name = my[:id].to_s
+        form_options = @form_options.first
+        form_method = form_options.delete :method if form_options
+
+        form_method = if form_method == :put
+                        :patch
+                      else
+                        form_options.present? ?  form_options[:method] : :post
+                      end
+
+        form_action  = if form_method == :patch
+                       %Q(/#{resource_name.pluralize}/{{@#{resource_name}.id}})
+                       else
+                       %Q(/#{resource_name.pluralize})
+                     end
+
+        form_args = {action: form_action, method: :post}
+        form_args.merge!(form_options) unless form_options.nil?
+
+        form(form_args) {
+          form_rails_support form_method
+          fields.each do |field|
+            field_name = field.name
+            field_type = field.type.to_s
+            resource_field_name = "#{resource_name.singularize}[#{field_name}]"
+            label_name = "#{resource_name.singularize}_#{field_name}"
+            field_label = field.label || field_name.to_s.capitalize
+
+            div(class: field.wrapper_class) {
+              if field_type == 'select'
+                label_tag(label_name, field_label)
+                select_tag(resource_field_name, field.options_html, field.options)
+              elsif field_type == 'radio'
+                collection_radio_buttons(my[:id], field_name, field.collection,
+                                         field.value_method, field.text_method, field.options) do |b|
+                  b.label(class: 'radio') { b.radio_button + b.text }
+                end
+              elsif field_type == 'checkbox'
+                collection_check_boxes(my[:id], field_name, field.collection,
+                                       field.value_method, field.text_method, field.options) do |b|
+                  b.label(class: 'checkbox') { b.check_box + b.text }
+                end
+              elsif field_type == 'submit'
+                submit_tag(field_name, field.options)
+              else
+                label_tag(label_name, field_label) unless field_type == 'hidden'
+                args = [resource_field_name, "{{@#{resource_name.singularize}.#{field_name}}}", field.options]
+                tag_string = if field_type == 'text_area'
+                                 'text_area_tag'
+                               else
+                                 "#{field_type}_field_tag"
+                               end
+
+                self.send(tag_string.to_sym, *args)
+              end
+            }
+          end
+        }
+      }
+
+      def wrap_for_stack_trace(body)
+        "ExpressTemplates::Components::FormFor.render_in(self) {\n#{body}\n}"
+      end
+
+      def compile
+        wrap_for_stack_trace(lookup(:markup))
+      end
+
+      class Field
+        attr :name, :options, :label, :type, :wrapper_class
+        def initialize(name, options = {}, type=:text)
+          @name = name
+          @options = options
+          @label = options[:label]
+          @wrapper_class = @options.delete(:wrapper_class)
+          @type = type
+        end
+      end
+
+      class TextArea < Field
+        def initialize(name, options={})
+          super(name, options, :text_area)
+        end
+      end
+
+      class Radio < Field
+        attr :collection, :value_method, :text_method
+        def initialize(name, options = {})
+          @collection = options.delete :collection
+          @value_method = options.delete :value_method
+          @text_method = options.delete :text_method
+          super(name, options, :radio)
+        end
+      end
+
+      class Checkbox < Radio
+        def initialize(name, options = {})
+          super(name, options)
+          @type = :checkbox
+        end
+      end
+
+      class Select < Field
+        attr :choices
+        def initialize(name, options = {})
+          @choices = options.delete :select_options
+          @selected = options.delete :selected
+          super(name, options, :select)
+        end
+
+        def options_html
+          choice_string = ""
+          if @choices.is_a?(String)
+            choice_string = @choices
+          else
+            @choices.map do |choice|
+              selected_string = (@selected != nil && choice == @selected) ? 'selected=selected' : nil
+              choice_string << "<option #{selected_string}>#{choice}</option>"
+            end
+            "{{'#{choice_string}'.html_safe}}"
+          end
+        end
+      end
     end
   end
-end
+end