papercraft 0.18 → 0.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a887e5946cfe19b6874046cb4ef173a1de4deb11509ea4c7dca5c6434e0d710d
-  data.tar.gz: 3bdd374b54c72dac9f8137f5878cd43f0415c84eadebfef50fc90eb30029bf3b
+  metadata.gz: 729c7b1cf7482cb761b005fba8da8ae4c1325559daee15fedd2d695de21ee08d
+  data.tar.gz: 0546c527a6a9ac0570c9bd6057101b31591eba1f1ee549c272d9bda13a9f7a04
 SHA512:
-  metadata.gz: 8d4a911c94bb39ab8da06e3f61a965a7db13725b143a2cf38feae44cbb1ac0ae0a8d79b899008a14c87d890ba5ebff61fb3616b5a2014bd84049da8af95a9029
-  data.tar.gz: fe798bfc67006d21e6bc62cfa32d50141720f44d0089d9da58b7b7406b8d1386e8f77d10f4a34863dad05968e0342acd9d94be68afeca98955189853b367a8e0
+  metadata.gz: fdaa8d2f254744694ea3624f39871f4b411294a990f6e1bb4c57f56bf36049031b9403820cbadaa57ef6ac3e9021b6afa53da22588462450a6ca0863b6b88184
+  data.tar.gz: 4ea21235970af0cdef9ce09cd790742a94632e4f1f02d4a3d90a3e857741ec41952a53fe59b24016c00894dde7131dbbbc79d7616564f159f5646acf24f469f9

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+## 0.22 2022-02-14
+
+- Fix behaviour of call to `#p` in an extension (#10)
+
+## 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

data/README.md

@@ -64,13 +64,14 @@ hello.render('world')
 - [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 components](#higher-order-components)
+- [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)
@@ -154,6 +155,43 @@ 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
+
+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
+characters in tag and attribute names. However, in order to best adhere to the
+HTML and XML specs and common practices, tag names and attributes will be
+formatted according to the following rules, depending on the template type:
+
+- HTML: underscores are converted to dashes:
+
+  ```ruby
+  Papercraft.html {
+    foo_bar { p 'Hello', data_name: 'world' }
+  }.render #=> '<foo-bar><p data-name="world">Hello</p></foo-bar>'
+  ```
+
+- XML: underscores are converted to dashes, double underscores are converted to
+  colons:
+
+  ```ruby
+  Papercraft.xml {
+    soap__Envelope(
+      xmlns__soap:  'http://schemas.xmlsoap.org/soap/envelope/',
+    ) { }
+  }.render #=> '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Envelope>'
+  ```
+
+If you need more precise control over tag names, you can use the `#tag` method,
+which takes the tag name as its first parameter, then the rest of the parameters
+normally used for tags:
+
+```ruby
+Papercraft.html {
+  tag 'cra_zy__:!tag', 'foo'
+}.render #=> '<cra_zy__:!tag>foo</cra_zy__:!tag>'
+```
+
 ## Template parameters
 
 In Papercraft, parameters are always passed explicitly. This means that template
@@ -221,8 +259,8 @@ Papercraft.html(&greeting).render('world')
 
 ## 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
@@ -250,14 +288,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" }
@@ -272,11 +310,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
@@ -289,19 +327,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 } }
@@ -310,7 +348,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 } }
@@ -320,7 +358,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`
@@ -434,8 +472,8 @@ 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.
@@ -444,11 +482,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
@@ -513,21 +551,27 @@ and other associated methods:
 
 ```ruby
 module BootstrapComponents
-  ...
-
-  def card(**props)
+  def card(**props, &block)
     div(class: 'card', **props) {
-      div(class: 'card-body') {
-        emit_yield
-      }
+      div(class: 'card-body', &block)
     }
   end
-
+  
   def card_title(title)
-    h5 title, class: 'card-title'
+    h4(title, class: 'card-title')
+  end
+
+  def card_subtitle(subtitle)
+    h5(subtitle, class: 'card-subtitle')
   end
 
-  ...
+  def card_text(text)
+    p(text, class: 'card-text')
+  end
+
+  def card_link(text, **opts)
+    a(text, class: 'card-link', **opts)
+  end
 end
 
 Papercraft.extension(bootstrap: BootstrapComponents)
@@ -543,14 +587,12 @@ Papercraft.html {
     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'
+    bootstrap.card_link 'Card link', href: '#foo'
+    bootstrap.card_link 'Another link', href: '#bar'
   }
 }
 ```
 
-
-
 ## XML templates
 
 XML templates behave largely the same as HTML templates, with a few minor

data/lib/papercraft/extension_proxy.rb

@@ -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,13 +19,25 @@ 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 *props [Array] named arguments
     # @param &block [Proc] block
     # @return void
-    def method_missing(sym, *args, &block)
-      @renderer.send(sym, *args, &block)
+    def method_missing(sym, *args, **props, &block)
+      @renderer.send(sym, *args, **props, &block)
+    end
+
+    # Overrides the `Kernel#p` method to emit a p tag.
+    #
+    # @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)
     end
   end
 end

data/lib/papercraft/html.rb

@@ -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

@@ -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