express_templates 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f322ad6cb1fb8bf620577f100a9a70274c6172d1
-  data.tar.gz: ea903155b79430c8e5ec5f557ea80ee7461d9fdd
+  metadata.gz: 00a0446a67ac0022ae2769db3a19f9c0399fa4c1
+  data.tar.gz: 5feea8d4b6a5732aec2f49edfc0ebd4024129f85
 SHA512:
-  metadata.gz: 9b71ed00ff0f5a2424a94b84da6c4104b988942b9fa37d7e36ec7c892118ccc33be46893c862be0e5ffec0b2ded2c5ed844d713e7650b3f5d0c82f0f78d0e726
-  data.tar.gz: d026690d15f79913cd90f112f437990449af06c795e718cf512a2d1a34d037ffa43e8e8161b20f9a7db4ebe9cf4aee9ea34421f628449d5f51b2584f98460446
+  metadata.gz: bd40eaa5f1d713c36084fd91ae72c844cf129b83683aa4a15dd730cc4e5e05a50e2e360ca31eef7fc81b25596075caf9fb54d79af98ab67bbc5ef7f896de36f4
+  data.tar.gz: 873c79cbf53186da5931979d05f62183432ec14426f0f37a2984d9fac64f38ea1210a4156ce40e8fbcf454113bbb21a76141d75f64208a5716f0612083b6fc25

data/README.md

@@ -36,18 +36,22 @@ Set your editor syntax for .et files to Ruby.
 
 ExpressTemplates works via a good-enough stand in for a true macro system in Ruby which would make this type of thing considerably easier.
 
-Basically, we use these "macros" and Ruby's block structure to build up a tree of components corresponding to the HTML structure of a document fragment.  Each HTML5 tag is a component available in the form of a macro.  Unrecognized identifiers are wrapped for later evaluation, presumably in a ViewContext.
+Basically, we use these "macros" and Ruby's block structure to build up a tree of components corresponding to the HTML structure of a document fragment.  Each HTML5 tag is a Component available in the form of a macro.  Unrecognized identifiers are wrapped for later evaluation, presumably in a ViewContext.
 
-yield and local variables which we may expect to be available in a view context are also wrapped for evaluation later.
+yield and local variables which we may expect to be available in a ViewContext are also wrapped for evaluation later.
+
+Templates are first "expanded", then "compiled" and then finally "rendered."
+
+Expanding results in a tree of Component like objects which have children and respond to #compile().  The result of #compile on a component is a Ruby code fragment which may be evaluated in a ViewContext to produce markup.  Compiling is similar to what HAML or Erb does.
 
 ## Background
 
-Sufficent motivation for this gem can be explained thusly:  The bondage of HAML is unnecessary.  The clutter of Erb is unsightly.
+The bondage of HAML is unnecessary.  The clutter of Erb is unsightly.
 
-I generall prefer "one syntax per file" for reasons of cognative load and maintainability.
+I generally prefer "one syntax per file" for reasons of cognative load and maintainability.
 
-Ultimately my objective with ExpressTemplates is to get away from writing HTML directly and to use this as a substrate for building pages out of higher-level, reusable components which include not only DOM elements but also behaviors.
+The introduction of an macro-like pre-processing step yielding a tree of Components as described above allows us to implement higher-level components which inherit behavior via normal OO Ruby.  This points the way to a UX framework and component library that will play nice with Rails caching and conventions.
 
-ExpressTemplates are part of the AppExpress platform at [appexpress.io](http://appexpress.io).
+ExpressTemplates form part of the AppExpress platform at [appexpress.io](http://appexpress.io).
 
 This project rocks and uses MIT-LICENSE.

data/lib/core_extensions/proc.rb

@@ -0,0 +1,42 @@
+require 'ripper'
+require 'pp'
+class Proc
+
+  TOKEN_PAIRS = {[:on_lbrace, '{']  => [:on_rbrace, '}'],
+                 [:on_kw, 'do']     => [:on_kw, 'end'],
+                 [:on_tlambeg, '{'] => [:on_rbrace, '}']}
+
+  # Make a best effort to provide the original source for a block
+  # based on extracting a string from the file identified in
+  # Proc#source_location using Ruby's tokenizer.
+  #
+  # This works for first block declared on a line in a source
+  # file.  If additional blocks are specified inside the first block
+  # on the same line as the start of the block, only the outer-most
+  # block declaration will be identified as a the block we want.
+  #
+  # If you require only the source of blocks-within-other-blocks, start them
+  # on a new line as would be best practice for clarity and readability.
+  def source
+    file, line_no = source_location
+    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) }
+    starting_token = tokens_on_line.detect do |pos, lbl, str| 
+      TOKEN_PAIRS.keys.include? [lbl, str] 
+    end
+    starting_token_type = [starting_token[1], starting_token[2]]
+    ending_token_type = TOKEN_PAIRS[starting_token_type]
+    source_str = ""
+    remaining_tokens = tokens.slice(tokens.index(starting_token)..-1)
+    nesting = -1
+    while token = remaining_tokens.shift
+      source_str << token[2]
+      nesting += 1 if [token[1], token[2]] == starting_token_type
+      is_ending_token = [token[1], token[2]].eql?(ending_token_type)
+      break if is_ending_token && nesting.eql?(0)
+      nesting -= 1 if is_ending_token
+    end
+    source_str
+  end
+end

