papercraft 0.9 → 0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1f7aa5872a78830c1a5662f055639ae2012b5b9d0f029640dce041f58d1ef4e
-  data.tar.gz: 0c5acc8b14254c63db2132caab42ce003a8ae4713ae6daea7225d0390a420219
+  metadata.gz: a7d34aa76efd449fc6a63182195e8353886887e13963b79439a19dc3b0f9a9d2
+  data.tar.gz: e199245d969426b75627401b7c57fe1a01e7121a656ece8cd97b004a22b3ab2e
 SHA512:
-  metadata.gz: 02bf1f7bc1300f4fa7871a6942c6a2eae2dd2f8202c7f3cc354171806f82e8a68262c3ca5e2232b7b6dcf6788a33b134b5811641561fa5baba3b7c342643b082
-  data.tar.gz: 97a68a0f854f631a6a36b52a350faae4b1da1e337b27701209c6eec9dc16c62856555fdff3ab3d8f33e144e7fed8dc892b22433f38dd3f951a04010f710b63c4
+  metadata.gz: 75d5dd94c26d1ee15b11f8a439ff1c26cd7336c60ce609e334f3c0e823e8813f67923b79e8f023e9d1bcc3f2af20b5fffc93196ba5731d1cea42b2e0f75f3102
+  data.tar.gz: 7bdcbfa67dabec451c00f006256b16b9875d60fc726d295135db5de94a5b8854e3bdf648410d6ef6e7a7b76766c6c07d21ebb4da9788cab45fcb67a8c9d6b221

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.10 2021-12-25
+
+- Add support for extensions
+
 ## 0.9 2021-12-23
 
 - Add support for emitting Markdown

data/README.md

@@ -1,8 +1,26 @@
-# Papercraft - Composable HTML templating for Ruby
+<h1 align="center">
+  Papercraft
+</h1>
+
+<h4 align="center">Composable HTML templating for Ruby</h4>
+
+<p align="center">
+  <a href="http://rubygems.org/gems/papercraft">
+    <img src="https://badge.fury.io/rb/papercraft.svg" alt="Ruby gem">
+  </a>
+  <a href="https://github.com/digital-fabric/papercraft/actions?query=workflow%3ATests">
+    <img src="https://github.com/digital-fabric/papercraft/workflows/Tests/badge.svg" alt="Tests">
+  </a>
+  <a href="https://github.com/digital-fabric/papercraft/blob/master/LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://www.rubydoc.info/gems/papercraft">API reference</a>
+</p>
 
