papercraft 0.24 → 0.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f90c4ea6ac9d3090ae45d79f7f4a58668ccf7f8ae5d4dfa2a727b44a82699eb9
-  data.tar.gz: 10ff5bc3df10c10b0a968921517d2e0c18a61973dd97b88e95eef38670b9e451
+  metadata.gz: 2b64cff374a2d8fdf50de978d3a4b0ceb6fb939741c00ed7cf63154af7cf6732
+  data.tar.gz: 67c0fc2aa65a1056f04c378ebe50a0a433bb1cabba75a1fbd522d60604ddcd1d
 SHA512:
-  metadata.gz: '02461962ba174678a5b4a6ec550a8faa2f643fe87234e41513f7b49d798e3f3b2ade02adcfb0fa4961124a74484ddddea9437cb02eec98e9e897721729c0ef63'
-  data.tar.gz: f99728bb218382a040f67cbf2fd9652c33b3e0648efefbc695ceee708006758b6ec249748f3e3d41b065bf3b2fb28014b1ae61e02f7d3b01231e928f028e6ebd
+  metadata.gz: 690eaec575b4ad635fc913609197d166841536811b1e1d4314d763c6c37fb520b9fc8f2f19d50f4a0cfd242a98b69d59aebf16eaa16f4298bfc74ac0040b516a
+  data.tar.gz: 66a468eeee29e5c2b9b9e7a2f3adc605fa2f9648ade7a0aa444a798d896de3eb8c5aa02c2e79bf27780769f86d2b1960b8a111be1d8ed6604af739cab5931adb

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.26 2023-01-13
+
+- Add support for namespaced local extensions using `#extend`
+
+## 0.25 2023-01-12
+
+- Implement `#def_tag` for defining custom tags inline
+
 ## 0.24 2022-03-19
 
 - Fix usage of const components (#13)

data/README.md

@@ -86,6 +86,8 @@ hello.render('world')
 - [XML Templates](#xml-templates)
 - [JSON Templates](#json-templates)
 - [Papercraft Extensions](#papercraft-extensions)
+  - [Extending Specific Templates](#extending-specific-templates)
+  - [Inline Helper Methods](#inline-helper-methods)
   - [Bundled Extensions](#bundled-extensions)
 - [API Reference](#api-reference)
 
@@ -681,7 +683,91 @@ Papercraft.html {
 }
 ```
 
-## Bundled Extensions
+### Extending Specific Templates
+
+Sometimes you wish to extend a specific template locally, without the extension
+API being available to other templates. To do this you can use `#extend`:
+
+```ruby
+module CustomTags
+  def label(text)
+    span text, class: 'label'
+  end
+end
+
+Papercraft.html {
+  extend CustomTags
+
+  label 'foo'
+}
+```
+
+The extension is in effect as long as the template is processing, so it is also
+accessible to any sub templates that are emitted.
+
+Local extensions can also be namespaced by passing `#extend` a hash mapping
+namespaces to modules:
+
+```ruby
+Papercraft.html {
+  extend custom: CustomTags
+
+  custom.label 'foo'
+}
+```
+
+### 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.
 All bundled extensions are namespaced under `Papercraft::Extensions`, and must
@@ -690,7 +776,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).
 

data/lib/papercraft/tags.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative './extension_proxy'
+
 module Papercraft  
   # Markup (HTML/XML) extensions
   module Tags
@@ -180,6 +182,66 @@ 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
+
+    alias_method :orig_extend, :extend
+
+    # Extends the template with the provided module or map of modules. When
+    # given a module, the template body will be extended with the module,
+    # and will have access to all the module's methods:
+    #
+    #   module CustomTags
+    #     def label(text)
+    #       span text, class: 'label'
+    #     end
+    #   end
+    #
+    #   Papercraft.html {
+    #     extend CustomTags
+    #     label('foo')
+    #   }
+    #
+    # When given a hash, each module in the hash is namespaced, and can be
+    # accessed using its key:
+    #
+    #   Papercraft.html {
+    #     extend custom: CustomTags
+    #     custom.label('foo')
+    #   }
+    #
+    # @param ext [Module, Hash] extension module or hash mapping symbols to modules
+    # @return [Object] self
+    def extend(ext)
+      if ext.is_a?(Module)
+        orig_extend(ext)
+      else
+        ext.each do |sym, mod|
+          define_extension_method(sym, mod)
+        end
+      end
+    end
+
     private
 
     # Defines a method that emits the given tag based on a constant. The
@@ -209,6 +271,17 @@ module Papercraft
       self.class.class_eval(code, __FILE__, S_TAG_METHOD_LINE)
     end
 
+    # Defines a namespace referring to the given module.
+    #
+    # @param sym [Symbol] namespace
+    # @param mod [Module] module
+    # @return [void]
+    def define_extension_method(sym, mod)
+      self.singleton_class.define_method(sym) do
+        (@extension_proxies ||= {})[mod] ||= ExtensionProxy.new(self, mod)
+      end
+    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`.
     #

data/lib/papercraft/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '0.24'
+  version: '0.26'
 platform: ruby
 authors:
 - Sharon Rosner
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-03-19 00:00:00.000000000 Z
+date: 2023-01-13 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: []