papercraft 0.8.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 944fb4023202a5fb15158b4dcd455eb12f37c5abff353f5ea63e3b605204f52b
-  data.tar.gz: 618aea8b154aff252af187bca43cdc569fae80a6c7a3ec6489b168d61a5ab7e4
+  metadata.gz: 309174da790e301142b03cc8aad3e966c6b1482d514da8d3910c2e84f6981af6
+  data.tar.gz: 64fb5b791fce05c0347ba21ccf70160323f70ad708ece9c14222b8544efdf8e0
 SHA512:
-  metadata.gz: d622166425334b096158ee425e75f4e4ad9c16c466db5aa7f45b51774137def33b4e4f891425bc917ee56b81fb91e39adc15c6f2476e009f3a4be4a73b295c74
-  data.tar.gz: 8546f39f7f6b08cc49049fae52db77891f7664b6ac6d8bce9c0a1a41f19bc0f8a92c59909ab4778cf15d6ef958f756bc6b6f392aa0c028a8d9ddd54bbee67afa
+  metadata.gz: d1f56c25e4854cb6b0ffce1d149d831d51d4141159a44fd6a962c27d9e0878b33e9438d9ad621c0c30a42dfa853b96a26b20c6ebe42243844be2b42d4e2901ef
+  data.tar.gz: 46952658d3e237f784cfd9b608c82b001fdd188b788c931f0a1a3669d5800d8ed3ef89623f88ff9a617237fbfbbd3a0f9f5b30bfc693b2e6f0b5659f66afa41b

data/lib/papercraft/component.rb

@@ -3,13 +3,14 @@
 require_relative './html'
 
 module Papercraft
+
   # Component represents a distinct, reusable HTML template. A component can
   # include other components, and also be nested inside other components.
   #
   # Since in Papercraft HTML is expressed using blocks (or procs,) the Component
   # class is simply a special kind of Proc, which has some enhanced
   # capabilities, allowing it to be easily composed in a variety of ways.
-
+  #
   # Components are usually created using the global methods `H` or `X`, for HTML
   # or XML templates, respectively:
   #
@@ -23,9 +24,64 @@ module Papercraft
   #
   # In the component block, HTML elements are created by simply calling
   # unqualified methods:
+  #
+  #   page_layout = H { html5 { head { title 'foo'
+  #       }
+  #       body {
+  #         h1 "Hello, world!"
+  #       }
+  #     }
+  #   }
+  #
+  # Papercraft components can take explicit parameters in order to render
+  # dynamic content. This can be in the form of regular or named parameters. The
+  # `greeter` template shown above takes a single `name` parameter. Here's how a
+  # anchor component could be implemented with named parameters:
+  #
+  #   anchor = H { |uri: , text: | a(text, href: uri) }
+  #
+  # The above component could later be rendered by passing the needed arguments:
+  #
+  #   anchor.render(uri: 'https://example.com', text: 'Example')
+  #
+  # ## Component Composition
+  #
+  # A component can be included in another component using the `emit` method:
+  #
+  #   links = H {
+  #     emit anchor, uri: '/posts',   text: 'Posts'
+  #     emit anchor, uri: '/archive', text: 'Archive'
+  #     emit anchor, uri: '/about',   text: 'About'
+  #   }
+  #
+  # Another way of composing components is to pass the components themselves as
+  # parameters:
+  #
+  #   links = H { |anchors|
+  #     anchors.each { |a| emit a }
+  #   }
+  #   links.render([
+  #     anchor.apply(uri: '/posts', text: 'Posts'),
+  #     anchor.apply(uri: '/archive', text: 'Archive'),
+  #     anchor.apply(uri: '/about', text: 'About')
+  #   ])
+  #
+  # The `#apply` method creates a new component, applying the given parameters
+  # such that the component can be rendered without parameters:
+  #
+  #   links_with_anchors = links.apply([
+  #     anchor.apply(uri: '/posts', text: 'Posts'),
+  #     anchor.apply(uri: '/archive', text: 'Archive'),
+  #     anchor.apply(uri: '/about', text: 'About')
+  #   ])
+  #   links_with_anchors.render
   class Component < Proc
-    # Initializes a component with the given block
-    # @param mode [Symbol] local context
+
+    # Initializes a component with the given block. The rendering mode (HTML or
+    # XML) can be passed in the `mode:` parameter. If `mode:` is not specified,
+    # the component defaults to HTML.
+    #
+    # @param mode [:html, :xml] rendering mode
     # @param block [Proc] nested HTML block
     def initialize(mode: :html, &block)
       @mode = mode
@@ -34,7 +90,9 @@ module Papercraft
   
     H_EMPTY = {}.freeze
   
-    # Renders the associated block and returns the string result
+    # Renders the template with the given parameters and or block, and returns
+    # the string result.
+    #
     # @param context [Hash] context
     # @return [String]
     def render(*a, **b, &block)
@@ -51,6 +109,24 @@ module Papercraft
       raise Papercraft::Error, e.message
     end
   
+    # Creates a new component, applying the given parameters and or block to the
+    # current one. Application is one of the principal methods of composing
+    # components, particularly when passing inner components as blocks:
+    #
+    # article_wrapper = H {
+    #   article {
+    #     emit_yield
+    #   }
+    # }
+    # wrapped_article = article_wrapper.apply {
+    #   h1 'Article title'
+    # }
+    # wrapped_article.render #=> "<article><h1>Article title</h1></article>"
+    #
+    # @param *a [<any>] normal parameters
+    # @param **b [Hash] named parameters
+    # @param &block [Proc] inner block
+    # @return [Papercraft::Component] applied component
     def apply(*a, **b, &block)
       template = self
       if block
@@ -64,6 +140,10 @@ module Papercraft
       end
     end
   
+    # Returns the Renderer class used for rendering the templates, according to
+    # the component's mode.
+    #
+    # @return [Papercraft::Renderer] Renderer used for rendering the component
     def renderer_class
       case @mode
       when :html

data/lib/papercraft/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.8.2
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-12-22 00:00:00.000000000 Z
+date: 2021-12-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: escape_utils