RubyGems - papercraft - Versions diffs - 0.23 → 0.25 - Mend

papercraft 0.23 → 0.25

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 (7) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 341520b9db20c53da441299fb449c4eea3321924517f4b93e70af1119b4516c3
-  data.tar.gz: 861a5a2747c3a468abb780cf50710698e52fbac1fc236c8672c2bbb328db6f4d
+  metadata.gz: f23902f7431dcbd6c1180e26f612ae5099d4e7f2ba468dd0e0e5e9a76e324ef4
+  data.tar.gz: 5bf38e4faea0ab6c6145d769b24b416e467836b29c6d8856bb96442f86b43bfe
 SHA512:
-  metadata.gz: 7668a984a2c7957ba3f65234eab6770b4e969e0d2b4e1345839db8c0711d07afbfef5735b67de9a94c22994b4b6c1d6b2f87e07a810a0cae04ccbecb1ff5b38f
-  data.tar.gz: 1605f9b1459ab20b9cec97805529764ece6058ce34609dc7d75fe38d8b35889c65e4afa5174f1c1d89dfb46205d282e65e1020995c999f66b84a5f9b5e505de1
+  metadata.gz: 69ed90f079f1db073bbc18b1b631c13cbcd2db5dae9e512781046fb7fa5ab0a164653137b28c201f48671d77e4d08ff1da3818381aca5d3686d61eb185f8a586
+  data.tar.gz: 85681c583e3e145ca27a52638e0d3370fa94462d5baaae8cccb477a1a2938ad56f3040ee4f6cceb2757b49019890bcae505bcdc008e2ff0931987f09ab9eb91a