data/lib/express_templates.rb

@@ -1,10 +1,15 @@
 module ExpressTemplates
+  require 'core_extensions/proc'
+  require 'express_templates/indenter'
+  require 'express_templates/macro'
+  require 'express_templates/markup'
+  require 'express_templates/components'
   require 'express_templates/template/handler'
-  require 'express_templates/html5_emitter'
   require 'express_templates/renderer'
   require 'express_templates/expander'
-  require 'express_templates/components'
+  require 'express_templates/compiler'
   extend Renderer
+  extend Compiler
   if defined?(Rails)
     ::ActionView::Template.register_template_handler :et, ExpressTemplates::Template::Handler
   end

data/lib/express_templates/compiler.rb

@@ -0,0 +1,27 @@
+module ExpressTemplates
+  module Compiler
+    def compile(template_or_src=nil, &block)
+      template, src = _normalize(template_or_src)
+
+      expander = Expander.new(template)
+
+      compiled = expander.expand(src, &block).map(&:compile)
+
+      return compiled.join("+").gsub('"+"', '').tap do |s|
+        puts("\n"+template.inspect+"\n"+s) if ENV['DEBUG'].eql?('true')
+      end
+    end
+
+    private
+      def _normalize(template_or_src)
+        template, src = nil, nil
+        if template_or_src.respond_to?(:source)
+          template = template_or_src
+          src = template_or_src.source
+        else
+          src = template_or_src
+        end
+        return template, src
+      end
+  end
+end

data/lib/express_templates/components.rb

@@ -2,7 +2,10 @@ module ExpressTemplates
   module Components
   end
 end
-require 'express_templates/component'
-require 'express_templates/components/html_tag'
-require 'express_templates/components/wrapper'
-require 'express_templates/components/yielder'
+
+require 'express_templates/expander'
+require 'express_templates/components/base'
+require 'express_templates/components/container'
+require 'express_templates/components/row'
+require 'express_templates/components/column'
+require 'express_templates/components/form_rails_support'

data/lib/express_templates/components/base.rb

@@ -0,0 +1,54 @@
+capabilities = Dir.glob(File.join(File.dirname(__FILE__), 'capabilities', '*.rb'))
+capabilities.each {|capability| require capability}
+
+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
+      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
+      end
+
+    end
+
+  end
+end

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

