express_templates 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7e3c4b0da15f9c3a8e15afd1cd406974c6a77830
-  data.tar.gz: 4fcaadfa00a739490b71b7a9539778aa3a7019e8
+  metadata.gz: 16f46943cd687967eb9ed04ce0beaa6cff6d251a
+  data.tar.gz: 04be2d8eae0f12e801b87ba6dfa23367e2c20642
 SHA512:
-  metadata.gz: 4ad45dd634f82597ad578c21047556a4770ad76f05b7b92e344fbbde27993dc69a7ff1d53dd3c0c116e9dadc0f444633ea6dc325cf1a7cbcb596179946bea615
-  data.tar.gz: 1a67f14a59f8eac2b61a840376c0ff2ab1607a2e41533c6fa1543c5caa1ce7811a3d2d0b7b4ca3a66b745d8d38e2cfd99efafbf94d78a056284b187b163ea72b
+  metadata.gz: b6bbead39fc3d366d5c11050a2b4b39aa9989f258b9fe5924824b3caa577227b729dfed4abbd66978f9c9bd270831e6b0c24b97cf07949439be5522bcd884aad
+  data.tar.gz: 9cd09d8d5fcc54f8e261a09bb4836d14242b14de4e56947c0e0c8e17907b0cc0635640b0e66dc73d12e21e2b2bf5744baec084b69ce024a2392ef52ba9a5c129

data/README.md

@@ -2,6 +2,10 @@
 
 Provides a DSL for HTML templates using a declarative style of Ruby as an alternative to Erb or HAML.
 
+Although originally we implemented our own DSL and used a code generation approach,
+this gem now uses [ActiveAdmin's arbre](https://github.com/activeadmin/arbre).  Arbre is widely
+used as part of ActiveAdmin, has a long history and many contributors and is conceptually much simpler.
+
 ## Usage
 
 Add this to your gemfile:
@@ -26,7 +30,7 @@ html(lang: "en") {
     csrf_meta_tags
   }
   body {
-    yield
+    current_arbre_element.add_child yield
     javascript_include_tag "application"
   }
 }
@@ -36,35 +40,18 @@ Everything should work as you would expect.
 
 Set your editor syntax for .et files to Ruby.
 
