papercraft 1.1 → 1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41c765213957fc2681e2f4cd7d94e7580e45394128d61a800349aa6e848c6b00
-  data.tar.gz: 5c2b0a91c3d4c744db20536d08ae741a07dab3a9cfc2c5fa790ea987224b5c7e
+  metadata.gz: 5ce5c8e506f96cd5e49625ba875bec30df1fe7849cf726e715383edf1feec4dd
+  data.tar.gz: fa5a04e6baf5b8e8e36d08a8e9bc962da886c48881489f699b1abab51bc06181
 SHA512:
-  metadata.gz: cf87f3ae1bcf718ad7b03e5b1b895cd8065e2aee72f7044cf0fb822db029477aa98297b8caf66d9e3db1ee664d9e42a954afb203f856fa6f190765defe5139e1
-  data.tar.gz: bfd2847daa9f2d9be7a0aa7e0adee170771e3fcdd6ca0ad407478f7b5bff2848b63639d21c26d1b9d040ac44b741d9032ac24742e839e19f1327d81ffd88e901
+  metadata.gz: 9fd2b6f1ce19479f6a57a5ca75f238b7fb7dee33a3275c2d7f786a1630a5ea5ca5f2d3210946c2ee1dd55676dce65fe0d3503bab830980e5d11fef216a76b5fd
+  data.tar.gz: 32bd431564ba19783822b5f0596d6f13fc9bd3fee6c498b0d5a9d9722bd536f19ee90fec74a8933460324fbe47d1eab860f3700b6d07bc904c60b131933c5a7b

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 1.2 2023-08-21
+
+- Update dependencies
+- Implement template fragments
+
 ## 1.1 2023-07-03
 
 - Add direct iteration using the `_for` attribute

data/README.md

