papercraft 0.17 → 0.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +6 -0
- data/README.md +113 -29
- data/lib/papercraft/renderer.rb +2 -1
- data/lib/papercraft/version.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: a887e5946cfe19b6874046cb4ef173a1de4deb11509ea4c7dca5c6434e0d710d
|
|
4
|
+
data.tar.gz: 3bdd374b54c72dac9f8137f5878cd43f0415c84eadebfef50fc90eb30029bf3b
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 8d4a911c94bb39ab8da06e3f61a965a7db13725b143a2cf38feae44cbb1ac0ae0a8d79b899008a14c87d890ba5ebff61fb3616b5a2014bd84049da8af95a9029
|
|
7
|
+
data.tar.gz: fe798bfc67006d21e6bc62cfa32d50141720f44d0089d9da58b7b7406b8d1386e8f77d10f4a34863dad05968e0342acd9d94be68afeca98955189853b367a8e0
|
data/CHANGELOG.md
CHANGED
data/README.md
CHANGED
|
@@ -24,35 +24,63 @@
|
|
|
24
24
|
|
|
25
25
|
## What is Papercraft?
|
|
26
26
|
|
|
27
|
+
Papercraft is a templating engine for dynamically producing HTML, XML or JSON.
|
|
28
|
+
Papercraft templates are expressed in plain Ruby, leading to easier debugging,
|
|
29
|
+
better protection against HTML/XML injection attacks, and better code reuse.
|
|
30
|
+
|
|
31
|
+
Papercraft templates can be composed in a variety of ways, facilitating the
|
|
32
|
+
usage of layout templates, and enabling a component-oriented approach to
|
|
33
|
+
building complex web interfaces.
|
|
34
|
+
|
|
35
|
+
In Papercraft, dynamic data is passed explicitly to the template as block
|
|
36
|
+
arguments, making the data flow easy to follow and understand. Papercraft also
|
|
37
|
+
lets developers create derivative templates using full or partial parameter
|
|
38
|
+
application.
|
|
39
|
+
|
|
40
|
+
Papercraft includes built-in support for rendering Markdown (using
|
|
41
|
+
[Kramdown](https://github.com/gettalong/kramdown/)), as well as support for
|
|
42
|
+
creating template extensions in order to allow the creation of component
|
|
43
|
+
libraries.
|
|
44
|
+
|
|
27
45
|
```ruby
|
|
28
46
|
require 'papercraft'
|
|
29
47
|
|
|
30
48
|
page = Papercraft.html { |*args|
|
|
31
49
|
html {
|
|
32
|
-
head { }
|
|
50
|
+
head { title 'Title' }
|
|
33
51
|
body { emit_yield *args }
|
|
34
52
|
}
|
|
35
53
|
}
|
|
36
54
|
page.render { p 'foo' }
|
|
37
|
-
#=> "<html><head
|
|
55
|
+
#=> "<html><head><title>Title</title></head><body><p>foo</p></body></html>"
|
|
38
56
|
|
|
39
57
|
hello = page.apply { |name| h1 "Hello, #{name}!" }
|
|
40
58
|
hello.render('world')
|
|
41
|
-
#=> "<html><head
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
-
|
|
47
|
-
-
|
|
48
|
-
-
|
|
49
|
-
-
|
|
50
|
-
-
|
|
51
|
-
-
|
|
52
|
-
-
|
|
53
|
-
-
|
|
54
|
-
-
|
|
55
|
-
-
|
|
59
|
+
#=> "<html><head><title>Title</title></head><body><h1>Hello, world!</h1></body></html>"
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Table of content
|
|
63
|
+
|
|
64
|
+
- [Installing papercraft](#installing-papercraft)
|
|
65
|
+
- [Basic usage](#basic-usage)
|
|
66
|
+
- [Adding tags](#adding-tags)
|
|
67
|
+
- [Template parameters](#template-parameters)
|
|
68
|
+
- [Template logic](#template-logic)
|
|
69
|
+
- [Template blocks](#template-blocks)
|
|
70
|
+
- [Plain procs as templates](#plain-procs-as-templates)
|
|
71
|
+
- [Template composition](#template-composition)
|
|
72
|
+
- [Parameter and block application](#parameter-and-block-application)
|
|
73
|
+
- [Higher-order components](#higher-order-components)
|
|
74
|
+
- [Layout template composition](#layout-template-composition)
|
|
75
|
+
- [Emitting raw HTML](#emitting-raw-html)
|
|
76
|
+
- [Emitting a string with HTML Encoding](#emitting-a-string-with-html-encoding)
|
|
77
|
+
- [Emitting Markdown](#emitting-markdown)
|
|
78
|
+
- [Working with MIME types](#working-with-mime-types)
|
|
79
|
+
- [Deferred evaluation](#deferred-evaluation)
|
|
80
|
+
- [Papercraft extensions](#papercraft-extensions)
|
|
81
|
+
- [XML templates](#xml-templates)
|
|
82
|
+
- [JSON templates](#json-templates)
|
|
83
|
+
- [API Reference](#api-reference)
|
|
56
84
|
|
|
57
85
|
## Installing Papercraft
|
|
58
86
|
|
|
@@ -68,9 +96,9 @@ Or manually:
|
|
|
68
96
|
$ gem install papercraft
|
|
69
97
|
```
|
|
70
98
|
|
|
71
|
-
##
|
|
99
|
+
## Basic usage
|
|
72
100
|
|
|
73
|
-
To create
|
|
101
|
+
To create an HTML template use `Papercraft.html`:
|
|
74
102
|
|
|
75
103
|
```ruby
|
|
76
104
|
require 'papercraft'
|
|
@@ -80,13 +108,16 @@ html = Papercraft.html {
|
|
|
80
108
|
}
|
|
81
109
|
```
|
|
82
110
|
|
|
111
|
+
(You can also use `Papercraft.xml` and `Papercraft.json` to create XML and JSON
|
|
112
|
+
templates, respectively.)
|
|
113
|
+
|
|
83
114
|
Rendering a template is done using `#render`:
|
|
84
115
|
|
|
85
116
|
```ruby
|
|
86
117
|
html.render #=> "<div id="greeter"><p>Hello!</p></div>"
|
|
87
118
|
```
|
|
88
119
|
|
|
89
|
-
##
|
|
120
|
+
## Adding tags
|
|
90
121
|
|
|
91
122
|
Tags are added using unqualified method calls, and can be nested using blocks:
|
|
92
123
|
|
|
@@ -141,7 +172,7 @@ greeting = Papercraft.html { |name:| h1 "Hello, #{name}!" }
|
|
|
141
172
|
greeting.render(name: 'world') #=> "<h1>Hello, world!</h1>"
|
|
142
173
|
```
|
|
143
174
|
|
|
144
|
-
##
|
|
175
|
+
## Template logic
|
|
145
176
|
|
|
146
177
|
Since Papercraft templates are just a bunch of Ruby, you can easily write your
|
|
147
178
|
view logic right in the template:
|
|
@@ -171,10 +202,10 @@ page = Papercraft.html {
|
|
|
171
202
|
page.render { h1 'hi' }
|
|
172
203
|
```
|
|
173
204
|
|
|
174
|
-
## Plain procs as
|
|
205
|
+
## Plain procs as templates
|
|
175
206
|
|
|
176
207
|
With Papercraft you can write a template as a plain Ruby proc, and later render
|
|
177
|
-
it by passing it as a block to `
|
|
208
|
+
it by passing it as a block to `Papercraft.html`:
|
|
178
209
|
|
|
179
210
|
```ruby
|
|
180
211
|
greeting = proc { |name| h1 "Hello, #{name}!" }
|
|
@@ -188,7 +219,7 @@ greeting = ->(name) { h1 "Hello, #{name}!" }
|
|
|
188
219
|
Papercraft.html(&greeting).render('world')
|
|
189
220
|
```
|
|
190
221
|
|
|
191
|
-
##
|
|
222
|
+
## Template composition
|
|
192
223
|
|
|
193
224
|
Papercraft makes it easy to compose multiple components into a whole HTML
|
|
194
225
|
document. A Papercraft component can contain other components, as the following
|
|
@@ -384,6 +415,22 @@ The deafult options can be configured by accessing
|
|
|
384
415
|
Papercraft.default_kramdown_options[:auto_ids] = false
|
|
385
416
|
```
|
|
386
417
|
|
|
418
|
+
## Working with MIME types
|
|
419
|
+
|
|
420
|
+
Papercraft lets you set and interrogate a template's MIME type, in order to be
|
|
421
|
+
able to dynamically set the `Content-Type` HTTP response header. A template's
|
|
422
|
+
MIME type can be set when creating the template, e.g. `Papercraft.xml(mime_type:
|
|
423
|
+
'application/rss+xml')`. You can interrogate the template's MIME type using
|
|
424
|
+
`#mime_type`:
|
|
425
|
+
|
|
426
|
+
```ruby
|
|
427
|
+
# using Qeweney (https://github.com/digital-fabric/qeweney)
|
|
428
|
+
def serve_template(req, template)
|
|
429
|
+
body = template.render
|
|
430
|
+
respond(body, 'Content-Type' => template.mime_type)
|
|
431
|
+
end
|
|
432
|
+
```
|
|
433
|
+
|
|
387
434
|
## Deferred evaluation
|
|
388
435
|
|
|
389
436
|
Deferred evaluation allows deferring the rendering of parts of a template until
|
|
@@ -502,11 +549,47 @@ Papercraft.html {
|
|
|
502
549
|
}
|
|
503
550
|
```
|
|
504
551
|
|
|
505
|
-
## JSON templating
|
|
506
552
|
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
553
|
+
|
|
554
|
+
## XML templates
|
|
555
|
+
|
|
556
|
+
XML templates behave largely the same as HTML templates, with a few minor
|
|
557
|
+
differences. XML templates employ a different encoding algorithm, and lack some
|
|
558
|
+
specific HTML functionality, such as emitting Markdown.
|
|
559
|
+
|
|
560
|
+
Here's an example showing how to create an RSS feed:
|
|
561
|
+
|
|
562
|
+
```ruby
|
|
563
|
+
rss = Papercraft.xml(mime_type: 'text/xml; charset=utf-8') { |resource:, **props|
|
|
564
|
+
rss(version: '2.0', 'xmlns:atom' => 'http://www.w3.org/2005/Atom') {
|
|
565
|
+
channel {
|
|
566
|
+
title 'Noteflakes'
|
|
567
|
+
link 'https://noteflakes.com/'
|
|
568
|
+
description 'A website by Sharon Rosner'
|
|
569
|
+
language 'en-us'
|
|
570
|
+
pubDate Time.now.httpdate
|
|
571
|
+
emit '<atom:link href="https://noteflakes.com/feeds/rss" rel="self" type="application/rss+xml" />'
|
|
572
|
+
|
|
573
|
+
article_entries = resource.page_list('/articles').reverse
|
|
574
|
+
|
|
575
|
+
article_entries.each { |e|
|
|
576
|
+
item {
|
|
577
|
+
title e[:title]
|
|
578
|
+
link "https://noteflakes.com#{e[:url]}"
|
|
579
|
+
guid "https://noteflakes.com#{e[:url]}"
|
|
580
|
+
pubDate e[:date].to_time.httpdate
|
|
581
|
+
description e[:html_content]
|
|
582
|
+
}
|
|
583
|
+
}
|
|
584
|
+
}
|
|
585
|
+
}
|
|
586
|
+
}
|
|
587
|
+
```
|
|
588
|
+
|
|
589
|
+
## JSON templates
|
|
590
|
+
|
|
591
|
+
JSON templates behave largely the same as HTML and XML templates. The only major
|
|
592
|
+
difference is that for adding array items you'll need to use the `#item` method:
|
|
510
593
|
|
|
511
594
|
```ruby
|
|
512
595
|
Papercraft.json {
|
|
@@ -531,7 +614,8 @@ Papercraft.json {
|
|
|
531
614
|
}.render #=> "{\"foo\":{\"bar\":[null,true,123.456]}}"
|
|
532
615
|
```
|
|
533
616
|
|
|
534
|
-
Papercraft uses the [JSON gem](https://rubyapi.org/3.1/o/json) under the hood
|
|
617
|
+
Papercraft uses the [JSON gem](https://rubyapi.org/3.1/o/json) under the hood in
|
|
618
|
+
order to generate actual JSON.
|
|
535
619
|
|
|
536
620
|
## API Reference
|
|
537
621
|
|
data/lib/papercraft/renderer.rb
CHANGED
|
@@ -223,10 +223,11 @@ module Papercraft
|
|
|
223
223
|
# @param *a [Array<any>] arguments to pass to a proc
|
|
224
224
|
# @param **b [Hash] named arguments to pass to a proc
|
|
225
225
|
# @return [void]
|
|
226
|
-
def emit(o, *a, **b)
|
|
226
|
+
def emit(o, *a, **b, &block)
|
|
227
227
|
case o
|
|
228
228
|
when ::Proc
|
|
229
229
|
Renderer.verify_proc_parameters(o, a, b)
|
|
230
|
+
push_emit_yield_block(block) if block
|
|
230
231
|
instance_exec(*a, **b, &o)
|
|
231
232
|
when nil
|
|
232
233
|
else
|
data/lib/papercraft/version.rb
CHANGED
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: papercraft
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: '0.
|
|
4
|
+
version: '0.18'
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Sharon Rosner
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: bin
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2022-
|
|
11
|
+
date: 2022-02-04 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: escape_utils
|