RubyGems - papercraft - Versions diffs - 0.10 → 0.13 - Mend

papercraft 0.10 → 0.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7d34aa76efd449fc6a63182195e8353886887e13963b79439a19dc3b0f9a9d2
-  data.tar.gz: e199245d969426b75627401b7c57fe1a01e7121a656ece8cd97b004a22b3ab2e
+  metadata.gz: 5250720b438ab385dca9f3b91487fc2e5c887ba7e709015f8e26a1a2e78fa8d6
+  data.tar.gz: '049f2399c403f55fdd0c0ee9de3b9bac5d314d0c57520184ddc59f361f7ec87d'
 SHA512:
-  metadata.gz: 75d5dd94c26d1ee15b11f8a439ff1c26cd7336c60ce609e334f3c0e823e8813f67923b79e8f023e9d1bcc3f2af20b5fffc93196ba5731d1cea42b2e0f75f3102
-  data.tar.gz: 7bdcbfa67dabec451c00f006256b16b9875d60fc726d295135db5de94a5b8854e3bdf648410d6ef6e7a7b76766c6c07d21ebb4da9788cab45fcb67a8c9d6b221
+  metadata.gz: 176f86dbf9e69deaf1fd60edbcba23401c1288a96d9eb5210175815e1ea1b297178daf2ba3533ae8020d18b8bc1b7003bcf39b2175c4ad95439982d622c01fad
+  data.tar.gz: 9f623e968a7462225e4f504c880a911557d024b45393658bec01426ebff934bfa9c94094ca52feae8c2a23b642054e9cd3b88df25644019a61f62c5fda4350ad

data/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,21 @@
+## 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
 ## 0.10 2021-12-25
 - Add support for extensions

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

@@ -138,11 +138,11 @@ module Papercraft
       template = self
       if block
         Component.new(&proc do |*x, **y|
-          with_block(block) { instance_exec(*x, **y, &template) }
+          with_block(block) { instance_exec(*a, *x, **b, **y, &template) }
         end)
       else
         Component.new(&proc do |*x, **y|
-          instance_exec(*a, **b, &template)
+          instance_exec(*a, *x, **b, **y, &template)
         end)
       end
     end

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,15 +93,36 @@ 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?
+          props = text
+          text = nil
+        end
         @buffer << S_TAG_%<TAG>s_PRE
         emit_props(props) unless props.empty?
@@ -98,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
@@ -107,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
@@ -155,6 +246,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              = '>'
@@ -212,6 +339,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'
+  VERSION = '0.13'
 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'
+  version: '0.13'
 platform: ruby
 authors:
 - Sharon Rosner
-autorequire:
+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
@@ -122,7 +122,7 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 2.0.9
-description:
+description:
 email: sharon@noteflakes.com
 executables: []
 extensions: []
@@ -147,7 +147,7 @@ metadata:
   documentation_uri: https://www.rubydoc.info/gems/papercraft
   homepage_uri: https://github.com/digital-fabric/papercraft
   changelog_uri: https://github.com/digital-fabric/papercraft/blob/master/CHANGELOG.md
-post_install_message:
+post_install_message:
 rdoc_options:
 - "--title"
 - Papercraft
@@ -166,8 +166,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key:
+rubygems_version: 3.3.3
+signing_key:
 specification_version: 4
 summary: 'Papercraft: component-based HTML templating for Ruby'
 test_files: []