@@ -0,0 +1,52 @@
+module ExpressTemplates
+  module Components
+    module Capabilities
+      # Adds the capability for a component to only render
+      # its markup when a condition to be evaluated in the
+      # view is true.
+      #
+      # Example:
+      #
+      #     class PageHeader < ExpressTemplates::Components::Base
+      #       include ExpressTemplates::Components::Capabilities::Conditionality
+      #
+      #         emits {
+      #           h1 { content_for(:page_header) }
+      #         }
+      #
+      #         only_if -> { content_for?(:page_header) }
+      #
+      #       end
+      #     end
+      #
+      # The condition supplied to only if in the form of a proc
+      # is evaluated in the view context.
+      #
+      # The component will render an empty string if the proc returns false.
+      module Conditionality
+        def self.included(base)
+          base.class_eval do
+            extend ClassMethods
+          end
+        end
+
+        module ClassMethods
+
+          def condition_proc
+            @condition_proc
+          end
+
+          def only_if condition_proc
+            @condition_proc = condition_proc
+
+            using_logic do |component, options|
+              condition = instance_exec(&component.condition_proc)
+              eval(component[:markup]) if condition
+            end
+          end
+
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+module ExpressTemplates
+  module Components
+    module Capabilities
+
+      # Configurable components accept options which they can use to alter
+      # their markup each time they are invoked within a template.
+      #
+      # They do not compile their markup fragments at load time as simpler
+      # components do for efficiency.  Rather they compile their fragments
+      # when they are themselves undergoing compilation.  This facilitates
+      # access to arguments which were passed to the component at initialization.
+      #
+      # For example, if we have a Row component that is Configurable:
+      #
+      #     row(:main)
+      #
+      # might process to:
+      #
+      #     <div id="main" class="row" />
+      #
+
+      module Configurable
+        def self.included(base)
+          base.class_eval do
+            extend ClassMethods
+            include InstanceMethods
+
+            # Stores arguments for later processing, eg., compile time
+            def initialize(*args)
+              @args = args.dup
+              @config = {}
+              _process_args!(args)
+              super(*args)
+            end
+          end
+        end
+
+        module ClassMethods
+
+          protected
+
+            # Override Templating._compile_fragment to delay compilation
+            def _compile_fragment(block, options = {})
+              if options.delete(:force_compile)
+                super(block, options)
+              else
+                block
+              end
+            end
+
+            def _lookup(name, options = {})
+              super(name, options.merge(force_compile: true))
+            end
+
+        end
+
+        module InstanceMethods
+
+          def config
+            @config
+          end
+
+          alias :my :config
+
+          def expand_locals
+            {my: config}
+          end
+
+          # Override Templating#lookup to pass locals
+          def lookup(fragment_name)
+            self.class.send(:_lookup, fragment_name, expand_locals)
+          end
+
+
+          private
+
+            def _process_args!(args)
+              if args.first.kind_of?(Symbol)
+                config.merge!(id: args.shift)
+              end
+              while arg = args.shift
+                if arg.kind_of?(Hash)
+                  config.merge!(arg)
+                end
+              end
+            end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+module ExpressTemplates
+  module Components
+    module Capabilities
+      #
+      # Adds the capability to iterate over a collection repeating a markup
+      # fragment for each member.
+      #
+      # Example:
+      #
+      #   class ParagraphsComponent < ExpressTemplates::Components::Base
+      #
+      #     emits -> { p { item } }     # item is the default local variable name
+      #
+      #     for_each -> { paragraphs }  # evaluated in view context
+      #
+      #   end
+      #
+      # Must specify an <tt>iterator</tt> either as a proc to be evaluated in the
+      # view context or else as a variable name in the form of a symbol which is
+      # assumed to be available in the view context.
+      #
+      # Provides:
+      #
+      # * Iterating::ClassMethods (for_each)
+      #
+      module Iterating
+        def self.included(base)
+          base.class_eval do
+            extend ClassMethods
+          end
+        end
+
+        module ClassMethods
+          # Sets the component up to use iterating logic to reproduce a fragment
+          # for a collection.
+          #
+          # Parameters include an iterator that may be :@variable assumed to be
+          # available in context or a proc that when evaluated in the context
+          # should return a collection.
+          #
+          # An <tt>:emit</tt> option may specify a fragment to emit.
+          # Defaults to <tt>:markup</tt>
+          #
+          # An <tt>:as</tt> option specifies the local variable name for each
+          # item in the collection for use in the fragment.  Defaults to: <tt>item</tt>
+          #
+          # An <tt>:empty</tt> option specifies a fragment to use for the
+          # empty state when the iterator returns an empty collection.
+          def for_each(iterator, as: :item, emit: :markup, empty: nil)
+            if iterator.kind_of?(Symbol)
+              var_name = iterator.to_s.gsub(/^@/,'').singularize.to_sym
+            else
+              var_name = as
+            end
+            using_logic do |component, options|
+              collection = if iterator.kind_of?(Proc)
+                if iterator.arity.eql?(1)
+                  instance_exec(options, &iterator)
+                else
+                  instance_exec &iterator
+                end
+              else
+                eval(iterator.to_s)
+              end
+              if collection.empty?
+                empty ? component[empty] : ''
+              else
+                collection.map do |item|
+                  b = binding
+                  b.local_variable_set(var_name, item)
+                  b.eval(component[emit], __FILE__)
+                end.join
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+module ExpressTemplates
+  module Components
+    module Capabilities
+      module Parenting
+
+        # Parenting adds the capability for a component to have and render
+        # children that may be specified in the template fragment which
+        # includes the component.
+        #
+        # Example parenting component:
+        #
+        #   class Line < ExpressTemplates::Components::Base
+        #     include Capabilities::Parenting
+        #
+        #     emits { p.line { _yield } }
+        #   end
+        #
+        # You might then use this component like so:
+        #
+        #   line "In", "Xanadu", "did", "Kubla", "Khan"
+        #   line { "A stately pleasure-dome decree :" }
+        #   line { "Where Alph, the sacred river, ran" }
+        #   line %q(Through caverns measureless to man)
+        #   line %q|Down to a sunless sea.|
+        #
+        # Provides
+        #
+        # * ClassMethods for rendering
+        # * InstanceMethods for managing children
+        #
+        def self.included(base)
+          base.class_eval do
+            extend ClassMethods
+            include InstanceMethods
+          end
+        end
+
+        module ClassMethods
+          def render_with_children(context, locals = {}, child_markup_src = nil)
+            _wrap_it(context, locals) do |component|
+              child_markup_src
+            end
+          end
+
+        end
+
+        module InstanceMethods
+          def children
+            @children ||= []
+          end
+
+          def children=(children)
+            @children =children
+          end
+
+          def compile
+            locals = (expand_locals rescue nil).inspect
+            compiled_children = nil
+            args = %w(self)
+            args << locals
+            Indenter.for(:compile) do |indent, indent_with_newline|
+              compiled_children = children.map { |child| indent_with_newline + child.compile }.join("+")
+              compiled_children.gsub!('"+"', '') # avoid unnecessary string concatenation
+              args << compiled_children unless compiled_children.empty?
+            end
+            closing_paren = compiled_children.empty? ? ')' : "\n#{Indenter.for(:compile)})"
+            "#{self.class.to_s}.render_with_children(#{args.join(', ')}#{closing_paren}"
+          end
+
+        end
+      end
+    end
+  end
+end