@@ -72,10 +72,11 @@ hello.render('world')
 - [Adding Tags](#adding-tags)
 - [Tag and Attribute Formatting](#tag-and-attribute-formatting)
 - [Escaping Content](#escaping-content)
-- [Direct Iteration][#direct-iteration]
+- [Direct Iteration](#direct-iteration)
 - [Template Parameters](#template-parameters)
 - [Template Logic](#template-logic)
 - [Template Blocks](#template-blocks)
+- [Template Fragments](#template-fragments)
 - [Plain Procs as Templates](#plain-procs-as-templates)
 - [Template Composition](#template-composition)
 - [Parameter and Block Application](#parameter-and-block-application)
@@ -381,6 +382,35 @@ page = Papercraft.html {
 page.render { h1 'hi' }
 ```
 
+## Template Fragments
+
+Template fragments allow rendering specific parts of a template, instead of the
+entire template. For example, you can define a template for a web page that
+includes a form, but may want to render just the form. Instead of extracting the
+code and putting it into a separate template, you can use template fragments to
+render just that part of that template:
+
+```ruby
+page = Papercraft.html {
+  div {
+    h1 'Page title'
+    p 'Some text'
+  }
+  div(id: 'my-form') {
+    fragment(:form) {
+      form {
+        input(name: 'email')
+        button 'OK'
+      }
+    }
+  }
+}
+page.render_fragment(:form)
+```
+
+For more information on how to use template fragments, see the [HTMX
+article](https://htmx.org/essays/template-fragments/).
+
 ## Plain Procs as Templates
 
 With Papercraft you can write a template as a plain Ruby proc, and later render

data/lib/papercraft/extension_proxy.rb

@@ -24,7 +24,6 @@ module Papercraft
     # @param sym [Symbol] method name
     # @param *args [Array] arguments
     # @param *props [Array] named arguments
-    # @param &block [Proc] block
     # @return void
     def method_missing(sym, *args, **props, &block)
       @renderer.send(sym, *args, **props, &block)
@@ -34,7 +33,6 @@ module Papercraft
     #
     # @param *args [Array] arguments
     # @param *props [Array] named arguments
-    # @param &block [Proc] block
     # @return void
     def p(text = nil, **props, &block)
       @renderer.p(text, **props, &block)

data/lib/papercraft/extensions/soap.rb

@@ -6,7 +6,6 @@ module Papercraft
       # Emits a SOAP XML tag that identifies the XML document as a SOAP message.
       #
       # @param **props [Hash] tag attributes
-      # @param &block [Proc] optional inner XML
       # @return [void]
       def Envelope(**props, &block)
         props[:xmlns__soap] ||= 'http://schemas.xmlsoap.org/soap/envelope/'
@@ -16,7 +15,6 @@ module Papercraft
       # Emits a SOAP XML tag that contains header information.
       #
       # @param **props [Hash] tag attributes
-      # @param &block [Proc] optional inner XML
       # @return [void]
       def Header(**props, &blk)
         tag('soap:Header', **props, &blk)
@@ -25,7 +23,6 @@ module Papercraft
       # Emits a SOAP XML tag that contains header information.
       #
       # @param **props [Hash] tag attributes
-      # @param &block [Proc] optional inner XML
       # @return [void]
       def Body(**props, &blk)
         tag('soap:Body', **props, &blk)
@@ -34,7 +31,6 @@ module Papercraft
       # Emits a SOAP XML tag that contains errors and status information.
       #
       # @param **props [Hash] tag attributes
-      # @param &block [Proc] optional inner XML
       # @return [void]
       def Fault(**props, &blk)
         tag('soap:Fault', **props, &blk)

data/lib/papercraft/html.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative './tags'
+require 'cgi'
 
 module Papercraft
   # HTML Markup extensions
@@ -10,7 +11,7 @@ module Papercraft
     # Emits the p tag (overrides Object#p)
     #
     # @param text [String] text content of tag
-    # @param props [Hash] tag attributes
+    # @param **props [Hash] tag attributes
     # @para block [Proc] nested HTML block
     # @return [void]
     def p(text = nil, **props, &block)
@@ -131,7 +132,7 @@ module Papercraft
     # Returns true if the given tag is a void element, in order to render a self
     # closing tag. See spec: https://html.spec.whatwg.org/multipage/syntax.html#void-elements.
     #
-    # @param text [String] tag
+    # @param tag [String] tag
     # @return [Bool] is it a void element
     def is_void_element_tag?(tag)
       case tag
@@ -148,7 +149,7 @@ module Papercraft
     # @param text [String] text
     # @return [String] escaped text
     def escape_text(text)
-      EscapeUtils.escape_html(text.to_s)
+      CGI.escapeHTML(text.to_s)
     end
 
     # Converts a tag to its string representation. Underscores will be converted

data/lib/papercraft/json.rb

@@ -15,8 +15,12 @@ module Papercraft
     # block is evaulated against a new object target, then added to the current
     # array.
     #
+    #   Papercraft.json {
+    #     item 'foo'
+    #     item 'bar'
+    #   }.render #=> "[\"foo\", \"bar\"]"
+    #
     # @param value [Object] item
-    # @param &block [Proc] template block
     # @return [void]
     def item(value = nil, _for: nil, &block)
       return _for.each { |*a| item(value) { block.(*a)} } if _for
@@ -34,7 +38,6 @@ module Papercraft
     #
     # @param key [Object] key
     # @param value [Object] value
-    # @param &block [Proc] template block
     # @return [void]
     def kv(key, value = nil, &block)
       verify_hash_target
@@ -47,12 +50,11 @@ module Papercraft
     # Intercepts method calls by adding key-value pairs to the current object
     # target.
     #
-    # @param key [Object] key
+    # @param key [Symbol] key
     # @param value [Object] value
-    # @param &block [Proc] template block
     # @return [void]
-    def method_missing(sym, value = nil, &block)
-      kv(sym, value, &block)
+    def method_missing(key, value = nil, &block)
+      kv(key, value, &block)
     end
 
     # Converts the root object target to JSON.
@@ -66,7 +68,6 @@ module Papercraft
 
     # Adds a new entry to the object stack and evaluates the given block.
     #
-    # @param &block [Proc] template block
     # @return [void]
     def with_object(&block)
       @object_stack << nil
@@ -117,7 +118,6 @@ module Papercraft
     # Adds a new object to the object stack, evaluates the given template block,
     # then pops the object off the stack.
     #
-    # @param &block [Proc] template block
     # @return [void]
     def enter_object(&block)
       @object_stack << nil

data/lib/papercraft/renderer.rb

@@ -84,7 +84,8 @@ module Papercraft
     # renderer's scope.
     #
     # @param &template [Proc] template block
-    def initialize(&template)
+    def initialize(render_fragment = nil, &template)
+      @render_fragment = render_fragment
       instance_eval(&template)
     end
 
@@ -119,7 +120,7 @@ module Papercraft
     end
     alias_method :e, :emit
 
-    # Emits a block supplied using `Component#apply` or `Component#render`.
+    # Emits a block supplied using {Template#apply} or {Template#render}.
     #
     #   div_wrap = Papercraft.html { |*args| div { emit_yield(*args) } }
     #   greeter = div_wrap.apply { |name| h1 "Hello, #{name}!" }
@@ -135,6 +136,33 @@ module Papercraft
       instance_exec(*a, **b, &block)
     end
 
+    # Defines a named template fragment. Template fragments allow rendering
+    # specific parts of the same template. A template fragment can be rendered
+    # using {Template#render_fragment}. See also
+    # {https://htmx.org/essays/template-fragments/ HTMX template fragments}.
+    #
+    #   form = Papercraft.html {
+    #     h1 'Hello'
+    #     fragment(:buttons) {
+    #       button 'OK'
+    #       button 'Cancel'
+    #     }
+    #   }
+    #   form.render_fragment(:buttons) #=> "<button>OK</button><button>Cancel</buttons>"
+    #
+    # @param name [Symbol, String] fragment name
+    # @return [void]
+    def fragment(name, &block)
+      raise Papercraft::Error, "Already in fragment" if @fragment
+
+      begin
+        @fragment = name
+        emit(block)
+      ensure
+        @fragment = nil
+      end
+    end
+
     private
 
     # Pushes the given block onto the emit_yield stack.

data/lib/papercraft/tags.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative './extension_proxy'
+require 'escape_utils'
 
 module Papercraft
   # Markup (HTML/XML) extensions
@@ -23,6 +24,8 @@ module Papercraft
       S_TAG_%<TAG>s_CLOSE = %<tag_close>s
 
       def %<tag>s(text = nil, _for: nil, **props, &block)
+        return if @render_fragment && @fragment != @render_fragment
+
         return _for.each { |*a| %<tag>s(text, **props) { block.(*a)} } if _for
 
         if text.is_a?(Hash) && props.empty?
@@ -55,6 +58,8 @@ module Papercraft
       S_TAG_%<TAG>s_CLOSE = %<tag_close>s
 
       def %<tag>s(text = nil, _for: nil, **props, &block)
+        return if @render_fragment && @fragment != @render_fragment
+        
         return _for.each { |*a| %<tag>s(text, **props) { block.(*a)} } if _for
 
         if text.is_a?(Hash) && props.empty?
@@ -84,9 +89,9 @@ module Papercraft
     INITIAL_BUFFER_CAPACITY = 8192
 
     # Initializes a tag renderer.
-    def initialize(&template)
+    def initialize(render_fragment = nil, &template)
       @buffer = String.new(capacity: INITIAL_BUFFER_CAPACITY)
-      super
+      super(render_fragment)
     end
 
     # Returns the rendered template.
@@ -134,7 +139,6 @@ module Papercraft
     #     h1 'content'
     #   }
     #
-    # @param &block [Proc] Deferred block to be emitted
     # @return [void]
     def defer(&block)
       if !@parts
@@ -161,9 +165,10 @@ module Papercraft
     # @param sym [Symbol, String] XML tag
     # @param text [String, nil] tag content
     # @param **props [Hash] tag attributes
-    # @param &block [Proc] optional inner XML
     # @return [void]
     def tag(sym, text = nil, _for: nil, **props, &block)
+      return if @render_fragment && @fragment != @render_fragment
+        
       return _for.each { |*a| tag(sym, text, **props) { block.(*a)} } if _for
 
       if text.is_a?(Hash) && props.empty?
@@ -195,10 +200,9 @@ module Papercraft
 
     # Catches undefined tag method call and handles it by defining the method.
     #
-    # @param sym [Symbol] XML tag or component identifier
+    # @param sym [Symbol] tag or component identifier
     # @param args [Array] method arguments
     # @param opts [Hash] named method arguments
-    # @param &block [Proc] block passed to method
     # @return [void]
     def method_missing(sym, *args, **opts, &block)
       tag = sym.to_s
@@ -217,6 +221,8 @@ module Papercraft
     # @param data [String] text
     # @return [void]
     def text(data)
+      return if @render_fragment && @fragment != @render_fragment
+        
       @buffer << escape_text(data)
     end
 
@@ -239,8 +245,8 @@ module Papercraft
     # @param tag [Symbol, String] tag/method name
     # @param block [Proc] method body
     # @return [void]
-    def def_tag(sym, &block)
-      self.class.define_method(sym, &block)
+    def def_tag(tag, &block)
+      self.class.define_method(tag, &block)
     end
 
     alias_method :orig_extend, :extend
@@ -333,13 +339,14 @@ module Papercraft
     # @param obj [Object] emitted object
     # @return [void]
     def emit_object(obj)
+      return if @render_fragment && @fragment != @render_fragment
+        
       @buffer << obj.to_s
     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
@@ -385,8 +392,7 @@ module Papercraft
       props.each { |k, v|
         case k
         when :src, :href
-          @buffer << S_SPACE << k.to_s << S_EQUAL_QUOTE <<
-            EscapeUtils.escape_uri(v) << S_QUOTE
+          @buffer << S_SPACE << k.to_s << S_EQUAL_QUOTE << EscapeUtils.escape_uri(v) << S_QUOTE
         else
           case v
           when true

data/lib/papercraft/template.rb

@@ -113,8 +113,9 @@ module Papercraft
     # Renders the template with the given parameters and or block, and returns
     # the string result.
     #
-    # @param context [Hash] context
-    # @return [String]
+    # @param *params [any] unnamed parameters
+    # @param **named_params [any] named parameters
+    # @return [String] rendered string
     def render(*a, **b, &block)
       template = self
       Renderer.verify_proc_parameters(template, a, b)
@@ -124,6 +125,32 @@ module Papercraft
       end.to_s
     end
 
+    # Renders a template fragment. Any given parameters are passed to the
+    # template just like with {Template#render}. See also
+    # {https://htmx.org/essays/template-fragments/ HTMX template fragments}.
+    #
+    #   form = Papercraft.html { |action|
+    #     h1 'Hello'
+    #     fragment(:buttons) {
+    #       button action
+    #       button 'Cancel'
+    #     }
+    #   }
+    #   form.render_fragment(:buttons, 'foo') #=> "<button>foo</button><button>Cancel</buttons>"
+    #
+    # @param name [Symbol, String] fragment name
+    # @param *params [any] unnamed parameters
+    # @param **named_params [any] named parameters
+    # @return [String] rendered string
+    def render_fragment(name, *a, **b, &block)
+      template = self
+      Renderer.verify_proc_parameters(template, a, b)
+      renderer_class.new(name) do
+        push_emit_yield_block(block) if block
+        instance_exec(*a, **b, &template)
+      end.to_s
+    end
+
     # Creates a new template, applying the given parameters and or block to the
     # current one. Application is one of the principal methods of composing
     # templates, particularly when passing inner templates as blocks:
@@ -140,7 +167,6 @@ module Papercraft
     #
     # @param *a [<any>] normal parameters
     # @param **b [Hash] named parameters
-    # @param &block [Proc] inner block
     # @return [Papercraft::Template] applied template
     def apply(*a, **b, &block)
       template = self

data/lib/papercraft/version.rb

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

data/lib/papercraft/xml.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require 'escape_utils'
 require_relative './tags'
+require 'escape_utils'
 
 module Papercraft
   # XML renderer extensions

data/lib/papercraft.rb

@@ -79,7 +79,7 @@ module Papercraft
     # default Kramdown options in order to change the rendering behaviour.
     #
     # @param markdown [String] Markdown
-    # @param **opts [Hash] Kramdown option overrides
+    # @param opts [Hash] Kramdown option overrides
     # @return [String] HTML
     def markdown(markdown, **opts)
       opts = default_kramdown_options.merge(opts)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '1.1'
+  version: '1.2'
 platform: ruby
 authors:
 - Sharon Rosner
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-03 00:00:00.000000000 Z
+date: 2023-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: escape_utils
@@ -16,42 +16,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.1
+        version: 1.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.1
+        version: 1.3.0
 - !ruby/object:Gem::Dependency
   name: kramdown
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.1
+        version: 2.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.1
+        version: 2.4.0
 - !ruby/object:Gem::Dependency
   name: rouge
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.27.0
+        version: 4.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.27.0
+        version: 4.1.3
 - !ruby/object:Gem::Dependency
   name: kramdown-parser-gfm
   requirement: !ruby/object:Gem::Requirement
@@ -72,14 +72,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.15'
+        version: '5.19'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.15'
+        version: '5.19'
 - !ruby/object:Gem::Dependency
   name: benchmark-ips
   requirement: !ruby/object:Gem::Requirement
@@ -114,15 +114,15 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.1.0
+        version: 2.2.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.1.0
-description: 
+        version: 2.2.0
+description:
 email: sharon@noteflakes.com
 executables: []
 extensions: []
@@ -153,7 +153,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
@@ -173,7 +173,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.4.1
-signing_key: 
+signing_key:
 specification_version: 4
 summary: 'Papercraft: component-based HTML templating for Ruby'
 test_files: []