data/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,12 @@
+## 0.25 2023-01-12
+- Implement `#def_tag` for defining custom tags inline
+## 0.24 2022-03-19
+- Fix usage of const components (#13)
+- Fix formatting of HTML/XML attributes for non-string values
 ## 0.23 2022-02-15
 - Remove unused `Encoding` module

data/README.md CHANGED Viewed

@@ -42,6 +42,10 @@ Papercraft includes built-in support for rendering Markdown (using
 creating template extensions in order to allow the creation of component
 libraries.
+Papercraft automatically escapes all text emitted in templates according to the
+template type. For more information see the section on [escaping
+content](#escaping-content).
 ```ruby
 require 'papercraft'
@@ -59,29 +63,31 @@ hello.render('world')
 #=> "<html><head><title>Title</title></head><body><h1>Hello, world!</h1></body></html>"
 ```
-## Table of content
-- [Installing papercraft](#installing-papercraft)
-- [Basic usage](#basic-usage)
-- [Adding tags](#adding-tags)
-- [Tag and attribute formatting](#tag-and-attribute-formatting)
-- [Template parameters](#template-parameters)
-- [Template logic](#template-logic)
-- [Template blocks](#template-blocks)
-- [Plain procs as templates](#plain-procs-as-templates)
-- [Template composition](#template-composition)
-- [Parameter and block application](#parameter-and-block-application)
-- [Higher-order templates](#higher-order-templates)
-- [Layout template composition](#layout-template-composition)
-- [Emitting raw HTML](#emitting-raw-html)
-- [Emitting a string with HTML Encoding](#emitting-a-string-with-html-encoding)
+## Table of Content
+- [Installing Papercraft](#installing-papercraft)
+- [Basic Usage](#basic-usage)
+- [Adding Tags](#adding-tags)
+- [Tag and Attribute Formatting](#tag-and-attribute-formatting)
+- [Escaping Content](#escaping-content)
+- [Template Parameters](#template-parameters)
+- [Template Logic](#template-logic)
+- [Template Blocks](#template-blocks)
+- [Plain Procs as Templates](#plain-procs-as-templates)
+- [Template Composition](#template-composition)
+- [Parameter and Block Application](#parameter-and-block-application)
+- [Higher-Order Templates](#higher-order-templates)
+- [Layout Template Composition](#layout-template-composition)
+- [Emitting Raw HTML](#emitting-raw-html)
+- [Emitting a String with HTML Encoding](#emitting-a-string-with-html-encoding)
 - [Emitting Markdown](#emitting-markdown)
-- [Working with MIME types](#working-with-mime-types)
-- [Deferred evaluation](#deferred-evaluation)
-- [XML templates](#xml-templates)
-- [JSON templates](#json-templates)
-- [Papercraft extensions](#papercraft-extensions)
-  - [Bundled extensions](#bundled-extensions)
+- [Working with MIME Types](#working-with-mime-types)
+- [Deferred Evaluation](#deferred-evaluation)
+- [XML Templates](#xml-templates)
+- [JSON Templates](#json-templates)
+- [Papercraft Extensions](#papercraft-extensions)
+  - [Inline Helper Methods](#inline-helper-methods)
+  - [Bundled Extensions](#bundled-extensions)
 - [API Reference](#api-reference)
 ## Installing Papercraft
@@ -98,7 +104,7 @@ Or manually:
 $ gem install papercraft
 ```
-## Basic usage
+## Basic Usage
 To create an HTML template use `Papercraft.html`:
@@ -119,7 +125,7 @@ Rendering a template is done using `#render`:
 html.render #=> "<div id="greeter"><p>Hello!</p></div>"
 ```
-## Adding tags
+## Adding Tags
 Tags are added using unqualified method calls, and can be nested using blocks:
@@ -156,7 +162,7 @@ Papercraft.html { img src: '/my.gif' }.render #=> "<img src="/my.gif"/>
 Papercraft.html { p "foobar", class: 'important' }.render #=> "<p class=\"important\">foobar</p>"
 ```
-## Tag and attribute formatting
+## Tag and Attribute Formatting
 Papercraft does not make any presumption about what tags and attributes you can
 use. You can mix upper and lower case letters, and you can include arbitrary
@@ -193,7 +199,23 @@ Papercraft.html {
 }.render #=> '<cra_zy__:!tag>foo</cra_zy__:!tag>'
 ```
-## Template parameters
+## Escaping Content
+Papercraft automatically escapes all text content emitted in a template. The
+specific escaping algorithm depends on the template type. For both HTML and XML
+templates, Papercraft uses
+[escape_utils](https://github.com/brianmario/escape_utils), specifically:
+- HTML: `escape_utils.escape_html`
+- XML: `escape_utils.escape_xml`
+In order to emit raw HTML/XML, you can use the `#emit` method as [described
+below](#emitting-raw-html).
+JSON templates are rendered using the `json` gem bundled with Ruby, which takes
+care of escaping text values.
+## Template Parameters
 In Papercraft, parameters are always passed explicitly. This means that template
 parameters are specified as block parameters, and are passed to the template on
@@ -211,7 +233,7 @@ greeting = Papercraft.html { |name:| h1 "Hello, #{name}!" }
 greeting.render(name: 'world') #=> "<h1>Hello, world!</h1>"
 ```
-## Template logic
+## Template Logic
 Since Papercraft templates are just a bunch of Ruby, you can easily write your
 view logic right in the template:
@@ -226,7 +248,7 @@ Papercraft.html { |user = nil|
 }
 ```
-## Template blocks
+## Template Blocks
 Templates can also accept and render blocks by using `emit_yield`:
@@ -241,7 +263,7 @@ page = Papercraft.html {
 page.render { h1 'hi' }
 ```
-## Plain procs as templates
+## Plain Procs as Templates
 With Papercraft you can write a template as a plain Ruby proc, and later render
 it by passing it as a block to `Papercraft.html`:
@@ -258,7 +280,7 @@ greeting = ->(name) { h1 "Hello, #{name}!" }
 Papercraft.html(&greeting).render('world')
 ```
-## Template composition
+## Template Composition
 Papercraft makes it easy to compose multiple templates into a whole HTML
 document. A Papercraft template can contain other templates, as the following
@@ -308,7 +330,7 @@ Papercraft.html {
 }
 ```
-## Parameter and block application
+## Parameter and Block Application
 Parameters and blocks can be applied to a template without it being rendered, by
 using `#apply`. This mechanism is what allows template composition and the
@@ -333,7 +355,7 @@ wrapped_hello_world = div_wrap.apply(&hello_world)
 wrapped_hello_world.render #=> "<div><h1>Hello, world!</h1></div>"
 ```
-## Higher-order templates
+## Higher-Order Templates
 Papercraft also lets you create higher-order templates, that is,
 templates that take other templates as parameters, or as blocks. Higher-order
@@ -357,7 +379,7 @@ wrapped_greeter = div_wrap.apply { h1 'hi' }
 wrapped_greeter.render #=> "<div><h1>hi</h1></div>"
 ```
-## Layout template composition
+## Layout Template Composition
 One of the principal uses of higher-order templates is the creation of nested
 layouts. Suppose we have a website with a number of different layouts, and we'd
@@ -390,7 +412,7 @@ article_layout.render(
 )
 ```
-## Emitting raw HTML
+## Emitting Raw HTML
 Raw HTML can be emitted using `#emit`:
@@ -399,13 +421,13 @@ wrapped = Papercraft.html { |html| div { emit html } }
 wrapped.render("<h1>hi</h1>") #=> "<div><h1>hi</h1></div>"
 ```
-## Emitting a string with HTML Encoding
+## Emitting a String with HTML Encoding
 To emit a string with proper HTML encoding, without wrapping it in an HTML
 element, use `#text`:
 ```ruby
-Papercraft.html { str 'hi&lo' }.render #=> "hi&amp;lo"
+Papercraft.html { text 'hi&lo' }.render #=> "hi&amp;lo"
 ```
 ## Emitting Markdown
@@ -454,7 +476,7 @@ The deafult options can be configured by accessing
 Papercraft.default_kramdown_options[:auto_ids] = false
 ```
-## Working with MIME types
+## Working with MIME Types
 Papercraft lets you set and interrogate a template's MIME type, in order to be
 able to dynamically set the `Content-Type` HTTP response header. A template's
@@ -470,7 +492,7 @@ def serve_template(req, template)
 end
 ```
-## Deferred evaluation
+## Deferred Evaluation
 Deferred evaluation allows deferring the rendering of parts of a template until
 the last moment, thus allowing an inner template to manipulate the state of the
@@ -522,7 +544,7 @@ page = default_layout.apply {
 }
 ```
-## XML templates
+## XML Templates
 XML templates behave largely the same as HTML templates, with a few minor
 differences. XML templates employ a different encoding algorithm, and lack some
@@ -557,7 +579,7 @@ rss = Papercraft.xml(mime_type: 'text/xml; charset=utf-8') { |resource:, **props
 }
 ```
-## JSON templates
+## JSON Templates
 JSON templates behave largely the same as HTML and XML templates. The only major
 difference is that for adding array items you'll need to use the `#item` method:
@@ -588,7 +610,7 @@ Papercraft.json {
 Papercraft uses the [JSON gem](https://rubyapi.org/3.1/o/json) under the hood in
 order to generate actual JSON.
-## Papercraft extensions
+## 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
@@ -660,6 +682,57 @@ Papercraft.html {
 }
 ```
+## Inline Helper Methods
+In addition to proper extensions defined in modules, you can also define
+individual extension methods inline in your Papercraft templates. You can do
+this using any of the following techniques:
+1. Define a method in the template body:
+```ruby
+Papercraft.html {
+  def label(text)
+    span text, class: 'label'
+  end
+  label 'foo'
+  label 'bar'
+}
+```
+2. Use `def_tag` to define a custom tag:
+```ruby
+Papercraft.html {
+  def_tag(:label) { |text| span text, class: 'label' }
+  label 'foo'
+  label 'bar'
+}
+```
+Note that using any of the above methods you can also create custom components
+that take a block with inner HTML:
+```ruby
+# using def
+def section(title, &inner)
+  div {
+    h1 title
+    emit inner
+  }
+end
+# using def_tag
+def_tag(:section) do |title, &inner|
+  div {
+    h1 title
+    emit inner
+  }
+end
+```
 ## Bundled Extensions
 Papercraft comes bundled with a few extensions that address common use cases.
@@ -669,7 +742,7 @@ be specifically required in order to be available to templates.
 For all bundled Papercraft extensions, there's no need to call
 `Papercraft.extension`, requiring the extension is sufficient.
-### SOAP extension
+### SOAP Extension
 > The SOAP extension was contributed by [@aemadrid](https://github.com/aemadrid).
@@ -713,4 +786,4 @@ xml = Papercraft.xml {
 ## API Reference
 The API reference for this library can be found
-[here](https://www.rubydoc.info/gems/papercraft).
+[here](https://www.rubydoc.info/gems/papercraft).

data/lib/papercraft/renderer.rb CHANGED Viewed

@@ -47,17 +47,17 @@ module Papercraft
       # components. In cases where method names in the module clash with XML
       # 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 }
-      #     }
+      #   module ComponentLibrary
+      #     def card(title, content)
+      #       div(class: 'card') {
+      #         h3 title
+      #         div(class: 'card-content') { emit_markdown content }
+      #       }
+      #     end
       #   end
-      # end
       #
-      # Papercraft.extension(components: ComponentLibrary)
-      # Papercraft.html { components.card('Foo', '**Bar**') }
+      #   Papercraft.extension(components: ComponentLibrary)
+      #   Papercraft.html { components.card('Foo', '**Bar**') }
       #
       # @param map [Hash] hash mapping methods to extension modules
       # @return [void]

data/lib/papercraft/tags.rb CHANGED Viewed

@@ -161,14 +161,13 @@ module Papercraft
     # @return [void]
     def method_missing(sym, *args, **opts, &block)
       tag = sym.to_s
-      repr = tag_repr(tag)
-      code = S_TAG_METHOD % {
-        tag: tag,
-        TAG: tag.upcase,
-        tag_pre: "<#{repr}".inspect,
-        tag_close: "</#{repr}>".inspect
-      }
-      self.class.class_eval(code, __FILE__, S_TAG_METHOD_LINE)
+      if tag =~ /^[A-Z]/ && (Object.const_defined?(tag))
+        define_const_tag_method(tag)
+        # return send(tag, *args, **opts)
+      else
+        define_tag_method(tag)
+      end
       send(sym, *args, **opts, &block)
     end
@@ -181,8 +180,58 @@ module Papercraft
       @buffer << escape_text(data)
     end
+    # Defines a custom tag. This is handy for defining helper or extension
+    # methods inside the template body.
+    #
+    #   Papercraft.html {
+    #     def_tag(:section) { |title, &inner|
+    #       div {
+    #         h1 title
+    #         emit inner
+    #       }
+    #     }
+    #
+    #     section('Foo') {
+    #       p 'Bar'
+    #     }
+    #   }
+    #
+    # @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)
+    end
     private
+    # Defines a method that emits the given tag based on a constant. The
+    # constant must be defined on the main (Object) binding.
+    #
+    # @param tag [Symbol, String] tag/method name
+    # @return [void]
+    def define_const_tag_method(tag)
+      const = Object.const_get(tag)
+      self.class.define_method(tag) { |*a, **b, &blk|
+        emit const, *a, **b, &blk
+      }
+    end
+    # Defines a normal tag method.
+    #
+    # @param tag [Symbol, String] tag/method name
+    # @return [void]
+    def define_tag_method(tag)
+      repr = tag_repr(tag)
+      code = S_TAG_METHOD % {
+        tag: tag,
+        TAG: tag.upcase,
+        tag_pre: "<#{repr}".inspect,
+        tag_close: "</#{repr}>".inspect
+      }
+      self.class.class_eval(code, __FILE__, S_TAG_METHOD_LINE)
+    end
     # Emits an arbitrary object by converting it to string, then adding it to
     # the internal buffer. This method is called internally by `Renderer#emit`.
     #
@@ -251,7 +300,7 @@ module Papercraft
             # emit nothing
           else
             @buffer << S_SPACE << att_repr(k) <<
-              S_EQUAL_QUOTE << v << S_QUOTE
+              S_EQUAL_QUOTE << escape_text(v) << S_QUOTE
           end
         end
       }

data/lib/papercraft/version.rb CHANGED Viewed

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

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '0.23'
+  version: '0.25'
 platform: ruby
 authors:
 - Sharon Rosner
-autorequire:
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-02-15 00:00:00.000000000 Z
+date: 2023-01-12 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: []
@@ -152,7 +152,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
@@ -171,8 +171,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
-signing_key:
+rubygems_version: 3.4.1
+signing_key:
 specification_version: 4
 summary: 'Papercraft: component-based HTML templating for Ruby'
 test_files: []