express_templates 0.2.0 → 0.2.2

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

@@ -0,0 +1,93 @@
+module ExpressTemplates
+  module Components
+    module Capabilities
+
+      # Adds the capability for a component to render itself in a context.
+      #
+      # Provides both:
+      #
+      # * Rendering::ClassMethods
+      # * Rendering::InstanceMethods
+      #
+      # Used in ExpressTemplates::Components::Base.
+      #
+      module Rendering
+        def self.included(base)
+          base.class_eval do
+            extend ClassMethods
+            include InstanceMethods
+          end
+        end
+
+        module ClassMethods
+
+          # Store a block of logic which will be evalutated in a context
+          # during rendering.
+          #
+          # The block will be passed a reference to the component's class.
+          #
+          def using_logic(&block)
+            @control_flow = block
+          end
+
+          # Returns a string containing markup generated by evaluating
+          # blocks of supplied logic or compiled template code in a <tt>context</tt>.
+          #
+          # The context may be any object however, it is generally an
+          # ActionView::Context.
+          #
+          # Components when compiled may yield something like:
+          #
+          #     "MyComponent.render(self, {id: 'foo'})"
+          #
+          # The supplied options hash may be used to modify any fragments
+          # or the behavior of any logic.
+          #
+          # If a fragment identifier is passed as a symbol in the first
+          # option position, this will render that fragment only.
+          #
+          def render(context, *opts, &context_logic_block)
+            fragment = opts.shift if opts.first.is_a?(Symbol)
+            begin
+              if fragment
+                context.instance_eval(_lookup(fragment, opts)) || ''
+              else
+                flow = context_logic_block || @control_flow
+                exec_args = [self, opts].take(flow.arity)
+                context.instance_exec(*exec_args, &flow) || ''
+              end
+            rescue => e
+              binding.pry if ENV['DEBUG'].eql?("true")
+              raise "Rendering error in #{self}: #{e.to_s}"
+            end
+          end
+
+          private
+
+            def _control_flow
+              @control_flow
+            end
+
+        end
+
+        module InstanceMethods
+
+          def compile
+            if _provides_logic?
+              "#{self.class.to_s}.render(self)"
+            else
+              lookup :markup
+            end
+          end
+
+          private
+
+            def _provides_logic?
+              !!self.class.send(:_control_flow)
+            end
+
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,196 @@
+module ExpressTemplates
+  module Components
+    module Capabilities
+
+      # The Templating capability module provides Components with the ability
+      # to store, reference and compile template fragments.
+      #
+      # It extends the including class with Templating::ClassMethods.
+      #
+      # It also provides helpers which are snippets of code in the form of
+      # lambdas that may be evaluated in the view context.
+      #
+      module Templating
+        def self.included(base)
+          base.class_eval do
+            extend ClassMethods
+            include InstanceMethods
+          end
+          class << base
+            alias_method :fragments, :emits
+            alias_method :has_markup, :emits
+          end
+        end
+
+        module ClassMethods
+
+          # Store fragments of ExpressTemplate style markup for use in
+          # generating the HTML representation of a component.
+          #
+          # For example in your class, simply place the following:
+          #
+          #     class MyComponent < ET::Components::Base
+          #       emits {
+          #         ul {
+          #           li "one"
+          #           li "two"
+          #           li "three"
+          #         }
+          #       }
+          #
+          #     end
+          #
+          # By default this template code is stored under the label :markup
+          # 
+          # You may specify several fragments with a hash containing lambdas:
+          #
+          #       emits body:     -> { li "item" },
+          #             wrapper:  -> { ul { _yield } }
+          #
+          # This method is aliased as <tt>fragments</tt> and <tt>has_markup</tt>
+          # 
+          def emits(*args, &template_code)
+            if args.first.respond_to?(:call) or template_code
+              _store :markup, _compile_fragment(args.first||template_code) # default fragment is named :markup
+            else
+              args.first.to_a.each do |name, block|
+                raise ArgumentError unless name.is_a?(Symbol) and block.is_a?(Proc)
+                _store(name, _compile_fragment(block))
+              end
+            end
+          end
+
+          def [](label)
+            _lookup(label)
+          end
+
+          # Stores a block given for later evaluation in context.
+          #
+          # Example:
+          #
+          #       class TitleComponent < ECB
+          #         helper :title_helper do
+          #           @resource.name
+          #         end
+          #
+          #         emits {
+          #           h1 {
+          #             title_helper
+          #           }
+          #         }
+          #
+          #       end
+          #
+          # In this example <tt>@resource.name</tt> is evaluated in the
+          # provided context during page rendering and not during template
+          # expansion or compilation.
+          #
+          # This is the recommended for encapsulation of "helper" type
+          # functionality which is of concern only to the component and
+          # used only in its own markup fragments.
+          def helper(name, &block)
+            _helpers[name] = block
+            _define_helper_methods name
+          end
+
+          def special_handlers
+            {insert: self, _yield: self}.merge(Hash[*(_helpers.keys.map {|k| [k, self] }.flatten)])
+          end
+
+          protected
+
+            # Stores a fragment for use during compilation and rendering
+            # of a component.
+            def _store(name, fragment)
+              @fragments ||= Hash.new
+              @fragments[name] = fragment
+            end
+
+            # Looks up a template fragment for this component and returns
+            # compiled template code.
+            #
+            # If the template fragment is not already compiled, it compiles it
+            # with the supplied options as locals.  Locals may be used within
+            # the template during expansion.
+            #
+            # Returns a string containing ruby code which evaluates to markup.
+            def _lookup(name, options = {})
+              @fragments ||= Hash.new
+              fragment = @fragments[name] or raise "no template fragment supplied for: #{name}"
+              if fragment.kind_of?(Proc)
+                _compile_fragment(fragment, options)
+              else
+                fragment
+              end
+            end
+
+            # Expands and compiles the supplied block representing a
+            # template fragment.
+            #
+            # Any supplied options are passed as locals for use during expansion.
+            #
+            # Returns a string containing ruby code which evaluates to markup.
+            def _compile_fragment(block, options = {})
+              expander = ExpressTemplates::Expander.new(nil, special_handlers, options)
+              expander.expand(&block).map(&:compile).join("+")
+            end
+
+
+          private
+
+
+            def _helpers
+              @helpers ||= Hash.new
+            end
+
+            def _define_helper_methods(name)
+              method_definition= <<-RUBY
+                class << self
+
+                  # called during expansion
+                  define_method(:#{name}) do |*args|
+                    helper_args = %w(self)
+                    helper_args += args.map(&:inspect)
+                    '\#\{#{self.to_s}._#{name}('+_interpolate(helper_args).join(', ')+')\}'
+                  end
+
+                  # called during rendering in view context
+                  define_method(:_#{name}) do |context, *args|
+                    begin
+                      helper_proc = _helpers[:#{name}]
+                      helper_args = args.take(helper_proc.arity)
+                      context.instance_exec *helper_args, &helper_proc
+                    rescue => e
+                      raise "#{name} raised: \#\{e.to_s\}"
+                    end.to_s
+                  end
+                end
+              RUBY
+              eval(method_definition)
+            end
+
+            def _interpolate(args)
+              args.map do |arg|
+                if arg.kind_of?(String) && match = arg.match(/"\{\{(.*)\}\}"/)
+                  match[1]
+                else
+                  arg
+                end
+              end
+            end
+
+        end
+
+        module InstanceMethods
+
+          def lookup(fragment_name)
+            self.class[fragment_name]
+          end
+
+        end
+
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+module ExpressTemplates
+  module Components
+    module Capabilities
+
+      # Add the ability for a component template to wrap or decorate a fragment
+      # with another fragment.
+      #
+      # The insertion point for the inner fragment is marked with <tt>_yield</tt>
+      #
+      # Example:
+      #
+      #   class MenuComponent < ExpressTemplates::Components::Base
+      #
+      #     fragments :menu_item, -> { li { menu_link(item) } },
+      #               :menu_wrapper, -> { ul { _yield } }
+      #
+      #     for_each -> { menu_items }
+      #
+      #     wrap_with :wrapper
+      #
+      #   end
+      #
+      # Note this example also uses Capabilities::Iterating.
+      #
+      # Provides:
+      #
+      # * Wrapping::ClassMethods
+      #
+      module Wrapping
+        def self.included(base)
+          base.class_eval do
+            extend ClassMethods
+          end
+        end
+
+        module ClassMethods
+
+          # Enclose whatever the component would already generate
+          # inside the specified fragment wherever we encounter _yield
+          #
+          # Note: this must come after any statements that affect the logic
+          # flow.
+          def wrap_with(fragment, dont_wrap_if: -> {false} )
+            wrapper_name(fragment)
+            prior_logic = @control_flow
+            using_logic do |component|
+              if instance_exec(&dont_wrap_if)
+                eval(component.render((self||Object.new), &prior_logic))
+              else
+                component._wrap_it(self, &prior_logic)
+              end
+            end
+          end
+
+          def wrapper_name(name = nil)
+            if name.nil?
+              @wrapper_name || :markup
+            else
+              @wrapper_name = name
+            end
+          end
+
+          # added back in for compatability with prior interface
+          # should probably be refactored away
+          def _wrap_using(fragment, context=nil, options={}, &to_be_wrapped)
+            old_wrapper_name = @wrapper_name
+            @wrapper_name = fragment
+            result = _wrap_it(context, options, &to_be_wrapped)
+            @wrapper_name = old_wrapper_name
+            return result
+          end
+
+          def _wrap_it(context=nil, options={}, &to_be_wrapped)
+            body = ''
+            if to_be_wrapped
+              body = render((context||Object.new), &to_be_wrapped)
+            end
+            if compiled_src = _lookup(wrapper_name, options)
+              if context.nil?
+                eval(compiled_src).gsub(/\{\{_yield\}\}/, body)
+              else
+                ctx = context.instance_eval("binding")
+                ctx.local_variable_set(:_yield, body)
+                ctx.eval(compiled_src)
+              end
+            else
+              raise "No wrapper fragment provided for '#{wrapper_name}'"
+            end
+          end
+
+          def _yield(*args)
+            "{{_yield}}"
+          end
+
+        end
+
+      end
+    end
+  end
+end

data/lib/express_templates/components/column.rb

@@ -0,0 +1,13 @@
+module ExpressTemplates
+  module Components
+    class Column < Container
+      include Capabilities::Configurable
+
+      emits {
+        div.column(my[:id]) {
+          _yield
+        }
+      }
+    end
+  end
+end

data/lib/express_templates/components/container.rb

@@ -0,0 +1,7 @@
+module ExpressTemplates
+  module Components
+    class Container < Base
+      include Capabilities::Parenting
+    end
+  end
+end

data/lib/express_templates/components/form_rails_support.rb

@@ -0,0 +1,19 @@
+module ExpressTemplates
+  module Components
+    # Provide hidden fields such as the authenticity token
+    # and the utf8 enforcer tag as well as a method tag as
+    # would be provided by Rails' form helpers.
+    #
+    # An optional method may be speficied.  Defaults to 'post'.
+    class FormRailsSupport < Base
+      include Capabilities::Configurable
+      emits {
+        div(style: 'display:none') {
+          utf8_enforcer_tag
+          method_tag(my[:id] || :post)
+          token_tag
+        }
+      }
+    end
+  end
+end

data/lib/express_templates/components/row.rb

@@ -0,0 +1,28 @@
+module ExpressTemplates
+  module Components
+    # A Row is a Container implemented as a div with
+    # a CSS class "row"
+    #
+    # An optional dom ID may be specified as a symbol.
+    #
+    # Example:
+    #
+    #     row(:main) {
+    #       p "Some content"
+    #     }
+    #
+    # This will render as:
+    #
+    #     <div id="main" class="row"><p>Some content</p></div>
+    #
+    class Row < Container
+      include Capabilities::Configurable
+
+      emits {
+        div.row(my[:id]) {
+          _yield
+        }
+      }
+    end
+  end
+end