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

papercraft 0.10.1 → 0.14

Files changed (9) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +18 -0
data/README.md +55 -5
data/lib/papercraft/component.rb +6 -14
data/lib/papercraft/html.rb +57 -4
data/lib/papercraft/renderer.rb +156 -16
data/lib/papercraft/version.rb +1 -1
data/lib/papercraft.rb +6 -0
metadata +3 -3

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 757137ea8d3a2b5d5d329b7e841bad13cc26ea3486ebcb216f1ef016d7d3ff4a
-  data.tar.gz: 281ee3b2911b1f4e1ff3337dbefef407ce07b17e21acb949dce158a93d8758a5
+  metadata.gz: 8ecbcde7e33f35958acc4ca0c5c0623468563f14322675a3c7315ed92e0b289c
+  data.tar.gz: 5f6bdcdee15ef9ca04bc982405bd07ea3da49c4a43fbd8fd95a70494e0c43dab
 SHA512:
-  metadata.gz: 22225498fce014a17962541bac3c17f20243239b709e191e75fa2f1abbc0f7f7fdef3b0c4d110753f0de1c2ca4efc19f516cb797a02cbafa70af95085449096e
-  data.tar.gz: 57bb7aae102900de14ba9d8f4a0e2be83978e5106ff098ffda5acf39431273fd76be646d012da72094715ad8a3da7fd81a485e51151c74df94091a91e72866f4
+  metadata.gz: 7496b82113125d5f20287cb8b2f6607acfe7c16dda2a4670152867a175c877c33865f85ad155e733509b55e36067d0c3ea60578bf55f041e95bb46e3c1fa84f9
+  data.tar.gz: 91d5a7059eaf4b760412d9440f8ae08b48486c6ca6fc423a1ce32eb61a9a376385b4830b88b8a2ca1721971c48e4525a99d732d7650522fa71a55654c63aae86