-[INSTALL](#installing-papercraft) |
-[TUTORIAL](#getting-started) |
-[DOCS](https://www.rubydoc.info/gems/papercraft)
+# Papercraft - Composable HTML templating for Ruby
 
 ## What is Papercraft?
 
@@ -32,9 +50,7 @@ features:
 - Explicit parameter passing to nested components
 - Higher order components
 - Built-in support for rendering [Markdown](#emitting-markdown)
-
-With Papercraft you can structure your templates as nested HTML components, in a
-somewhat similar fashion to React.
+- Support for namespaced extensions
 
 ## Installing Papercraft
 
@@ -52,43 +68,25 @@ $ gem install papercraft
 
 ## Getting started
 
-To use Papercraft in your code just require it:
+To create a template use the global method `Kernel#H`:
 
 ```ruby
 require 'papercraft'
-```
-
-To create a template use `Papercraft::Component.new` or the global method
-`Kernel#H`:
 
-```ruby
-# can also use Papercraft.new
 html = H {
-  div { p 'hello' }
+  div(id: 'greeter') { p 'Hello!' }
 }
 ```
 
-## Rendering a template
-
-To render a Papercraft template use the `#render` method:
-
-```ruby
-H { span 'best span' }.render  #=> "<span>best span</span>"
-```
-
-The render method accepts an arbitrary context variable:
+Rendering a template is done using `#render`:
 
 ```ruby
-html = H {
-  h1 context[:title]
-}
-
-html.render(title: 'My title') #=> "<h1>My title</h1>"
+html.render #=> "<div id="greeter"><p>Hello!</p></div>"
 ```
 
 ## All about tags
 
-Tags are added using unqualified method calls, and are nested using blocks:
+Tags are added using unqualified method calls, and can be nested using blocks:
 
 ```ruby
 H {
@@ -376,7 +374,73 @@ The deafult options can be configured by accessing
 Papercraft::HTML.kramdown_options[:auto_ids] = false
 ```
 
-## Documentation
+## 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`.
+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/).
+
+For example, to create a Bootstrap card component, the following HTML markup is
+needed (example taken from the [Bootstrap
+docs](https://getbootstrap.com/docs/5.1/components/card/#titles-text-and-links)):
+
+```html
+<div class="card" style="width: 18rem;">
+  <div class="card-body">
+    <h5 class="card-title">Card title</h5>
+    <h6 class="card-subtitle mb-2 text-muted">Card subtitle</h6>
+    <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p>
+    <a href="#" class="card-link">Card link</a>
+    <a href="#" class="card-link">Another link</a>
+  </div>
+</div>
+```
+
+With Papercraft, we could create a `Bootstrap` extension with a `#card` method
+and other associated methods:
+
+```ruby
+module BootstrapComponents
+  ...
+
+  def card(**props)
+    div(class: 'card', **props) {
+      div(class: 'card-body') {
+        emit_yield
+      }
+    }
+  end
+
+  def card_title(title)
+    h5 title, class: 'card-title'
+  end
+
+  ...
+end
+
+Papercraft.extension(bootstrap: BootstrapComponents)
+```
+
+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:
+
+```ruby
+H {
+  bootstrap.card(style: 'width: 18rem') {
+    bootstrap.card_title 'Card title'
+    bootstrap.card_subtitle 'Card subtitle'
+    bootstrap.card_text 'Some quick example text to build on the card title and make up the bulk of the card''s content.'
+    bootstrap.card_link '#', 'Card link'
+    bootstrap.card_link '#', 'Another link'
+  }
+}
+```
+
+## API Reference
 
-The complete documentation for this library can be found
+The API reference for this library can be found
 [here](https://www.rubydoc.info/gems/papercraft).

data/lib/papercraft/extension_proxy.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Papercraft
+  
+  # An ExtensionProxy proxies method calls to a renderer. Extension proxies are
+  # used to provide an namespaced interface to Papercraft extensions. When an
+  # extension is installed using `Papercraft.extension`, a corresponding method
+  # is defined on the `Papercraft::Renderer` class that creates an extension
+  # proxy that gives access to the different extension methods.
+  class ExtensionProxy
+
+    # Initializes a new ExtensionProxy.
+    # @param renderer [Papercraft::Renderer] renderer to proxy to
+    # @param mod [Module] extension module
+    # @return [void]
+    def initialize(renderer, mod)
+      @renderer = renderer
+      extend(mod)
+    end
+  
+    # Proxies missing methods to the renderer
+    # @param sym [Symbol] method name
+    # @param *args [Array] arguments
+    # @param &block [Proc] block
+    # @return void
+    def method_missing(sym, *args, &block)
+      @renderer.send(sym, *args, &block)
+    end
+  end
+end

data/lib/papercraft/renderer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative './html'
+require_relative './extension_proxy'
 
 module Papercraft
   
@@ -31,7 +32,29 @@ module Papercraft
         if param_count > args.size
           raise Papercraft::Error, "Missing template parameters"
         end
-      end  
+      end
+
+      # Installs the given extensions, mapping a method name to the extension
+      # module.
+      # @param map [Hash] hash mapping methods to extension modules
+      # @return [void]
+      def extension(map)
+        map.each do |sym, mod|
+          define_extension_method(sym, mod)
+        end
+      end
+
+      private
+
+      # Defines a method returning an extension proxy for the given module
+      # @param sym [Symbol] method name
+      # @param mod [Module] extension module
+      # @return [void]
+      def define_extension_method(sym, mod)
+        define_method(sym) do
+          (@extension_proxies ||= {})[mod] ||= ExtensionProxy.new(self, mod)
+        end
+      end
     end
 
     # Initializes the renderer and evaulates the given template in the
@@ -83,9 +106,6 @@ module Papercraft
     # @param &block [Proc] block passed to method
     # @return [void]
     def method_missing(sym, *args, **opts, &block)
-      value = @local && @local[sym]
-      return value if value
-
       tag = sym.to_s
       code = S_TAG_METHOD % { tag: tag, TAG: tag.upcase }
       self.class.class_eval(code, __FILE__, S_TAG_METHOD_LINE)
@@ -200,6 +220,7 @@ module Papercraft
 
     private
 
+    # Escapes the given text using HTML entities.
     def escape_text(text)
       EscapeUtils.escape_html(text.to_s)
     end
@@ -209,6 +230,7 @@ module Papercraft
   class XMLRenderer < Renderer
     private
 
+    # Escapes the given text using XML entities.
     def escape_text(text)
       EscapeUtils.escape_xml(text.to_s)
     end

data/lib/papercraft/version.rb

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

data/lib/papercraft.rb

@@ -11,6 +11,14 @@ require_relative 'papercraft/encoding'
 module Papercraft
   # Exception class used to signal templating-related errors
   class Error < RuntimeError; end
+
+  # Installs one or more extensions. Extensions enhance templating capabilities
+  # 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.
+  def self.extension(map)
+    Renderer.extension(map)
+  end
 end
 
 # Kernel extensions

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '0.9'
+  version: '0.10'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-12-23 00:00:00.000000000 Z
+date: 2021-12-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: escape_utils
@@ -135,6 +135,7 @@ files:
 - lib/papercraft/compiler.rb
 - lib/papercraft/component.rb
 - lib/papercraft/encoding.rb
+- lib/papercraft/extension_proxy.rb
 - lib/papercraft/html.rb
 - lib/papercraft/renderer.rb
 - lib/papercraft/version.rb