RubyGems - papercraft - Versions diffs - 0.17 → 0.21 - Mend

papercraft 0.17 → 0.21

Files changed (14) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +19 -0
data/README.md +135 -51
data/lib/papercraft/extension_proxy.rb +3 -1
data/lib/papercraft/html.rb +32 -0
data/lib/papercraft/json.rb +89 -36
data/lib/papercraft/renderer.rb +12 -240
data/lib/papercraft/tags.rb +261 -0
data/lib/papercraft/{component.rb → template.rb} +29 -26
data/lib/papercraft/version.rb +1 -1
data/lib/papercraft/xml.rb +39 -0
data/lib/papercraft.rb +17 -17
data/papercraft.png +0 -0
metadata +7 -3

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31c80224c2a9dc3a6d594d923e9a16ccd8127284bce501f1d7f1dc25386bf25c
-  data.tar.gz: 45dc43d353bc1f3c06e62d1b439751570ce7d46a915b0a72f1ce3ea182b0c225
+  metadata.gz: a23bf614d84747a18eecf84545604c9c2f58710dc3fa0e0c651a863a53c919b0
+  data.tar.gz: 6b1ca8f4a90801beff11807dd357ce801b7526b5d114d5cca5f41f41aec69958
 SHA512:
-  metadata.gz: 67529d1336456dded5d911548941c1accc695bd017b889b378ed008e177707b100e11e90b1adbe887d45530cfb94950808e21257955999d795b388dbeb13206e
-  data.tar.gz: 1caca448eb2a317b1616a529e82803f6571e26e8b0f36a19e771b2b4a9a96cabb8695ad5a01148acfa7481b016742e9c546c794fd2a9017ec54d299184d36c94
+  metadata.gz: dcd7eada8280cb0fcd68528eaea0d2500ff99ac149c8495dd5a3955a93c3f181301a4decc9eeb4d7efdd8cfe2c4f6047c9f838e5084b413c1118a76d6abc4252
+  data.tar.gz: 840ce0fc2a83de9b5a83bb10a5f4ed98986f7201737d6e31a4e89877aeb6bb22b2f2449c6efa08302473c073e26c830cfbe9e267456b450a56222b57a429fd15