data/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,21 @@
+## 0.14 2022-01-19
+- Add support for #emit_yield in applied component (#4)
+## 0.13 2022-01-19
+- Add support for partial parameter application (#3)
+## 0.12 2022-01-06
+- Improve documentation
+- Add `Renderer#tag` method
+- Add `HTML#style`, `HTML#script` methods
+## 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

@@ -20,8 +20,6 @@
   <a href="https://www.rubydoc.info/gems/papercraft">API reference</a>
 </p>
-# Papercraft - Composable HTML templating for Ruby
 ## What is Papercraft?
 ```ruby
@@ -368,17 +366,69 @@ The default Kramdown options are:
 ```
 The deafult options can be configured by accessing
-`Papercraft::HTML.kramdown_options`:
+`Papercraft::HTML.kramdown_options`, e.g.:
 ```ruby
 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
 used to render complex HTML components. Extension modules can be used by
-installing them as a namespaced extension using `Papercraft.extension`.
+installing them as a namespaced extension using `Papercraft::extension`.
 Extensions are particularly useful when you work with CSS frameworks such as
 [Bootstrap](https://getbootstrap.com/), [Tailwind](https://tailwindui.com/) or
 [Primer](https://primer.style/).
@@ -424,7 +474,7 @@ end
 Papercraft.extension(bootstrap: BootstrapComponents)
 ```
-The call to `Papercraft.extension` lets us access the different methods of
+The call to `Papercraft::extension` lets us access the different methods of
 `BootstrapComponents` by calling `#bootstrap` inside a template. With this,
 we'll be able to express the above markup as follows:

data/lib/papercraft/component.rb CHANGED Viewed

@@ -106,11 +106,8 @@ module Papercraft
       template = self
       Renderer.verify_proc_parameters(template, a, b)
       renderer_class.new do
-        if block
-          with_block(block) { instance_exec(*a, **b, &template) }
-        else
-          instance_exec(*a, **b, &template)
-        end
+        push_emit_yield_block(block) if block
+        instance_exec(*a, **b, &template)
       end.to_s
     rescue ArgumentError => e
       raise Papercraft::Error, e.message
@@ -136,15 +133,10 @@ module Papercraft
     # @return [Papercraft::Component] applied component
     def apply(*a, **b, &block)
       template = self
-      if block
-        Component.new(&proc do |*x, **y|
-          with_block(block) { instance_exec(*x, **y, &template) }
-        end)
-      else
-        Component.new(&proc do |*x, **y|
-          instance_exec(*a, **b, &template)
-        end)
-      end
+      Component.new(&proc do |*x, **y|
+        push_emit_yield_block(block) if block
+        instance_exec(*a, *x, **b, **y, &template)
+      end)
     end
     # Returns the Renderer class used for rendering the templates, according to

data/lib/papercraft/html.rb CHANGED Viewed

@@ -44,15 +44,53 @@ module Papercraft
       link(**attributes)
     end
-    def emit_markdown(markdown, **opts)
-      emit Kramdown::Document.new(markdown, **kramdown_options(opts)).to_html
+    # Emits an inline CSS style element.
+    #
+    # @param css [String] CSS code
+    # @param **props [Hash] optional element attributes
+    # @return [void]
+    def style(css, **props, &block)
+      @buffer << '<style'
+      emit_props(props) unless props.empty?
+      @buffer << '>' << css << '</style>'
     end
+    # Emits an inline JS script element.
+    #
+    # @param js [String, nil] Javascript code
+    # @param **props [Hash] optional element attributes
+    # @return [void]
+    def script(js = nil, **props, &block)
+      @buffer << '<script'
+      emit_props(props) unless props.empty?
-    def kramdown_options(opts)
-      HTML.kramdown_options.merge(**opts)
+      if js
+        @buffer << '>' << js << '</script>'
+      else
+        @buffer << '></script>'
+      end
+    end
+    # Converts and emits the given markdown. Papercraft uses
+    # [Kramdown](https://github.com/gettalong/kramdown/) to do the Markdown to
+    # HTML conversion. Optional Kramdown settings can be provided in order to
+    # control the conversion. Those are merged with the default Kramdown
+    # settings, which can be controlled using
+    # `Papercraft::HTML.kramdown_options`.
+    #
+    # @param markdown [String] Markdown content
+    # @param **opts [Hash] Kramdown options
+    # @return [void]
+    def emit_markdown(markdown, **opts)
+      emit Kramdown::Document.new(markdown, **kramdown_options(opts)).to_html
     end
     class << self
+      # Returns the default Kramdown options used for converting Markdown to
+      # HTML.
+      #
+      # @return [Hash] Default Kramdown options
       def kramdown_options
         @kramdown_options ||= {
           entity_output: :numeric,
@@ -62,9 +100,24 @@ module Papercraft
         }
       end
+      # Sets the default Kramdown options used for converting Markdown to
+      # HTML.
+      #
+      # @param opts [Hash] New deafult Kramdown options
+      # @return [Hash] New default Kramdown options
       def kramdown_options=(opts)
         @kramdown_options = opts
       end
     end
+    private
+    # Returns the default Kramdown options, merged with the given overrides.
+    #
+    # @param opts [Hash] Kramdown option overrides
+    # @return [Hash] Merged Kramdown options
+    def kramdown_options(opts)
+      HTML.kramdown_options.merge(**opts)
+    end
   end
 end

data/lib/papercraft/renderer.rb CHANGED Viewed

@@ -34,8 +34,29 @@ module Papercraft
         end
       end
-      # Installs the given extensions, mapping a method name to the extension
-      # module.
+      # call_seq:
+      #   Papercraft::Renderer.extension(name => mod, ...)
+      #   Papercraft.extension(name => mod, ...)
+      #
+      # Installs the given extensions, passed in the form of a Ruby hash mapping
+      # methods to extension modules. The methods will be available to all
+      # Papercraft components. Extension methods are executed in the context of
+      # the the renderer instance, so they can look just like normal proc
+      # components. In cases where method names in the module clash with HTML
+      # tag names, you can use the `#tag` method to emit the relevant tag.
+      #
+      # module ComponentLibrary
+      #   def card(title, content)
+      #     div(class: 'card') {
+      #       h3 title
+      #       div(class: 'card-content') { emit_markdown content }
+      #     }
+      #   end
+      # end
+      #
+      # Papercraft.extension(components: ComponentLibrary)
+      # H { components.card('Foo', '**Bar**') }
+      #
       # @param map [Hash] hash mapping methods to extension modules
       # @return [void]
       def extension(map)
@@ -57,12 +78,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,13 +93,29 @@ 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
+    # The tag method template below is optimized for performance. Do not touch!
     S_TAG_METHOD_LINE = __LINE__ + 1
     S_TAG_METHOD = <<~EOF
-      S_TAG_%<TAG>s_PRE = '<%<tag>s'.tr('_', '-')
-      S_TAG_%<TAG>s_CLOSE = '</%<tag>s>'.tr('_', '-')
+      S_TAG_%<TAG>s_PRE = %<tag_pre>s
+      S_TAG_%<TAG>s_CLOSE = %<tag_close>s
       def %<tag>s(text = nil, **props, &block)
         if text.is_a?(Hash) && props.empty?
@@ -103,6 +142,48 @@ module Papercraft
       end
     EOF
+    # Emits an HTML tag with the given content, properties and optional block.
+    # This method is an alternative to emitting HTML tags using dynamically
+    # created methods. This is particularly useful when using extensions that
+    # have method names that clash with HTML tags, such as `button` or `a`, or
+    # when you need to override the behaviour of a particular HTML tag.
+    #
+    # The following two method calls have the same effect:
+    #
+    # button 'text', id: 'button1'
+    # tag :button, 'text', id: 'button1'
+    #
+    # @param sym [Symbol, String] HTML tag
+    # @param text [String, nil] tag content
+    # @param **props [Hash] tag attributes
+    # @param &block [Proc] optional inner HTML
+    # @return [void]
+    def tag(sym, text = nil, **props, &block)
+      if text.is_a?(Hash) && props.empty?
+        props = text
+        text = nil
+      end
+      tag = sym.to_s.tr('_', '-')
+      @buffer << S_LT << tag
+      emit_props(props) unless props.empty?
+      if block
+        @buffer << S_GT
+        instance_eval(&block)
+        @buffer << S_LT_SLASH << tag << S_GT
+      elsif Proc === text
+        @buffer << S_GT
+        emit(text)
+        @buffer << S_LT_SLASH << tag << S_GT
+      elsif text
+        @buffer << S_GT << escape_text(text.to_s) << S_LT_SLASH << tag << S_GT
+      else
+        @buffer << S_SLASH_GT
+      end
+    end
     # Catches undefined tag method call and handles it by defining the method.
     #
     # @param sym [Symbol] HTML tag or component identifier
@@ -112,7 +193,12 @@ module Papercraft
     # @return [void]
     def method_missing(sym, *args, **opts, &block)
       tag = sym.to_s
-      code = S_TAG_METHOD % { tag: tag, TAG: tag.upcase }
+      code = S_TAG_METHOD % {
+        tag: tag,
+        TAG: tag.upcase,
+        tag_pre: "<#{tag.tr('_', '-')}".inspect,
+        tag_close: "</#{tag.tr('_', '-')}>".inspect
+      }
       self.class.class_eval(code, __FILE__, S_TAG_METHOD_LINE)
       send(sym, *args, **opts, &block)
     end
@@ -156,9 +242,46 @@ module Papercraft
     # @param **b [Hash] named arguments to pass to a proc
     # @return [void]
     def emit_yield(*a, **b)
-      raise Papercraft::Error, "No block given" unless @inner_block
+      block = @emit_yield_stack&.pop
+      raise Papercraft::Error, "No block given" unless block
-      instance_exec(*a, **b, &@inner_block)
+      instance_exec(*a, **b, &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              = '<'
@@ -182,19 +305,19 @@ module Papercraft
     private
     # Escapes text. This method must be overriden in descendant classes.
+    #
+    # @param text [String] text to be escaped
     def escape_text(text)
       raise NotImplementedError
     end
-    # Sets up a block to be called with `#emit_yield`
-    def with_block(block, &run_block)
-      old_block = @inner_block
-      @inner_block = block
-      instance_eval(&run_block)
-    ensure
-      @inner_block = old_block
+    # Pushes the given block onto the emit_yield stack.
+    #
+    # @param block [Proc] block
+    def push_emit_yield_block(block)
+      (@emit_yield_stack ||= []) << block
     end
     # Emits tag attributes into the rendering buffer
     # @param props [Hash] tag attributes
     # @return [void]
@@ -217,6 +340,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.14'
 end

data/lib/papercraft.rb CHANGED Viewed

@@ -16,6 +16,12 @@ module Papercraft
   # by adding namespaced methods to emplates. An extension is implemented as a
   # Ruby module containing one or more methods. Each method in the extension
   # module can be used to render a specific HTML element or a set of elements.
+  #
+  # This is a convenience method. For more information on using Papercraft
+  # extensions, see `Papercraft::Renderer::extension`
+  #
+  # @param map [Hash] hash mapping methods to extension modules
+  # @return [void]
   def self.extension(map)
     Renderer.extension(map)
   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.14'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-12-25 00:00:00.000000000 Z
+date: 2022-01-19 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'