express_templates 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 00a0446a67ac0022ae2769db3a19f9c0399fa4c1
-  data.tar.gz: 5feea8d4b6a5732aec2f49edfc0ebd4024129f85
+  metadata.gz: 1a2204c2d16013be1c940bba47afad46787deb71
+  data.tar.gz: 9ccace8f710e68095767b14c9c48a1217e632e26
 SHA512:
-  metadata.gz: bd40eaa5f1d713c36084fd91ae72c844cf129b83683aa4a15dd730cc4e5e05a50e2e360ca31eef7fc81b25596075caf9fb54d79af98ab67bbc5ef7f896de36f4
-  data.tar.gz: 873c79cbf53186da5931979d05f62183432ec14426f0f37a2984d9fac64f38ea1210a4156ce40e8fbcf454113bbb21a76141d75f64208a5716f0612083b6fc25
+  metadata.gz: 75ab5ac3591e5d3f19de1ae9a83e5bca3b95d0dd946c124e5d73b769cc52b9923dcba935c5e9cfc20e05d696a8ee1304c5324e90133cc990a773da4d12605df2
+  data.tar.gz: 8d33acbcc55699a37dd0a36ad289f9ebd826bfe3c0124f0db488816844cede9910a36316a420ac94f7d6af229c398a8c0f55befef714bb8d378db7370e13ce9e

data/README.md

@@ -1,57 +1,138 @@
 # ExpressTemplates
 
-Provides a macro-ish DSL for use in constructing html templates in plain Ruby as an alternative to Erb or HAML.
+Provides a DSL for HTML templates using a declarative style of Ruby as an alternative to Erb or HAML.
 
 ## Usage
 
 Add this to your gemfile:
 
-    gem 'express_templates'
+```ruby
+gem 'express_templates'
+```
 
 Rename your application.html.erb to application.html.et.
 
 Change your template to look like this.
 
-    html(lang: "en") {
-      head {
-        meta charset: 'utf-8'
-        meta name: 'viewport', content: "width=device-width, initial-scale=1.0"
-        title {
-          content_for(:title)
-        }
-        stylesheet_link_tag "application", media: 'all', 'data-turbolinks-track' => true
-        csrf_meta_tags
-      }
-      body {
-        yield
-        javascript_include_tag "application"
-      }
+```ruby
+html(lang: "en") {
+  head {
+    meta charset: 'utf-8'
+    meta name: 'viewport', content: "width=device-width, initial-scale=1.0"
+    title {
+      content_for(:title)
     }
+    stylesheet_link_tag "application", media: 'all', 'data-turbolinks-track' => true
+    csrf_meta_tags
+  }
+  body {
+    yield
+    javascript_include_tag "application"
+  }
+}
+```
 
 Everything should work as you would expect.
 
 Set your editor syntax for .et files to Ruby.
 
-### How It Works
+You will now have also be able to utilize components which are found with documentation and examples in <tt>ExpressTemplates::Components<tt>.
 
-ExpressTemplates works via a good-enough stand in for a true macro system in Ruby which would make this type of thing considerably easier.
+## History
 
-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.
+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.
+
+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.
+
+## Expansion
+
+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.
+
+[Diagram depciting Haml/Erb](https://raw.githubusercontent.com/aelogica/express_templates/master/diagrams/diagram_express_templates.png "Diagram depciting Haml/Erb")
+
+## 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.
+
+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.
+
+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.
+
+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
+
+ExpressTemplates use Ruby's block structure and execution order to indicate parent-child relationships and to build the tree structure that ultimately results in nodes in the DOM.
+
+Example:
+
+```ruby
+ul {
+  li { "one" }
+  li "two"
+  li %Q(#{@three})
+}
+```
+
+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>
 
 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."
+## Components
 
-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.
+Given the constraint that logic must not go in the template, where does one put it?  The answer is we make a component!
 
-## Background
+ExpressTemplates provide a framework for construction of components by encapsulating common logic patterns found in view code into Capabilities which Components may include.  These Capabilities form a DSL which allows Components to be built in a declarative fashion.  This makes them "low-cost" entities to construct in terms of developer time.
+
+A common need is for a list items such as in the above example to be generated from a collection or array of data.   Let us suppose we expect the view context to have:
+
+```ruby
+@list = %w(one two three)
+```
 
-The bondage of HAML is unnecessary.  The clutter of Erb is unsightly.
+We can make a simple component like so:
 
-I generally prefer "one syntax per file" for reasons of cognative load and maintainability.
+```ruby
+class ListComponent < ExpressTemplates::Components::Base
+  emits inner: -> {
+                    li {
+                      item
+                    }
+                  },
+        outer: -> {
+                    ul {
+                      _yield
+                    }
+                  }
 
-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.
+  for_each -> { @list }, emit: :inner
+
+  wrap_with :outer
+end
+```
+
+This would be used in a view template just as if it were a tag, like so:
+
+```ruby
+div.active {
+  list_component
+}
+```
+
+Now when the template renders, it will yield:
+
+    <div class="active"><ul><li>one</li><li>two</li><li>three</li></ul></div>
+
+## Background
 
-ExpressTemplates form part of the AppExpress platform at [appexpress.io](http://appexpress.io).
+ExpressTemplates is a key part of the AppExpress platform at [appexpress.io](http://appexpress.io).
 
 This project rocks and uses MIT-LICENSE.

data/lib/express_templates/version.rb

@@ -1,3 +1,3 @@
 module ExpressTemplates
-  VERSION = "0.2.2"
+  VERSION = "0.2.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: express_templates
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Steven Talcott Smith