feat: Add envelope(&) method (#36)

stephannv · Apr 7, 2023 · f84f642 · f84f642
1 parent b25af7f
commit f84f642
Show file tree

Hide file tree

Showing 4 changed files with 96 additions and 3 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,7 +7,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ## [Unreleased]
 
 ### Added
-- Allow conditional rendering (#26)
+- Allow conditional rendering
+- Handles array attributes
+- Adds `#envelope(&)` method
 
 ### Changed
 - Requires `require "blueprint/html"` to use `Blueprint::HTML` module

diff --git a/README.md b/README.md
@@ -37,6 +37,7 @@ Output:
   * [Passing content](#passing-content)
   * [Composing components](#composing-components)
   * [Conditional rendering](#conditional-rendering)
+  * [Enveloping](#enveloping)
   * [NamedTuple attributes](#namedtuple-attributes)
   * [Boolean attributes](#boolean-attributes)
   * [Array attributes](#array-attributes)
@@ -390,6 +391,53 @@ Output:
 <h1>Hello Blueprint</h1>
 ```
 
+### Enveloping
+
+By overriding the `#envelope(&)` method, you can create a wrapper around blueprint content. This is useful when defining layouts for pages, for example.
+
+```crystal
+class MainLayout
+  include Blueprint::HTML
+
+  private def blueprint(&)
+    html do
+      body do
+        yield
+      end
+    end
+  end
+end
+
+class BasePage
+  include Blueprint::HTML
+
+  private def envelope(&)
+    render(MainLayout.new) do
+      yield
+    end
+  end
+end
+
+class HomePage < BasePage
+  private def blueprint
+    h1 { "Home" }
+  end
+end
+
+page = HomePage.new
+puts page.to_html
+```
+
+Output:
+
+```html
+<html>
+  <body>
+    <h1>Home</h1>
+  </body>
+</html>
+```
+
 ### NamedTuple attributes
 
 If you pass a NamedTuple attribute to some element, it will be flattened with a dash between each level. This is useful for `data-*` and `aria-*` attributes.

diff --git a/spec/blueprint/html/enveloping_spec.cr b/spec/blueprint/html/enveloping_spec.cr
@@ -0,0 +1,35 @@
+private class MainLayout
+  include Blueprint::HTML
+
+  private def blueprint(&)
+    html do
+      body do
+        yield
+      end
+    end
+  end
+end
+
+private class BasePage
+  include Blueprint::HTML
+
+  private def envelope(&)
+    render(MainLayout.new) do
+      yield
+    end
+  end
+end
+
+private class IndexPage < BasePage
+  private def blueprint
+    h1 { "Home" }
+  end
+end
+
+describe "Blueprint::HTML enveloping" do
+  it "allows defining a blueprint wrapper" do
+    page = IndexPage.new
+
+    page.to_html.should eq "<html><body><h1>Home</h1></body></html>"
+  end
+end
diff --git a/src/blueprint/html.cr b/src/blueprint/html.cr
@@ -13,18 +13,26 @@ module Blueprint::HTML
   def to_html : String
     return "" unless render?
 
-    blueprint
+    envelope { blueprint }
+
     @buffer.to_s
   end
 
   def to_html(&) : String
     return "" unless render?
 
-    blueprint { capture_content { yield } }
+    envelope do
+      blueprint { capture_content { yield } }
+    end
+
     @buffer.to_s
   end
 
   private def render? : Bool
     true
   end
+
+  private def envelope(&) : Nil
+    yield
+  end
 end