data/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,22 @@
+## 0.21 2022-02-13
+- Refactor and improve documentation
+## 0.20 2022-02-13
+- Add support for XML namespaced tags and attributes (#9)
+- Move and refactor HTML/XML common code to Tags module
+## 0.19 2022-02-05
+- Rename `Papercraft::Component` to `Papercraft::Template`
+## 0.18 2022-02-04
+- Cleanup and update examples
+- Fix behaviour of #emit with block
+- Improve README
 ## 0.17 2022-01-23
 - Refactor markdown code, add `Papercraft.markdown` method (#8)

data/README.md CHANGED Viewed

@@ -24,35 +24,63 @@
 ## What is Papercraft?
+Papercraft is a templating engine for dynamically producing HTML, XML or JSON.
+Papercraft templates are expressed in plain Ruby, leading to easier debugging,
+better protection against HTML/XML injection attacks, and better code reuse.
+Papercraft templates can be composed in a variety of ways, facilitating the
+usage of layout templates, and enabling a component-oriented approach to
+building complex web interfaces.
+In Papercraft, dynamic data is passed explicitly to the template as block
+arguments, making the data flow easy to follow and understand. Papercraft also
+lets developers create derivative templates using full or partial parameter
+application.
+Papercraft includes built-in support for rendering Markdown (using
+[Kramdown](https://github.com/gettalong/kramdown/)), as well as support for
+creating template extensions in order to allow the creation of component
+libraries.
 ```ruby
 require 'papercraft'
 page = Papercraft.html { |*args|
   html {
-    head { }
+    head { title 'Title' }
     body { emit_yield *args }
   }
 }
 page.render { p 'foo' }
-#=> "<html><head/><body><p>foo</p></body></html>"
+#=> "<html><head><title>Title</title></head><body><p>foo</p></body></html>"
 hello = page.apply { |name| h1 "Hello, #{name}!" }
 hello.render('world')
-#=> "<html><head/><body><h1>Hello, world!</h1></body></html>"
-```
-Papercraft is a templating engine for Ruby that offers the following features:
-- HTML, XML and JSON templating using plain Ruby syntax
-- Minimal boilerplate
-- Mix logic and tags freely
-- Automatic HTML and XML escaping
-- Composable components
-- Standard or custom MIME types
-- Explicit parameter passing to nested components
-- Higher order components
-- Built-in support for rendering [Markdown](#emitting-markdown)
-- Support for namespaced extensions
+#=> "<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)
+- [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)
+- [Papercraft extensions](#papercraft-extensions)
+- [XML templates](#xml-templates)
+- [JSON templates](#json-templates)
+- [API Reference](#api-reference)
 ## Installing Papercraft
@@ -68,9 +96,9 @@ Or manually:
 $ gem install papercraft
 ```
-## Getting started
+## Basic usage
-To create a template use the global method `Kernel#H`:
+To create an HTML template use `Papercraft.html`:
 ```ruby
 require 'papercraft'
@@ -80,13 +108,16 @@ html = Papercraft.html {
 }
 ```
+(You can also use `Papercraft.xml` and `Papercraft.json` to create XML and JSON
+templates, respectively.)
 Rendering a template is done using `#render`:
 ```ruby
 html.render #=> "<div id="greeter"><p>Hello!</p></div>"
 ```
-## All about tags
+## Adding tags
 Tags are added using unqualified method calls, and can be nested using blocks:
@@ -141,7 +172,7 @@ greeting = Papercraft.html { |name:| h1 "Hello, #{name}!" }
 greeting.render(name: 'world') #=> "<h1>Hello, world!</h1>"
 ```
-## Logic in templates
+## Template logic
 Since Papercraft templates are just a bunch of Ruby, you can easily write your
 view logic right in the template:
@@ -171,10 +202,10 @@ page = Papercraft.html {
 page.render { h1 'hi' }
 ```
-## Plain procs as components
+## 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 `H`:
+it by passing it as a block to `Papercraft.html`:
 ```ruby
 greeting = proc { |name| h1 "Hello, #{name}!" }
@@ -188,10 +219,10 @@ greeting = ->(name) { h1 "Hello, #{name}!" }
 Papercraft.html(&greeting).render('world')
 ```
-## Component composition
+## Template composition
-Papercraft makes it easy to compose multiple components into a whole HTML
-document. A Papercraft component can contain other components, as the following
+Papercraft makes it easy to compose multiple templates into a whole HTML
+document. A Papercraft template can contain other templates, as the following
 example shows.
 ```ruby
@@ -219,14 +250,14 @@ page = Papercraft.html { |title, items|
   }
 }
-page.render('Hello from components', [
+page.render('Hello from composed templates', [
   { id: 1, text: 'foo', checked: false },
   { id: 2, text: 'bar', checked: true }
 ])
 ```
-In addition to using components defined as constants, you can also use
-non-constant components by invoking the `#emit` method:
+In addition to using templates defined as constants, you can also use
+non-constant templates by invoking the `#emit` method:
 ```ruby
 greeting = -> { span "Hello, world" }
@@ -241,11 +272,11 @@ Papercraft.html {
 ## 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 component composition and the
-creation of higher-order components.
+using `#apply`. This mechanism is what allows template composition and the
+creation of higher-order templates.
-The `#apply` method returns a new component which applies the given parameters and
-or block to the original component:
+The `#apply` method returns a new template which applies the given parameters and
+or block to the original template:
 ```ruby
 # parameter application
@@ -258,19 +289,19 @@ div_wrap = Papercraft.html { div { emit_yield } }
 wrapped_h1 = div_wrap.apply { h1 'hi' }
 wrapped_h1.render #=> "<div><h1>hi</h1></div>"
-# wrap a component
+# wrap a template
 wrapped_hello_world = div_wrap.apply(&hello_world)
 wrapped_hello_world.render #=> "<div><h1>Hello, world!</h1></div>"
 ```
-## Higher-order components
+## Higher-order templates
-Papercraft also lets you create higher-order components (HOCs), that is,
-components that take other components as parameters, or as blocks. Higher-order
-components are handy for creating layouts, wrapping components in arbitrary
-markup, enhancing components or injecting component parameters.
+Papercraft also lets you create higher-order templates, that is,
+templates that take other templates as parameters, or as blocks. Higher-order
+templates are handy for creating layouts, wrapping templates in arbitrary
+markup, enhancing templates or injecting template parameters.
-Here is a HOC that takes a component as parameter:
+Here is a higher-order template that takes a template as parameter:
 ```ruby
 div_wrap = Papercraft.html { |inner| div { emit inner } }
@@ -279,7 +310,7 @@ wrapped_greeter = div_wrap.apply(greeter)
 wrapped_greeter.render #=> "<div><h1>hi</h1></div>"
 ```
-The inner component can also be passed as a block, as shown above:
+The inner template can also be passed as a block, as shown above:
 ```ruby
 div_wrap = Papercraft.html { div { emit_yield } }
@@ -289,7 +320,7 @@ wrapped_greeter.render #=> "<div><h1>hi</h1></div>"
 ## Layout template composition
-One of the principal uses of higher-order components is the creation of nested
+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
 like to avoid having to repeat the same code in the different layouts. We can do
 this by creating a `default` page template that takes a block, then use `#apply`
@@ -384,11 +415,27 @@ The deafult options can be configured by accessing
 Papercraft.default_kramdown_options[:auto_ids] = false
 ```
+## 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
+MIME type can be set when creating the template, e.g. `Papercraft.xml(mime_type:
+'application/rss+xml')`. You can interrogate the template's MIME type using
+`#mime_type`:
+```ruby
+# using Qeweney (https://github.com/digital-fabric/qeweney)
+def serve_template(req, template)
+  body = template.render
+  respond(body, 'Content-Type' => template.mime_type)
+end
+```
 ## 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
+the last moment, thus allowing an inner template to manipulate the state of the
+outer template. 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.
@@ -397,11 +444,11 @@ 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
+- Using templates 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
+class that can collect JS and CSS dependencies from the different templates
 integrated into the page, and adds them to the page's `<head>` element:
 ```ruby
@@ -502,11 +549,47 @@ Papercraft.html {
 }
 ```
-## JSON templating
-You can create a JSON template using the same API used for HTML and XML
-templating. The only difference is that for adding array items you'll need to
-use the `#item` method:
+## 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
+specific HTML functionality, such as emitting Markdown.
+Here's an example showing how to create an RSS feed:
+```ruby
+rss = Papercraft.xml(mime_type: 'text/xml; charset=utf-8') { |resource:, **props|
+  rss(version: '2.0', 'xmlns:atom' => 'http://www.w3.org/2005/Atom') {
+    channel {
+      title 'Noteflakes'
+      link 'https://noteflakes.com/'
+      description 'A website by Sharon Rosner'
+      language 'en-us'
+      pubDate Time.now.httpdate
+      emit '<atom:link href="https://noteflakes.com/feeds/rss" rel="self" type="application/rss+xml" />'
+      article_entries = resource.page_list('/articles').reverse
+      article_entries.each { |e|
+        item {
+          title e[:title]
+          link "https://noteflakes.com#{e[:url]}"
+          guid "https://noteflakes.com#{e[:url]}"
+          pubDate e[:date].to_time.httpdate
+          description e[:html_content]
+        }
+      }
+    }
+  }
+}
+```
+## 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:
 ```ruby
 Papercraft.json {
@@ -531,7 +614,8 @@ Papercraft.json {
 }.render #=> "{\"foo\":{\"bar\":[null,true,123.456]}}"
 ```
-Papercraft uses the [JSON gem](https://rubyapi.org/3.1/o/json) under the hood.
+Papercraft uses the [JSON gem](https://rubyapi.org/3.1/o/json) under the hood in
+order to generate actual JSON.
 ## API Reference

data/lib/papercraft/extension_proxy.rb CHANGED Viewed

@@ -10,6 +10,7 @@ module Papercraft
   class ExtensionProxy
     # Initializes a new ExtensionProxy.
+    #
     # @param renderer [Papercraft::Renderer] renderer to proxy to
     # @param mod [Module] extension module
     # @return [void]
@@ -18,7 +19,8 @@ module Papercraft
       extend(mod)
     end
-    # Proxies missing methods to the renderer
+    # Proxies missing methods to the renderer.
+    #
     # @param sym [Symbol] method name
     # @param *args [Array] arguments
     # @param &block [Proc] block

data/lib/papercraft/html.rb CHANGED Viewed

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
+require_relative './tags'
 module Papercraft
   # HTML Markup extensions
   module HTML
+    include Tags
     # Emits the p tag (overrides Object#p)
     #
     # @param text [String] text content of tag
@@ -81,5 +85,33 @@ module Papercraft
     def emit_markdown(markdown, **opts)
       emit Papercraft.markdown(markdown, **opts)
     end
+    private
+    # Escapes the given text using HTML entities.
+    #
+    # @param text [String] text
+    # @return [String] escaped text
+    def escape_text(text)
+      EscapeUtils.escape_html(text.to_s)
+    end
+    # Converts a tag to its string representation. Underscores will be converted
+    # to dashes.
+    #
+    # @param tag [Symbol, String] tag
+    # @return [String] tag string
+    def tag_repr(tag)
+      tag.to_s.tr('_', '-')
+    end
+    # Converts an attribute to its string representation. Underscores will be
+    # converted to dashes.
+    #
+    # @param att [Symbol, String] attribute
+    # @return [String] attribute string
+    def att_repr(att)
+      att.to_s.tr('_', '-')
+    end
   end
 end

data/lib/papercraft/json.rb CHANGED Viewed

@@ -5,69 +5,122 @@ require 'json'
 module Papercraft
   # JSON renderer extensions
   module JSON
-    def object_stack
-      @object_stack ||= [nil]
+    # Initializes a JSON renderer, setting up an object stack.
+    def initialize(&template)
+      @object_stack = [nil]
+      super
     end
+    # Adds an array item to the current object target. If a block is given, the
+    # block is evaulated against a new object target, then added to the current
+    # array.
+    #
+    # @param value [Object] item
+    # @param &block [Proc] template block
+    # @return [void]
+    def item(value = nil, &block)
+      verify_array_target
+      if block
+        value = enter_object(&block)
+      end
+      push_array_item(value)
+    end
+    # Adds a key-value item to the current object target. If a block is given,
+    # the block is evaulated against a new object target, then used as the
+    # value.
+    #
+    # @param key [Object] key
+    # @param value [Object] value
+    # @param &block [Proc] template block
+    # @return [void]
+    def kv(key, value = nil, &block)
+      verify_hash_target
+      if block
+        value = enter_object(&block)
+      end
+      push_kv_item(key, value)
+    end
+    # Intercepts method calls by adding key-value pairs to the current object
+    # target.
+    #
+    # @param key [Object] key
+    # @param value [Object] value
+    # @param &block [Proc] template block
+    # @return [void]
+    def method_missing(sym, value = nil, &block)
+      kv(sym, value, &block)
+    end
+    # Converts the root object target to JSON.
+    #
+    # @return [String] JSON template result
+    def to_s
+      @object_stack[0].to_json
+    end
+    private
+    # 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
+      @object_stack << nil
       instance_eval(&block)
     end
+    # Verifies that the current object target is not a hash.
+    #
+    # @return [bool]
     def verify_array_target
-      case object_stack[-1]
+      case @object_stack[-1]
       when nil
-        object_stack[-1] = []
+        @object_stack[-1] = []
       when Hash
         raise "Mixing array and hash values"
       end
     end
+    # Verifies that the current object target is not an array.
+    #
+    # @return [bool]
     def verify_hash_target
-      case object_stack[-1]
+      case @object_stack[-1]
       when nil
-        object_stack[-1] = {}
+        @object_stack[-1] = {}
       when Array
         raise "Mixing array and hash values"
       end
     end
+    # Pushes an array item to the current object target.
+    #
+    # @param value [Object] item
+    # @return [void]
     def push_array_item(value)
-      object_stack[-1] << value
+      @object_stack[-1] << value
     end
+    # Pushes a key value into the current object target.
+    #
+    # @param key [Object] key
+    # @param value [Object] value
+    # @return [void]
     def push_kv_item(key, value)
-      object_stack[-1][key] = value
+      @object_stack[-1][key] = value
     end
+    # 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
+      @object_stack << nil
       instance_eval(&block)
-      object_stack.pop
-    end
-    def item(value = nil, &block)
-      verify_array_target
-      if block
-        value = enter_object(&block)
-      end
-      push_array_item(value)
-    end
-    def kv(key, value, &block)
-      verify_hash_target
-      if block
-        value = enter_object(&block)
-      end
-      push_kv_item(key, value)
-    end
-    def method_missing(sym, value = nil, &block)
-      kv(sym, value, &block)
-    end
-    def to_s
-      object_stack[0].to_json
-    end
+      @object_stack.pop
+    end
   end
 end