-You will now have also be able to utilize components which are found with documentation and examples in <tt>ExpressTemplates::Components<tt>.
-
-## History
-
-To understand ExpressTemplates, you must first understand the standard tools of ERB and Haml which have been with us for quite some time.
-
-![Haml/Erb Diagram](https://raw.githubusercontent.com/aelogica/express_templates/master/diagrams/diagram_haml_erb.png "Haml/Erb Diagram")
-
-Both of these provide a language for embedding other languages.  Erb embeds Ruby between <% %> style tags.  This is similar to the way we worked with PHP and for those who can remember "embedded Perl" in 1990s.  Erb places no constraints on either the text into which the Ruby is embedded, nor on the Ruby which may be placed within the delimiters which comprise Erb's simple grammar.
-
-Haml introduced a number of innovations or improvements upon Erb.  Through Haml's use of significant whitespace and indentation, it ensures well-formed markup.  This noticably slows template compilation, however, due to caching it generally goes unnoticed.  Haml added better support for mixing grammars in a single file as is common practice with Javascript.  Haml introduced abbreviated methods for specifying CSS classes and HTML entity attribute values with the result of generally cleaning up view code.
+You can now utilize components which are found with documentation and examples in <tt>ExpressTemplates::Components<tt>.
 
-Both Haml and Erb compile down to Ruby code which must be eval()'d in a View Context as per the interface required by Rails' ActionView.
+Components are the real strength of both arbre and express_templates.
 
-## Expansion
+express_templates now *is* arbre + some components + some conventions.  ExpressTemplates::Components::Base provides a little syntactic sugar in the form of the emits class method.
 
-ExpressTemplates introduces an earlier step in this process, "expansion", which may be likened to a kind of macro system.  This is introduced to facilitate reusable view components in the form of normal object-oriented Ruby classes.
+In terms of conventions, we use brace blocks { } to indicate html structure and do/end blocks to indicate control flow.
 
-![Diagram depciting Haml/Erb](https://raw.githubusercontent.com/aelogica/express_templates/master/diagrams/diagram_express_templates.png "Diagram depciting Haml/Erb")
+Control flow should only be used in Components.  This is currently not enforced but it will be in the future.
 
-## Constraints - Important!
+The purpose of express_templates is to provide a foundation for a library of reusable UX components which we can enhance for drag-and-drop style UX construction and template editing.
 
-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* 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 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.
 
 ## Block Structure
 
@@ -90,8 +77,6 @@ Let us suppose that an @three variable exists in the view context with the value
 </ul>
 ```
 
-yield and local variables which we may expect to be available in a ViewContext are also wrapped for evaluation later.
-
 ## Components
 
 Given the constraint that logic must not go in the template, where does one put it?  The answer is we make a component!
@@ -108,27 +93,23 @@ We can make a simple component like so:
 
 ```ruby
 class ListComponent < ExpressTemplates::Components::Base
-  emits inner: -> {
-                    li {
-                      item
-                    }
-                  },
-        outer: -> {
-                    ul {
-                      _yield
-                    }
-                  }
-
-  for_each -> { @list }, emit: :inner
-
-  wrap_with :outer
+  emits -> {
+    ul {
+      # assumes view provides list
+      list.each do |item|
+        li {
+          item
+        }
+      end
+    }
+  }
 end
 ```
 
 This would be used in a view template just as if it were a tag, like so:
 
 ```ruby
-div.active {
+div(class: "active") {
   list_component
 }
 ```

data/lib/arbre/patches.rb

@@ -0,0 +1,50 @@
+module Arbre
+  class Context
+    def resource
+      helpers.resource
+    end
+  end
+
+  class Element
+
+    module BuilderMethods
+
+      # we do not want to check the arity of the
+      # block in express templates because components
+      # are expected to be able to contain other components or template code
+      # without use of a builder style syntax
+      def build_tag(klass, *args, &block)
+        tag = klass.new(arbre_context)
+        tag.parent = current_arbre_element
+
+        with_current_arbre_element tag do
+          tag.build(*args, &block)
+        end
+
+        tag
+      end
+    end
+
+    # Implements the method lookup chain. When you call a method that
+    # doesn't exist, we:
+    #
+    #  1. Try to call the method on the current DOM context
+    #  2. Return an assigned variable of the same name
+    #  3. Call the method on the helper object
+    #  4. Call super
+    #
+    def method_missing(name, *args, &block)
+      if current_arbre_element.respond_to?(name)
+        current_arbre_element.send name, *args, &block
+      elsif assigns && assigns.has_key?(name)
+        assigns[name]
+      elsif helpers.respond_to?(name)
+        current_arbre_element.add_child helpers.send(name, *args, &block)
+      else
+        super
+      end
+    end
+
+  end
+
+end

data/lib/core_extensions/proc.rb

@@ -24,6 +24,7 @@ class Proc
   def source
     @source ||= begin
       file, line_no = source_location
+      raise "no file provided by source_location: #{self}" if file.nil?
       raise "no line number provided for source_location: #{self}" if line_no.nil?
       tokens =  Ripper.lex File.read(file)
       tokens_on_line = tokens.select {|pos, lbl, str| pos[0].eql?(line_no) }

data/lib/express_templates/compiler.rb

@@ -1,3 +1,4 @@
+require 'ostruct'
 module ExpressTemplates
   module Compiler
     def compile(template_or_src=nil, &block)
@@ -12,13 +13,7 @@ module ExpressTemplates
 
       template, src = _normalize(template_or_src)
 
-      expander = Expander.new(template)
-
-      compiled = expander.expand(src, &block).map(&:compile)
-
-      return Interpolator.transform(compiled.join("+").gsub('"+"', '')).tap do |s|
-        puts("\n"+template.inspect+"\nSource:\n#{template.try(:source)}\nInterpolated:\n#{s}\n") if ENV['DEBUG'].eql?('true')
-      end
+      %Q[Arbre::Context.new(assigns.merge(template_virtual_path: @virtual_path), self) { #{src || block.source_body} }.to_s]
     end
 
     private

data/lib/express_templates/components/base.rb

@@ -5,50 +5,46 @@ module ExpressTemplates
   # Components provide self-contained reusable view code meant to be shared
   # within a project or across many projects through a library of components
   #
-  # Components gain their functionality through inclusion of Capabilities.
-  #
-  # Most Components are descendents of Components::Base.
-  #
   module Components
 
     # Components::Base is the base class for ExpressTemplates view components.
     #
-    # View components are available as macros in ExpressTemplates and may be
-    # used to encapsulate common view patterns, behavior and functionality in
-    # reusable classes that can be shared within and across projects.
-    #
-    # Components intended to provide a base framework for a library of reusable
-    # components to cut development time across a multitude of projects.
-    #
-    # Components gain their functionality through including Capabilities.
-    #
-    # Example capabilities include:
-    #
-    # * Managing related ExpressTemplate fragments
-    # * Compiling template fragments for evaluation in a View Context
-    # * Specifying rendering logic to be executed in the View Context
-    # * Potentially referencing external assets that may be required
-    #   for the component to work.
     #
-    # Components::Base includes the following capabilities:
-    #
-    # * Capabilities::Templating
-    # * Capabilities::Rendering
-    # * Capabilities::Wrapping
-    # * Capabilities::Iterating
-    #
-    class Base < Expander
-      include ExpressTemplates::Macro
-      include Capabilities::Templating
-      include Capabilities::Rendering
-      include Capabilities::Wrapping
-      include Capabilities::Iterating
-
-      def self.inherited(klass)
-        ExpressTemplates::Expander.register_macros_for klass
+    class Base < Arbre::Component
+
+      def self.builder_method_and_class(method_name, klass)
+        Arbre::Element::BuilderMethods.class_eval <<-EOF, __FILE__, __LINE__
+          def #{method_name}(*args, &block)
+            insert_tag ::#{klass.name}, *args, &block
+          end
+        EOF
+        # puts "added #{method_name} -> #{klass.name}"
       end
 
-    end
+      def self.emits(proc = nil, &block)
+        define_method(:build, &(proc || block))
+      end
 
+      def build(*args, block)
+        raise "#build method must be overridden"
+      end
+
+      def resource
+        helpers.resource
+      end
+
+      def self.inherited(subclass)
+        builder_method_and_class subclass.to_s.demodulize.underscore, subclass
+      end
+
+      def indent_level
+        parent_indent_level = parent.try(:indent_level) || 0
+      end
+
+      def to_s
+        children.to_s
+      end
+
+    end
   end
 end

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

@@ -4,15 +4,15 @@ module ExpressTemplates
 
       module Resourceful
         def namespace
-          @config[:namespace] || infer_namespace
+          config[:namespace] || infer_namespace
         end
 
         def path_prefix
-          @config[:path_prefix] || infer_path_prefix
+          config[:path_prefix] || infer_path_prefix
         end
 
         def resource_class
-          resource_class = @config[:resource_class] || _namespaced_resource_class
+          resource_class = config[:resource_class] || _namespaced_resource_class
           resource_class.constantize
         end
 
@@ -26,10 +26,17 @@ module ExpressTemplates
           end
         end
 
+        def template_virtual_path
+          begin
+            super
+          rescue
+            nil
+          end
+        end
+
         def infer_namespace
-          expander = @args.last
-          if expander.try(:template)
-            path_parts = expander.template.virtual_path.split('/')
+          if template_virtual_path
+            path_parts = template_virtual_path.split('/')
 
             case
             when path_parts.size == 4
@@ -50,9 +57,8 @@ module ExpressTemplates
         end
 
         def infer_path_prefix
-          expander = @args.last
-          if expander.try(:template)
-            path_parts = expander.template.virtual_path.split('/')
+          if template_virtual_path
+            path_parts = template_virtual_path.split('/')
 
             case
             when path_parts.size == 4
@@ -75,7 +81,7 @@ module ExpressTemplates
         # TODO: this can now be inferred from the template.virtual_path
         # if not supplied...
         def resource_name
-          @config[:id].to_s.singularize
+          config[:id].to_s.singularize
         end
 
         def collection_member_name
@@ -91,14 +97,15 @@ module ExpressTemplates
         end
 
         def collection
-          @config[:collection] || collection_var
+          config[:collection] || helpers.collection
         end
 
         def collection_path
-          if @config[:collection_path]
-            @config[:collection_path]
+          if config[:collection_path]
+            config[:collection_path]
           else
-            "#{collection_name_with_prefix}_path"
+            #super
+            helpers.instance_eval "#{collection_name_with_prefix}_path"
           end
         end
 
@@ -110,11 +117,16 @@ module ExpressTemplates
           end
         end
 
+        def resource_path_helper
+          "#{resource_name_with_path_prefix}_path"
+        end
+
         def resource_path(ivar=false)
-          if @config[:resource_path]
-            @config[:resource_path]
+          if config[:resource_path]
+            config[:resource_path]
           else
-            "#{resource_name_with_path_prefix}_path(#{ivar ? '@' : ''}#{resource_name})"
+            # super
+            helpers.instance_eval("#{resource_path_helper}(#{ivar ? '@' : ''}#{resource_name})")
           end
         end
 
@@ -126,7 +138,7 @@ module ExpressTemplates
           end
         end
 
-        def attributes
+        def resource_attributes
           resource_class.columns
         end
       end

data/lib/express_templates/components/configurable.rb

@@ -0,0 +1,41 @@
+module ExpressTemplates
+  module Components
+    class Configurable < Base
+
+      def self.emits(proc = nil, &block)
+        define_method(:markup, &(proc || block))
+      end
+
+      def build(*args, &block)
+        _process_args!(args)
+        if method(:markup).arity > 0
+          markup(block)
+        else
+          markup(&block)
+        end
+      end
+
+      def config
+        @config ||= {}
+      end
+
+      alias :my :config
+
+
+      protected
+
+        def _process_args!(args)
+          if args.first.kind_of?(Symbol)
+            config.merge!(id: args.shift)
+            attributes[:id] = config[:id]
+          end
+          args.each do |arg|
+            if arg.kind_of?(Hash)
+              config.merge!(arg)
+            end
+          end
+        end
+
+    end
+  end
+end

data/lib/express_templates/components/form_rails_support.rb

@@ -5,16 +5,15 @@ module ExpressTemplates
     # would be provided by Rails' form helpers.
     #
     # An optional method may be speficied.  Defaults to 'post'.
-    class FormRailsSupport < Base
-      include Capabilities::Configurable
-      emits -> {
+    class FormRailsSupport < Configurable
+      emits -> (ctx) {
         div(style: 'display:none') {
-          utf8_enforcer_tag
+          add_child helpers.utf8_enforcer_tag
           # NOTE: This should be moved into the forms module and made a FormComponent
           #       to have access to the resource_name as this code assumes existence of
           #       a resource method which may not exist
-          method_tag(@config[:id] || "{{((resource.persisted? ? :put : :post) rescue :post)}}")
-          token_tag
+          add_child helpers.send(:method_tag, (config[:id] || ((resource.persisted? ? :put : :post) rescue :post)))
+          helpers.send(:token_tag)
         }
       }
     end

data/lib/express_templates/components/forms/basic_fields.rb

@@ -12,7 +12,7 @@ module ExpressTemplates
               emits -> {
                 div(class: field_wrapper_class) {
                   label_tag(label_name, label_text)
-                  #{type}_field resource_var, field_name.to_sym
+                  #{type}_field resource_var, field_name.to_sym, html_options
                 }
               }
             end
@@ -35,19 +35,16 @@ RUBY
         emits -> {
           div(class: field_wrapper_class) {
             label_tag(label_name, label_text)
-            text_area resource_var, field_name.to_sym
+            text_area resource_var, field_name.to_sym, html_options
           }
         }
       end
 
       class Hidden < FormComponent
         emits -> {
-          hidden_field resource_var, field_name.to_sym
+          hidden_field resource_var, field_name.to_sym, html_options
         }
       end
-
-
     end
   end
 end
-

data/lib/express_templates/components/forms/checkbox.rb

@@ -16,7 +16,7 @@ module ExpressTemplates
         end
 
         def label_after?
-          !!@config[:label_after]
+          !!config[:label_after]
         end
 
         def field_options

data/lib/express_templates/components/forms/express_form.rb

@@ -1,55 +1,45 @@
 module ExpressTemplates
   module Components
     module Forms
-      class ExpressForm < Base
-        include Capabilities::Configurable
-        include Capabilities::Parenting
-        include Capabilities::Resourceful
-        include Forms::FormSupport
-
-        emits -> {
-          form( form_args ) {
+      class ExpressForm < Configurable
+        include ExpressTemplates::Components::Capabilities::Resourceful
+
+        emits -> (block) {
+          form(form_tag_options ) {
             form_rails_support form_method
-            _yield
+            block.call(self) if block
           }
         }
 
         def form_id
-          "#{resource_name}_{{@#{resource_name}.id}}"
+          "#{resource_name}_#{resource.id}"
         end
 
         def form_method
-          @config[:method]
+          config[:method].to_s.upcase || 'POST'
         end
 
+        def form_action
+          config[:action] || (resource.try(:persisted?) ? resource_path(ivar: true) : collection_path)
+        end
 
-        def form_args
-          # there are no put/patch emthods in HTML5, so we have to enforce post
-          # need to find a better way to do this: id/action can be overridden but method
-          # should always be :post IN THE FORM TAG
-          args = {id: form_id, action: form_action}.merge!(@config).merge!(method: :post)
+        def form_tag_options
+          args = {id: form_id, action: form_action}.merge!(config).merge!(method: 'POST')
 
           if html_options = args.delete(:html_options)
             args.merge!(html_options)
           end
-          args[:method] = args[:method].to_s.upcase
           args
         end
 
         def resource_name_for_path
-          @config[:id].to_s
+          config[:id].to_s
         end
 
         def resource_name
-          (@config[:resource_name] || @config[:id]).to_s
+          (config[:resource_name] || config[:id]).to_s
         end
 
-        private
-
-          def _modifying_resource?
-            [:put, :patch].include? form_method
-          end
-
       end
     end
   end

data/lib/express_templates/components/forms/form_component.rb

@@ -1,17 +1,11 @@
 module ExpressTemplates
   module Components
     module Forms
-      class FormComponent < Base
-        include Capabilities::Configurable
-        include Capabilities::Adoptable
-
-        def compile(*args)
-          raise "#{self.class} requires a parent ExpressForm" if parent.nil? or parent_form.nil?
-          super(*args)
-        end
+      class FormComponent < Configurable
 
         # Lookup the resource_name from the parent ExpressForm.
         def resource_name
+          raise "FormComponent must have a parent form" unless parent_form
           parent_form.resource_name
         end
 
@@ -30,13 +24,13 @@ module ExpressTemplates
 
         # Return the text content for the label
         def label_text
-          @config[:label] || field_name.titleize
+          config[:label] || field_name.titleize
         end
 
         # Return the field_name as a string.  This taken from the first argument
         # to the component macro in the template or fragment.
         def field_name
-          (@config[:id] || (@args.first.is_a?(String) && @args.first)).to_s
+          (config[:id] || (@args.first.is_a?(String) && @args.first)).to_s
         end
 
         # Return the field name attribute.  Currently handles only simple attributes
@@ -46,7 +40,7 @@ module ExpressTemplates
         end
 
         def field_wrapper_class
-          @config[:wrapper_class] || 'field-wrapper'
+          config[:wrapper_class] || 'field-wrapper'
         end
 
         # Search the parent graph until we find an ExpressForm.  Returns nil if none found.
@@ -58,6 +52,21 @@ module ExpressTemplates
           return @my_form
         end
 
+        def default_html_options
+          (config || {}).reject {|k,v| k.eql?(:id)}
+        end
+
+        def html_options
+          default_html_options.merge(config[:html_options] || {})
+        end
+
+        protected
+
+          def _process_args!(args)
+            @args = args
+            super(args)
+          end
+
       end
     end
   end

data/lib/express_templates/components/forms/option_support.rb

@@ -28,9 +28,9 @@ module ExpressTemplates
           reflection = belongs_to_association || has_many_through_association
           if reflection && !reflection.polymorphic?
             if cols.detect {|column| column.name.eql?('name') }
-              "#{reflection.klass}.all.select(:#{option_value_method}, :#{option_name_method}).order(:#{option_name_method})"
+              reflection.klass.select(option_value_method.to_sym, option_name_method.to_sym).order(option_name_method.to_sym)
             else
-              "#{reflection.klass}.all.sort_by(&:#{option_name_method})"
+              reflection.klass.all.sort_by(&option_name_method.to_sym)
             end
           end
         end