RubyGems - papercraft - Versions diffs - 0.10.1 → 0.11 - Mend

papercraft 0.10.1 → 0.11

Files changed (6) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 757137ea8d3a2b5d5d329b7e841bad13cc26ea3486ebcb216f1ef016d7d3ff4a
-  data.tar.gz: 281ee3b2911b1f4e1ff3337dbefef407ce07b17e21acb949dce158a93d8758a5
+  metadata.gz: 3452d115d85742018d1497b369ea27970f0c144e3dcb1772f4d81e33315dce51
+  data.tar.gz: e7217a9d9bcfd7af0dc92482650bc03392b0406cf4f3d6141c253a2918638545
 SHA512:
-  metadata.gz: 22225498fce014a17962541bac3c17f20243239b709e191e75fa2f1abbc0f7f7fdef3b0c4d110753f0de1c2ca4efc19f516cb797a02cbafa70af95085449096e
-  data.tar.gz: 57bb7aae102900de14ba9d8f4a0e2be83978e5106ff098ffda5acf39431273fd76be646d012da72094715ad8a3da7fd81a485e51151c74df94091a91e72866f4
+  metadata.gz: 8f76b9e73aa48f91af932af3308d3dd43239c3d5ca39e305cb1535417b5997483aa884f0e34ed128800b07a3135ebc1d18ea81d0df64e6170726a66c86969288
+  data.tar.gz: dbe744ca25996c3d263ff609ca26f42076784fdbceabd2dd1604dd1016e2d840830230f4205a673b9e5ba14eb8e480627612971b71ca6631e0a6e473d59ccb73

data/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,7 @@
+## 0.11 2022-01-04
+- Add deferred evaluation
 ## 0.10.1 2021-12-25
 - Fix tag rendering with empty text in Ruby 3.0

data/README.md CHANGED Viewed

@@ -374,6 +374,58 @@ The deafult options can be configured by accessing
 Papercraft::HTML.kramdown_options[:auto_ids] = false
 ```
+## Deferred evaluation
+Deferred evaluation allows deferring the rendering of parts of a template until
+the last moment, thus allowing an inner component to manipulate the state of the
+outer component. To in order to defer a part of a template, use `#defer`, and
+include any markup in the provided block. This technique, in in conjunction with
+holding state in instance variables, is an alternative to passing parameters,
+which can be limiting in some situations.
+A few use cases for deferred evaulation come to mind:
+- Setting the page title.
+- Adding a flash message to a page.
+- Using components that dynamically add static dependencies (JS and CSS) to the
+  page.
+The last use case is particularly interesting. Imagine a `DependencyMananger`
+class that can collect JS and CSS dependencies from the different components
+integrated into the page, and adds them to the page's `<head>` element:
+```ruby
+default_layout = H { |**args|
+  @dependencies = DependencyMananger.new
+  head {
+    defer { emit @dependencies.head_markup }
+  }
+  body { emit_yield **args }
+}
+button = proc { |text, onclick|
+  @dependencies.js '/static/js/button.js'
+  @dependencies.css '/static/css/button.css'
+  button text, onclick: onclick
+}
+heading = proc { |text|
+  @dependencies.js '/static/js/heading.js'
+  @dependencies.css '/static/css/heading.css'
+  h1 text
+}
+page = default_layout.apply {
+  emit heading, "What's your favorite cheese?"
+  emit button, 'Beaufort', 'eat_beaufort()'
+  emit button, 'Mont d''or', 'eat_montdor()'
+  emit button, 'Époisses', 'eat_epoisses()'
+}
+```
 ## Papercraft extensions
 Papercraft extensions are modules that contain one or more methods that can be

data/lib/papercraft/renderer.rb CHANGED Viewed

@@ -57,12 +57,14 @@ module Papercraft
       end
     end
+    INITIAL_BUFFER_CAPACITY = 8192
     # Initializes the renderer and evaulates the given template in the
     # renderer's scope.
     #
     # @param &template [Proc] template block
     def initialize(&template)
-      @buffer = +''
+      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
       instance_eval(&template)
     end
@@ -70,6 +72,20 @@ module Papercraft
     #
     # @return [String]
     def to_s
+      if @parts
+        last = @buffer
+        @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
+        parts = @parts
+        @parts = nil
+        parts.each do |p|
+          if Proc === p
+            render_deferred_proc(&p)
+          else
+            @buffer << p
+          end
+        end
+        @buffer << last unless last.empty?
+      end
       @buffer
     end
@@ -160,6 +176,42 @@ module Papercraft
       instance_exec(*a, **b, &@inner_block)
     end
+    # Defers the given block to be evaluated later. Deferred evaluation allows
+    # Papercraft components to inject state into sibling components, regardless
+    # of the component's order in the container component. For example, a nested
+    # component may set an instance variable used by another component. This is
+    # an elegant solution to the problem of setting the HTML page's title, or
+    # adding elements to the `<head>` section. Here's how a title can be
+    # controlled from a nested component:
+    #
+    #   layout = H {
+    #     html {
+    #       head {
+    #         defer { title @title }
+    #       }
+    #       body {
+    #         emit_yield
+    #       }
+    #     }
+    #   }
+    #
+    #   html.render {
+    #     @title = 'My super page'
+    #     h1 'content'
+    #   }
+    #
+    # @param &block [Proc] Deferred block to be emitted
+    # @return [void]
+    def defer(&block)
+      if !@parts
+        @parts = [@buffer, block]
+      else
+        @parts << @buffer unless @buffer.empty?
+        @parts << block
+      end
+      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
+    end
     S_LT              = '<'
     S_GT              = '>'
@@ -217,6 +269,23 @@ module Papercraft
         end
       }
     end
+    # Renders a deferred proc by evaluating it, then adding the rendered result
+    # to the buffer.
+    #
+    # @param &block [Proc] deferred proc
+    # @return [void]
+    def render_deferred_proc(&block)
+      old_buffer = @buffer
+      @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
+      @parts = nil
+      instance_eval(&block)
+      old_buffer << to_s
+      @buffer = old_buffer
+    end
   end
   # Implements an HTML renderer

data/lib/papercraft/version.rb CHANGED Viewed

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 module Papercraft
-  VERSION = '0.10.1'
+  VERSION = '0.11'
 end

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: '0.11'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-25 00:00:00.000000000 Z
+date: 2022-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: escape_utils
@@ -166,7 +166,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.32
+rubygems_version: 3.3.3
 signing_key:
 specification_version: 4
 summary: 'Papercraft: component-based HTML templating for Ruby'