papercraft 0.8.2 → 0.10.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +14 -0
- data/README.md +132 -123
- data/lib/papercraft/component.rb +18 -11
- data/lib/papercraft/extension_proxy.rb +30 -0
- data/lib/papercraft/html.rb +36 -4
- data/lib/papercraft/renderer.rb +107 -41
- data/lib/papercraft/version.rb +1 -1
- data/lib/papercraft.rb +31 -11
- metadata +50 -7
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 757137ea8d3a2b5d5d329b7e841bad13cc26ea3486ebcb216f1ef016d7d3ff4a
|
4
|
+
data.tar.gz: 281ee3b2911b1f4e1ff3337dbefef407ce07b17e21acb949dce158a93d8758a5
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 22225498fce014a17962541bac3c17f20243239b709e191e75fa2f1abbc0f7f7fdef3b0c4d110753f0de1c2ca4efc19f516cb797a02cbafa70af95085449096e
|
7
|
+
data.tar.gz: 57bb7aae102900de14ba9d8f4a0e2be83978e5106ff098ffda5acf39431273fd76be646d012da72094715ad8a3da7fd81a485e51151c74df94091a91e72866f4
|
data/CHANGELOG.md
CHANGED
@@ -1,3 +1,17 @@
|
|
1
|
+
## 0.10.1 2021-12-25
|
2
|
+
|
3
|
+
- Fix tag rendering with empty text in Ruby 3.0
|
4
|
+
|
5
|
+
## 0.10 2021-12-25
|
6
|
+
|
7
|
+
- Add support for extensions
|
8
|
+
|
9
|
+
## 0.9 2021-12-23
|
10
|
+
|
11
|
+
- Add support for emitting Markdown
|
12
|
+
- Add support for passing proc as argument to `#H` and `#X`
|
13
|
+
- Deprecate `Encoding` module
|
14
|
+
|
1
15
|
## 0.8.1 2021-12-22
|
2
16
|
|
3
17
|
- Fix gemspec
|
data/README.md
CHANGED
@@ -1,30 +1,56 @@
|
|
1
|
-
|
1
|
+
<h1 align="center">
|
2
|
+
Papercraft
|
3
|
+
</h1>
|
4
|
+
|
5
|
+
<h4 align="center">Composable HTML templating for Ruby</h4>
|
6
|
+
|
7
|
+
<p align="center">
|
8
|
+
<a href="http://rubygems.org/gems/papercraft">
|
9
|
+
<img src="https://badge.fury.io/rb/papercraft.svg" alt="Ruby gem">
|
10
|
+
</a>
|
11
|
+
<a href="https://github.com/digital-fabric/papercraft/actions?query=workflow%3ATests">
|
12
|
+
<img src="https://github.com/digital-fabric/papercraft/workflows/Tests/badge.svg" alt="Tests">
|
13
|
+
</a>
|
14
|
+
<a href="https://github.com/digital-fabric/papercraft/blob/master/LICENSE">
|
15
|
+
<img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License">
|
16
|
+
</a>
|
17
|
+
</p>
|
18
|
+
|
19
|
+
<p align="center">
|
20
|
+
<a href="https://www.rubydoc.info/gems/papercraft">API reference</a>
|
21
|
+
</p>
|
2
22
|
|
3
|
-
|
4
|
-
[TUTORIAL](#getting-started) |
|
5
|
-
[EXAMPLES](examples) |
|
6
|
-
[REFERENCE](#api-reference)
|
23
|
+
# Papercraft - Composable HTML templating for Ruby
|
7
24
|
|
8
25
|
## What is Papercraft?
|
9
26
|
|
27
|
+
```ruby
|
28
|
+
require 'papercraft'
|
29
|
+
|
30
|
+
page = H { |*args|
|
31
|
+
html {
|
32
|
+
head { }
|
33
|
+
body { emit_yield *args }
|
34
|
+
}
|
35
|
+
}
|
36
|
+
|
37
|
+
hello = H.apply { |name| h1 "Hello, #{name}!" }
|
38
|
+
hello.render('world')
|
39
|
+
#=> "<html><head/><body><h1>Hello, world!</h1></body></html>"
|
40
|
+
```
|
41
|
+
|
10
42
|
Papercraft is an HTML templating engine for Ruby that offers the following
|
11
43
|
features:
|
12
44
|
|
13
|
-
- HTML templating using plain Ruby syntax
|
45
|
+
- HTML and XML templating using plain Ruby syntax
|
14
46
|
- Minimal boilerplate
|
15
47
|
- Mix logic and tags freely
|
16
|
-
-
|
17
|
-
- Automatic HTML escaping
|
48
|
+
- Automatic HTML and XML escaping
|
18
49
|
- Composable components
|
50
|
+
- Explicit parameter passing to nested components
|
19
51
|
- Higher order components
|
20
|
-
- Built-in support for rendering Markdown
|
21
|
-
|
22
|
-
> **Note** Papercraft is a new library and as such may be missing features and
|
23
|
-
> contain bugs. Also, its API may change unexpectedly. Your issue reports and
|
24
|
-
> code contributions are most welcome!
|
25
|
-
|
26
|
-
With Papercraft you can structure your templates as nested HTML components, in a
|
27
|
-
somewhat similar fashion to React.
|
52
|
+
- Built-in support for rendering [Markdown](#emitting-markdown)
|
53
|
+
- Support for namespaced extensions
|
28
54
|
|
29
55
|
## Installing Papercraft
|
30
56
|
|
@@ -42,42 +68,25 @@ $ gem install papercraft
|
|
42
68
|
|
43
69
|
## Getting started
|
44
70
|
|
45
|
-
To
|
71
|
+
To create a template use the global method `Kernel#H`:
|
46
72
|
|
47
73
|
```ruby
|
48
74
|
require 'papercraft'
|
49
|
-
```
|
50
|
-
|
51
|
-
To create a template use `Papercraft.new` or the global method `Kernel#H`:
|
52
75
|
|
53
|
-
```ruby
|
54
|
-
# can also use Papercraft.new
|
55
76
|
html = H {
|
56
|
-
div { p '
|
77
|
+
div(id: 'greeter') { p 'Hello!' }
|
57
78
|
}
|
58
79
|
```
|
59
80
|
|
60
|
-
|
61
|
-
|
62
|
-
To render a Papercraft template use the `#render` method:
|
81
|
+
Rendering a template is done using `#render`:
|
63
82
|
|
64
83
|
```ruby
|
65
|
-
|
66
|
-
```
|
67
|
-
|
68
|
-
The render method accepts an arbitrary context variable:
|
69
|
-
|
70
|
-
```ruby
|
71
|
-
html = H {
|
72
|
-
h1 context[:title]
|
73
|
-
}
|
74
|
-
|
75
|
-
html.render(title: 'My title') #=> "<h1>My title</h1>"
|
84
|
+
html.render #=> "<div id="greeter"><p>Hello!</p></div>"
|
76
85
|
```
|
77
86
|
|
78
87
|
## All about tags
|
79
88
|
|
80
|
-
Tags are added using unqualified method calls, and
|
89
|
+
Tags are added using unqualified method calls, and can be nested using blocks:
|
81
90
|
|
82
91
|
```ruby
|
83
92
|
H {
|
@@ -114,8 +123,9 @@ H { p "foobar", class: 'important' }.render #=> "<p class=\"important\">foobar</
|
|
114
123
|
|
115
124
|
## Template parameters
|
116
125
|
|
117
|
-
|
118
|
-
template on
|
126
|
+
In Papercraft, parameters are always passed explicitly. This means that template
|
127
|
+
parameters are specified as block parameters, and are passed to the template on
|
128
|
+
rendering:
|
119
129
|
|
120
130
|
```ruby
|
121
131
|
greeting = H { |name| h1 "Hello, #{name}!" }
|
@@ -328,110 +338,109 @@ H { str 'hi&lo' }.render #=> "hi&lo"
|
|
328
338
|
|
329
339
|
## Emitting Markdown
|
330
340
|
|
331
|
-
|
341
|
+
Markdown is rendered using the
|
342
|
+
[Kramdown](https://kramdown.gettalong.org/index.html) gem. To emit Markdown, use
|
343
|
+
`#emit_markdown`:
|
332
344
|
|
333
345
|
```ruby
|
334
346
|
template = H { |md| div { emit_markdown md } }
|
335
|
-
template.render("Here's some *Markdown*") #=> "<div>Here's some <em>Markdown</em
|
347
|
+
template.render("Here's some *Markdown*") #=> "<div><p>Here's some <em>Markdown</em><p>\n</div>"
|
336
348
|
```
|
337
349
|
|
338
|
-
|
339
|
-
|
340
|
-
|
341
|
-
together pieces of HTML. Feel free to explore the API!
|
350
|
+
[Kramdown
|
351
|
+
options](https://kramdown.gettalong.org/options.html#available-options) can be
|
352
|
+
specified by adding them to the `#emit_markdown` call:
|
342
353
|
|
343
|
-
|
354
|
+
```ruby
|
355
|
+
template = H { |md| div { emit_markdown md, auto_ids: false } }
|
356
|
+
template.render("# title") #=> "<div><h1>title</h1></div>"
|
357
|
+
```
|
344
358
|
|
345
|
-
|
346
|
-
takes an item component as an argument. The `List` component can be reused for
|
347
|
-
rendering any kind of unordered list, and with any kind of item component:
|
359
|
+
The default Kramdown options are:
|
348
360
|
|
349
361
|
```ruby
|
350
|
-
|
351
|
-
|
352
|
-
|
353
|
-
|
354
|
-
|
355
|
-
li { emit item_component }
|
356
|
-
}
|
357
|
-
}
|
358
|
-
}
|
359
|
-
}
|
360
|
-
}
|
361
|
-
|
362
|
-
TodoItem = H {
|
363
|
-
span item.text, class: item.completed ? 'completed' : 'pending'
|
362
|
+
{
|
363
|
+
entity_output: :numeric,
|
364
|
+
syntax_highlighter: :rouge,
|
365
|
+
input: 'GFM',
|
366
|
+
hard_wrap: false
|
364
367
|
}
|
365
|
-
|
366
|
-
def todo_list(items)
|
367
|
-
H {
|
368
|
-
div { List(items, TodoItem) }
|
369
|
-
}
|
370
|
-
end
|
371
368
|
```
|
372
369
|
|
373
|
-
|
374
|
-
|
375
|
-
#### `Papercraft#initialize(**context, &block)` a.k.a. `Kernel#H`
|
376
|
-
|
377
|
-
- `context`: local context hash
|
378
|
-
- `block`: template block
|
379
|
-
|
380
|
-
Initializes a new Papercraft instance. This method takes a block of template
|
381
|
-
code, and an optional [local context](#local-context) in the form of a hash.
|
382
|
-
The `Kernel#H` method serves as a shortcut for creating Papercraft instances.
|
383
|
-
|
384
|
-
#### `Papercraft#render(**context)`
|
385
|
-
|
386
|
-
- `context`: global context hash
|
387
|
-
|
388
|
-
Renders the template with an optional [global context](#global-context)
|
389
|
-
hash.
|
390
|
-
|
391
|
-
#### Methods accessible inside template blocks
|
392
|
-
|
393
|
-
#### `#<tag/component>(*args, **props, &block)`
|
394
|
-
|
395
|
-
- `args`: tag arguments. For an HTML tag Papercraft expects a single `String`
|
396
|
-
argument containing the inner text of the tag.
|
397
|
-
- `props`: hash of tag attributes
|
398
|
-
- `block`: inner HTML block
|
399
|
-
|
400
|
-
Adds a tag or component to the current template. If the method name starts with
|
401
|
-
an upper-case letter, it is considered a [component](#templates-as-components).
|
402
|
-
|
403
|
-
If a text argument is given for a tag, it will be escaped.
|
404
|
-
|
405
|
-
#### `#cache(*vary, &block)`
|
406
|
-
|
407
|
-
- `vary`: variables used in cached block. The given values will be used to
|
408
|
-
create a separate cache entry.
|
409
|
-
- `block`: inner HTML block
|
370
|
+
The deafult options can be configured by accessing
|
371
|
+
`Papercraft::HTML.kramdown_options`:
|
410
372
|
|
411
|
-
|
412
|
-
|
413
|
-
|
414
|
-
a separate cache entry.
|
373
|
+
```ruby
|
374
|
+
Papercraft::HTML.kramdown_options[:auto_ids] = false
|
375
|
+
```
|
415
376
|
|
416
|
-
|
377
|
+
## Papercraft extensions
|
378
|
+
|
379
|
+
Papercraft extensions are modules that contain one or more methods that can be
|
380
|
+
used to render complex HTML components. Extension modules can be used by
|
381
|
+
installing them as a namespaced extension using `Papercraft.extension`.
|
382
|
+
Extensions are particularly useful when you work with CSS frameworks such as
|
383
|
+
[Bootstrap](https://getbootstrap.com/), [Tailwind](https://tailwindui.com/) or
|
384
|
+
[Primer](https://primer.style/).
|
385
|
+
|
386
|
+
For example, to create a Bootstrap card component, the following HTML markup is
|
387
|
+
needed (example taken from the [Bootstrap
|
388
|
+
docs](https://getbootstrap.com/docs/5.1/components/card/#titles-text-and-links)):
|
389
|
+
|
390
|
+
```html
|
391
|
+
<div class="card" style="width: 18rem;">
|
392
|
+
<div class="card-body">
|
393
|
+
<h5 class="card-title">Card title</h5>
|
394
|
+
<h6 class="card-subtitle mb-2 text-muted">Card subtitle</h6>
|
395
|
+
<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>
|
396
|
+
<a href="#" class="card-link">Card link</a>
|
397
|
+
<a href="#" class="card-link">Another link</a>
|
398
|
+
</div>
|
399
|
+
</div>
|
400
|
+
```
|
417
401
|
|
418
|
-
|
402
|
+
With Papercraft, we could create a `Bootstrap` extension with a `#card` method
|
403
|
+
and other associated methods:
|
419
404
|
|
420
|
-
|
405
|
+
```ruby
|
406
|
+
module BootstrapComponents
|
407
|
+
...
|
421
408
|
|
422
|
-
|
409
|
+
def card(**props)
|
410
|
+
div(class: 'card', **props) {
|
411
|
+
div(class: 'card-body') {
|
412
|
+
emit_yield
|
413
|
+
}
|
414
|
+
}
|
415
|
+
end
|
423
416
|
|
424
|
-
|
425
|
-
|
417
|
+
def card_title(title)
|
418
|
+
h5 title, class: 'card-title'
|
419
|
+
end
|
426
420
|
|
427
|
-
|
421
|
+
...
|
422
|
+
end
|
428
423
|
|
429
|
-
|
424
|
+
Papercraft.extension(bootstrap: BootstrapComponents)
|
425
|
+
```
|
430
426
|
|
431
|
-
|
427
|
+
The call to `Papercraft.extension` lets us access the different methods of
|
428
|
+
`BootstrapComponents` by calling `#bootstrap` inside a template. With this,
|
429
|
+
we'll be able to express the above markup as follows:
|
432
430
|
|
433
|
-
|
431
|
+
```ruby
|
432
|
+
H {
|
433
|
+
bootstrap.card(style: 'width: 18rem') {
|
434
|
+
bootstrap.card_title 'Card title'
|
435
|
+
bootstrap.card_subtitle 'Card subtitle'
|
436
|
+
bootstrap.card_text 'Some quick example text to build on the card title and make up the bulk of the card''s content.'
|
437
|
+
bootstrap.card_link '#', 'Card link'
|
438
|
+
bootstrap.card_link '#', 'Another link'
|
439
|
+
}
|
440
|
+
}
|
441
|
+
```
|
434
442
|
|
435
|
-
|
443
|
+
## API Reference
|
436
444
|
|
437
|
-
|
445
|
+
The API reference for this library can be found
|
446
|
+
[here](https://www.rubydoc.info/gems/papercraft).
|
data/lib/papercraft/component.rb
CHANGED
@@ -14,8 +14,8 @@ module Papercraft
|
|
14
14
|
# Components are usually created using the global methods `H` or `X`, for HTML
|
15
15
|
# or XML templates, respectively:
|
16
16
|
#
|
17
|
-
# greeter = H { |name| h1 "Hello, #{name}!" }
|
18
|
-
# "<h1>Hello, world!</h1>"
|
17
|
+
# greeter = H { |name| h1 "Hello, #{name}!" }
|
18
|
+
# greeter.render('world') #=> "<h1>Hello, world!</h1>"
|
19
19
|
#
|
20
20
|
# Components can also be created using the normal constructor:
|
21
21
|
#
|
@@ -25,7 +25,10 @@ module Papercraft
|
|
25
25
|
# In the component block, HTML elements are created by simply calling
|
26
26
|
# unqualified methods:
|
27
27
|
#
|
28
|
-
# page_layout = H {
|
28
|
+
# page_layout = H {
|
29
|
+
# html5 {
|
30
|
+
# head {
|
31
|
+
# title 'foo'
|
29
32
|
# }
|
30
33
|
# body {
|
31
34
|
# h1 "Hello, world!"
|
@@ -75,7 +78,11 @@ module Papercraft
|
|
75
78
|
# anchor.apply(uri: '/about', text: 'About')
|
76
79
|
# ])
|
77
80
|
# links_with_anchors.render
|
81
|
+
#
|
78
82
|
class Component < Proc
|
83
|
+
|
84
|
+
# Determines the rendering mode: `:html` or `:xml`.
|
85
|
+
attr_accessor :mode
|
79
86
|
|
80
87
|
# Initializes a component with the given block. The rendering mode (HTML or
|
81
88
|
# XML) can be passed in the `mode:` parameter. If `mode:` is not specified,
|
@@ -113,15 +120,15 @@ module Papercraft
|
|
113
120
|
# current one. Application is one of the principal methods of composing
|
114
121
|
# components, particularly when passing inner components as blocks:
|
115
122
|
#
|
116
|
-
#
|
117
|
-
#
|
118
|
-
#
|
123
|
+
# article_wrapper = H {
|
124
|
+
# article {
|
125
|
+
# emit_yield
|
126
|
+
# }
|
127
|
+
# }
|
128
|
+
# wrapped_article = article_wrapper.apply {
|
129
|
+
# h1 'Article title'
|
119
130
|
# }
|
120
|
-
#
|
121
|
-
# wrapped_article = article_wrapper.apply {
|
122
|
-
# h1 'Article title'
|
123
|
-
# }
|
124
|
-
# wrapped_article.render #=> "<article><h1>Article title</h1></article>"
|
131
|
+
# wrapped_article.render #=> "<article><h1>Article title</h1></article>"
|
125
132
|
#
|
126
133
|
# @param *a [<any>] normal parameters
|
127
134
|
# @param **b [Hash] named parameters
|
@@ -0,0 +1,30 @@
|
|
1
|
+
# frozen_string_literal: true
|
2
|
+
|
3
|
+
module Papercraft
|
4
|
+
|
5
|
+
# An ExtensionProxy proxies method calls to a renderer. Extension proxies are
|
6
|
+
# used to provide an namespaced interface to Papercraft extensions. When an
|
7
|
+
# extension is installed using `Papercraft.extension`, a corresponding method
|
8
|
+
# is defined on the `Papercraft::Renderer` class that creates an extension
|
9
|
+
# proxy that gives access to the different extension methods.
|
10
|
+
class ExtensionProxy
|
11
|
+
|
12
|
+
# Initializes a new ExtensionProxy.
|
13
|
+
# @param renderer [Papercraft::Renderer] renderer to proxy to
|
14
|
+
# @param mod [Module] extension module
|
15
|
+
# @return [void]
|
16
|
+
def initialize(renderer, mod)
|
17
|
+
@renderer = renderer
|
18
|
+
extend(mod)
|
19
|
+
end
|
20
|
+
|
21
|
+
# Proxies missing methods to the renderer
|
22
|
+
# @param sym [Symbol] method name
|
23
|
+
# @param *args [Array] arguments
|
24
|
+
# @param &block [Proc] block
|
25
|
+
# @return void
|
26
|
+
def method_missing(sym, *args, &block)
|
27
|
+
@renderer.send(sym, *args, &block)
|
28
|
+
end
|
29
|
+
end
|
30
|
+
end
|
data/lib/papercraft/html.rb
CHANGED
@@ -1,11 +1,14 @@
|
|
1
1
|
# frozen_string_literal: true
|
2
2
|
|
3
|
-
|
3
|
+
require 'kramdown'
|
4
|
+
require 'rouge'
|
5
|
+
require 'kramdown-parser-gfm'
|
4
6
|
|
5
|
-
module Papercraft
|
6
|
-
# Markup extensions
|
7
|
+
module Papercraft
|
8
|
+
# HTML Markup extensions
|
7
9
|
module HTML
|
8
10
|
# Emits the p tag (overrides Object#p)
|
11
|
+
#
|
9
12
|
# @param text [String] text content of tag
|
10
13
|
# @param props [Hash] tag attributes
|
11
14
|
# @para block [Proc] nested HTML block
|
@@ -16,7 +19,8 @@ module Papercraft
|
|
16
19
|
|
17
20
|
S_HTML5_DOCTYPE = '<!DOCTYPE html>'
|
18
21
|
|
19
|
-
# Emits an HTML5 doctype tag and an html tag with the given block
|
22
|
+
# Emits an HTML5 doctype tag and an html tag with the given block.
|
23
|
+
#
|
20
24
|
# @param block [Proc] nested HTML block
|
21
25
|
# @return [void]
|
22
26
|
def html5(&block)
|
@@ -24,6 +28,11 @@ module Papercraft
|
|
24
28
|
self.html(&block)
|
25
29
|
end
|
26
30
|
|
31
|
+
# Emits a link element with a stylesheet.
|
32
|
+
#
|
33
|
+
# @param href [String] stylesheet URL
|
34
|
+
# @param custom_attributes [Hash] optional custom attributes for the link element
|
35
|
+
# @return [void]
|
27
36
|
def link_stylesheet(href, custom_attributes = nil)
|
28
37
|
attributes = {
|
29
38
|
rel: 'stylesheet',
|
@@ -34,5 +43,28 @@ module Papercraft
|
|
34
43
|
end
|
35
44
|
link(**attributes)
|
36
45
|
end
|
46
|
+
|
47
|
+
def emit_markdown(markdown, **opts)
|
48
|
+
emit Kramdown::Document.new(markdown, **kramdown_options(opts)).to_html
|
49
|
+
end
|
50
|
+
|
51
|
+
def kramdown_options(opts)
|
52
|
+
HTML.kramdown_options.merge(**opts)
|
53
|
+
end
|
54
|
+
|
55
|
+
class << self
|
56
|
+
def kramdown_options
|
57
|
+
@kramdown_options ||= {
|
58
|
+
entity_output: :numeric,
|
59
|
+
syntax_highlighter: :rouge,
|
60
|
+
input: 'GFM',
|
61
|
+
hard_wrap: false
|
62
|
+
}
|
63
|
+
end
|
64
|
+
|
65
|
+
def kramdown_options=(opts)
|
66
|
+
@kramdown_options = opts
|
67
|
+
end
|
68
|
+
end
|
37
69
|
end
|
38
70
|
end
|
data/lib/papercraft/renderer.rb
CHANGED
@@ -1,11 +1,22 @@
|
|
1
1
|
# frozen_string_literal: true
|
2
2
|
|
3
3
|
require_relative './html'
|
4
|
+
require_relative './extension_proxy'
|
4
5
|
|
5
6
|
module Papercraft
|
7
|
+
|
6
8
|
# A Renderer renders a Papercraft component into a string
|
7
9
|
class Renderer
|
10
|
+
|
8
11
|
class << self
|
12
|
+
|
13
|
+
# Verifies that the given template proc can be called with the given
|
14
|
+
# arguments and named arguments. If the proc demands named argument keys
|
15
|
+
# that do not exist in `named_args`, `Papercraft::Error` is raised.
|
16
|
+
#
|
17
|
+
# @param template [Proc] proc to verify
|
18
|
+
# @param args [Array<any>] arguments passed to proc
|
19
|
+
# @param named_args [Hash] named arguments passed to proc
|
9
20
|
def verify_proc_parameters(template, args, named_args)
|
10
21
|
param_count = 0
|
11
22
|
template.parameters.each do |(type, name)|
|
@@ -21,40 +32,58 @@ module Papercraft
|
|
21
32
|
if param_count > args.size
|
22
33
|
raise Papercraft::Error, "Missing template parameters"
|
23
34
|
end
|
24
|
-
end
|
25
|
-
end
|
35
|
+
end
|
26
36
|
|
27
|
-
|
37
|
+
# Installs the given extensions, mapping a method name to the extension
|
38
|
+
# module.
|
39
|
+
# @param map [Hash] hash mapping methods to extension modules
|
40
|
+
# @return [void]
|
41
|
+
def extension(map)
|
42
|
+
map.each do |sym, mod|
|
43
|
+
define_extension_method(sym, mod)
|
44
|
+
end
|
45
|
+
end
|
28
46
|
|
29
|
-
|
30
|
-
|
31
|
-
|
32
|
-
|
47
|
+
private
|
48
|
+
|
49
|
+
# Defines a method returning an extension proxy for the given module
|
50
|
+
# @param sym [Symbol] method name
|
51
|
+
# @param mod [Module] extension module
|
52
|
+
# @return [void]
|
53
|
+
def define_extension_method(sym, mod)
|
54
|
+
define_method(sym) do
|
55
|
+
(@extension_proxies ||= {})[mod] ||= ExtensionProxy.new(self, mod)
|
56
|
+
end
|
57
|
+
end
|
58
|
+
end
|
59
|
+
|
60
|
+
# Initializes the renderer and evaulates the given template in the
|
61
|
+
# renderer's scope.
|
62
|
+
#
|
63
|
+
# @param &template [Proc] template block
|
33
64
|
def initialize(&template)
|
34
65
|
@buffer = +''
|
35
66
|
instance_eval(&template)
|
36
67
|
end
|
37
68
|
|
38
|
-
# Returns the
|
69
|
+
# Returns the rendered template.
|
70
|
+
#
|
39
71
|
# @return [String]
|
40
72
|
def to_s
|
41
73
|
@buffer
|
42
74
|
end
|
43
75
|
|
44
|
-
def escape_text(text)
|
45
|
-
raise NotImplementedError
|
46
|
-
end
|
47
|
-
|
48
|
-
def escape_uri(uri)
|
49
|
-
EscapeUtils.escape_uri(v)
|
50
|
-
end
|
51
|
-
|
52
76
|
S_TAG_METHOD_LINE = __LINE__ + 1
|
53
77
|
S_TAG_METHOD = <<~EOF
|
54
78
|
S_TAG_%<TAG>s_PRE = '<%<tag>s'.tr('_', '-')
|
55
79
|
S_TAG_%<TAG>s_CLOSE = '</%<tag>s>'.tr('_', '-')
|
56
80
|
|
57
81
|
def %<tag>s(text = nil, **props, &block)
|
82
|
+
if text.is_a?(Hash) && props.empty?
|
83
|
+
props = text
|
84
|
+
text = nil
|
85
|
+
end
|
86
|
+
|
58
87
|
@buffer << S_TAG_%<TAG>s_PRE
|
59
88
|
emit_props(props) unless props.empty?
|
60
89
|
|
@@ -74,33 +103,42 @@ module Papercraft
|
|
74
103
|
end
|
75
104
|
EOF
|
76
105
|
|
77
|
-
# Catches undefined tag method call and handles
|
106
|
+
# Catches undefined tag method call and handles it by defining the method.
|
107
|
+
#
|
78
108
|
# @param sym [Symbol] HTML tag or component identifier
|
79
|
-
# @param args [Array] method
|
80
|
-
# @param
|
109
|
+
# @param args [Array] method arguments
|
110
|
+
# @param opts [Hash] named method arguments
|
111
|
+
# @param &block [Proc] block passed to method
|
81
112
|
# @return [void]
|
82
113
|
def method_missing(sym, *args, **opts, &block)
|
83
|
-
value = @local && @local[sym]
|
84
|
-
return value if value
|
85
|
-
|
86
114
|
tag = sym.to_s
|
87
115
|
code = S_TAG_METHOD % { tag: tag, TAG: tag.upcase }
|
88
116
|
self.class.class_eval(code, __FILE__, S_TAG_METHOD_LINE)
|
89
117
|
send(sym, *args, **opts, &block)
|
90
118
|
end
|
91
119
|
|
92
|
-
# Emits the given object into the rendering buffer
|
120
|
+
# Emits the given object into the rendering buffer. If the given object is a
|
121
|
+
# proc or a component, `emit` will passes any additional arguments and named
|
122
|
+
# arguments to the object when rendering it. If the given object is nil,
|
123
|
+
# nothing is emitted. Otherwise, the object is converted into a string using
|
124
|
+
# `#to_s` which is then added to the rendering buffer, without any escaping.
|
125
|
+
#
|
126
|
+
# greeter = proc { |name| h1 "Hello, #{name}!" }
|
127
|
+
# H { emit(greeter, 'world') }.render #=> "<h1>Hello, world!</h1>"
|
128
|
+
#
|
129
|
+
# H { emit 'hi&<bye>' }.render #=> "hi&<bye>"
|
130
|
+
#
|
131
|
+
# H { emit nil }.render #=> ""
|
132
|
+
#
|
93
133
|
# @param o [Proc, Papercraft::Component, String] emitted object
|
134
|
+
# @param *a [Array<any>] arguments to pass to a proc
|
135
|
+
# @param **b [Hash] named arguments to pass to a proc
|
94
136
|
# @return [void]
|
95
137
|
def emit(o, *a, **b)
|
96
138
|
case o
|
97
139
|
when ::Proc
|
98
140
|
Renderer.verify_proc_parameters(o, a, b)
|
99
141
|
instance_exec(*a, **b, &o)
|
100
|
-
# when Papercraft::Component
|
101
|
-
# o = o.template
|
102
|
-
# Renderer.verify_proc_parameters(o, a, b)
|
103
|
-
# instance_exec(*a, **b, &o)
|
104
142
|
when nil
|
105
143
|
else
|
106
144
|
@buffer << o.to_s
|
@@ -108,14 +146,15 @@ module Papercraft
|
|
108
146
|
end
|
109
147
|
alias_method :e, :emit
|
110
148
|
|
111
|
-
|
112
|
-
|
113
|
-
|
114
|
-
|
115
|
-
|
116
|
-
|
117
|
-
|
118
|
-
|
149
|
+
# Emits a block supplied using `Component#apply` or `Component#render`.
|
150
|
+
#
|
151
|
+
# div_wrap = H { |*args| div { emit_yield(*args) } }
|
152
|
+
# greeter = div_wrap.apply { |name| h1 "Hello, #{name}!" }
|
153
|
+
# greeter.render('world') #=> "<div><h1>Hello, world!</h1></div>"
|
154
|
+
#
|
155
|
+
# @param *a [Array<any>] arguments to pass to a proc
|
156
|
+
# @param **b [Hash] named arguments to pass to a proc
|
157
|
+
# @return [void]
|
119
158
|
def emit_yield(*a, **b)
|
120
159
|
raise Papercraft::Error, "No block given" unless @inner_block
|
121
160
|
|
@@ -131,6 +170,31 @@ module Papercraft
|
|
131
170
|
S_EQUAL_QUOTE = '="'
|
132
171
|
S_QUOTE = '"'
|
133
172
|
|
173
|
+
# Emits text into the rendering buffer, escaping any special characters to
|
174
|
+
# the respective HTML entities.
|
175
|
+
#
|
176
|
+
# @param data [String] text
|
177
|
+
# @return [void]
|
178
|
+
def text(data)
|
179
|
+
@buffer << escape_text(data)
|
180
|
+
end
|
181
|
+
|
182
|
+
private
|
183
|
+
|
184
|
+
# Escapes text. This method must be overriden in descendant classes.
|
185
|
+
def escape_text(text)
|
186
|
+
raise NotImplementedError
|
187
|
+
end
|
188
|
+
|
189
|
+
# Sets up a block to be called with `#emit_yield`
|
190
|
+
def with_block(block, &run_block)
|
191
|
+
old_block = @inner_block
|
192
|
+
@inner_block = block
|
193
|
+
instance_eval(&run_block)
|
194
|
+
ensure
|
195
|
+
@inner_block = old_block
|
196
|
+
end
|
197
|
+
|
134
198
|
# Emits tag attributes into the rendering buffer
|
135
199
|
# @param props [Hash] tag attributes
|
136
200
|
# @return [void]
|
@@ -153,23 +217,25 @@ module Papercraft
|
|
153
217
|
end
|
154
218
|
}
|
155
219
|
end
|
156
|
-
|
157
|
-
# Emits text into the rendering buffer
|
158
|
-
# @param data [String] text
|
159
|
-
def text(data)
|
160
|
-
@buffer << escape_text(data)
|
161
|
-
end
|
162
220
|
end
|
163
221
|
|
222
|
+
# Implements an HTML renderer
|
164
223
|
class HTMLRenderer < Renderer
|
165
224
|
include HTML
|
166
225
|
|
226
|
+
private
|
227
|
+
|
228
|
+
# Escapes the given text using HTML entities.
|
167
229
|
def escape_text(text)
|
168
230
|
EscapeUtils.escape_html(text.to_s)
|
169
231
|
end
|
170
232
|
end
|
171
233
|
|
234
|
+
# Implements an XML renderer
|
172
235
|
class XMLRenderer < Renderer
|
236
|
+
private
|
237
|
+
|
238
|
+
# Escapes the given text using XML entities.
|
173
239
|
def escape_text(text)
|
174
240
|
EscapeUtils.escape_xml(text.to_s)
|
175
241
|
end
|
data/lib/papercraft/version.rb
CHANGED
data/lib/papercraft.rb
CHANGED
@@ -11,24 +11,44 @@ require_relative 'papercraft/encoding'
|
|
11
11
|
module Papercraft
|
12
12
|
# Exception class used to signal templating-related errors
|
13
13
|
class Error < RuntimeError; end
|
14
|
+
|
15
|
+
# Installs one or more extensions. Extensions enhance templating capabilities
|
16
|
+
# by adding namespaced methods to emplates. An extension is implemented as a
|
17
|
+
# Ruby module containing one or more methods. Each method in the extension
|
18
|
+
# module can be used to render a specific HTML element or a set of elements.
|
19
|
+
def self.extension(map)
|
20
|
+
Renderer.extension(map)
|
21
|
+
end
|
14
22
|
end
|
15
23
|
|
16
24
|
# Kernel extensions
|
17
25
|
module ::Kernel
|
18
|
-
|
19
|
-
#
|
26
|
+
|
27
|
+
# Creates a new papercraft component. `#H` can take either a proc argument or
|
28
|
+
# a block. In both cases, the proc is converted to a `Papercraft::Component`.
|
29
|
+
#
|
30
|
+
# H(proc { h1 'hi' }).render #=> "<h1>hi</h1>"
|
31
|
+
# H { h1 'hi' }.render #=> "<h1>hi</h1>"
|
32
|
+
#
|
20
33
|
# @param template [Proc] template block
|
21
|
-
# @return [Papercraft] Papercraft
|
22
|
-
def H(&template)
|
23
|
-
Papercraft::Component
|
34
|
+
# @return [Papercraft::Component] Papercraft component
|
35
|
+
def H(o = nil, &template)
|
36
|
+
return o if o.is_a?(Papercraft::Component)
|
37
|
+
template ||= o
|
38
|
+
Papercraft::Component.new(mode: :html, &template)
|
24
39
|
end
|
25
40
|
|
26
|
-
|
41
|
+
# Creates a new papercraft component in XML mode. `#X` can take either a proc argument or
|
42
|
+
# a block. In both cases, the proc is converted to a `Papercraft::Component`.
|
43
|
+
#
|
44
|
+
# X(proc { item 'foo' }).render #=> "<item>foo</item>"
|
45
|
+
# X { item 'foo' }.render #=> "<item>foo</item>"
|
46
|
+
#
|
47
|
+
# @param template [Proc] template block
|
48
|
+
# @return [Papercraft::Component] Papercraft component
|
49
|
+
def X(o = nil, &template)
|
50
|
+
return o if o.is_a?(Papercraft::Component)
|
51
|
+
template ||= o
|
27
52
|
Papercraft::Component.new(mode: :xml, &template)
|
28
53
|
end
|
29
54
|
end
|
30
|
-
|
31
|
-
# Object extensions
|
32
|
-
class Object
|
33
|
-
include Papercraft::Encoding
|
34
|
-
end
|
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.10.1
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Sharon Rosner
|
8
|
-
autorequire:
|
8
|
+
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2021-12-
|
11
|
+
date: 2021-12-25 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: escape_utils
|
@@ -24,6 +24,48 @@ dependencies:
|
|
24
24
|
- - '='
|
25
25
|
- !ruby/object:Gem::Version
|
26
26
|
version: 1.2.1
|
27
|
+
- !ruby/object:Gem::Dependency
|
28
|
+
name: kramdown
|
29
|
+
requirement: !ruby/object:Gem::Requirement
|
30
|
+
requirements:
|
31
|
+
- - "~>"
|
32
|
+
- !ruby/object:Gem::Version
|
33
|
+
version: 2.3.0
|
34
|
+
type: :runtime
|
35
|
+
prerelease: false
|
36
|
+
version_requirements: !ruby/object:Gem::Requirement
|
37
|
+
requirements:
|
38
|
+
- - "~>"
|
39
|
+
- !ruby/object:Gem::Version
|
40
|
+
version: 2.3.0
|
41
|
+
- !ruby/object:Gem::Dependency
|
42
|
+
name: rouge
|
43
|
+
requirement: !ruby/object:Gem::Requirement
|
44
|
+
requirements:
|
45
|
+
- - "~>"
|
46
|
+
- !ruby/object:Gem::Version
|
47
|
+
version: 3.26.0
|
48
|
+
type: :runtime
|
49
|
+
prerelease: false
|
50
|
+
version_requirements: !ruby/object:Gem::Requirement
|
51
|
+
requirements:
|
52
|
+
- - "~>"
|
53
|
+
- !ruby/object:Gem::Version
|
54
|
+
version: 3.26.0
|
55
|
+
- !ruby/object:Gem::Dependency
|
56
|
+
name: kramdown-parser-gfm
|
57
|
+
requirement: !ruby/object:Gem::Requirement
|
58
|
+
requirements:
|
59
|
+
- - "~>"
|
60
|
+
- !ruby/object:Gem::Version
|
61
|
+
version: 1.1.0
|
62
|
+
type: :runtime
|
63
|
+
prerelease: false
|
64
|
+
version_requirements: !ruby/object:Gem::Requirement
|
65
|
+
requirements:
|
66
|
+
- - "~>"
|
67
|
+
- !ruby/object:Gem::Version
|
68
|
+
version: 1.1.0
|
27
69
|
- !ruby/object:Gem::Dependency
|
28
70
|
name: minitest
|
29
71
|
requirement: !ruby/object:Gem::Requirement
|
@@ -80,7 +122,7 @@ dependencies:
|
|
80
122
|
- - '='
|
81
123
|
- !ruby/object:Gem::Version
|
82
124
|
version: 2.0.9
|
83
|
-
description:
|
125
|
+
description:
|
84
126
|
email: sharon@noteflakes.com
|
85
127
|
executables: []
|
86
128
|
extensions: []
|
@@ -93,6 +135,7 @@ files:
|
|
93
135
|
- lib/papercraft/compiler.rb
|
94
136
|
- lib/papercraft/component.rb
|
95
137
|
- lib/papercraft/encoding.rb
|
138
|
+
- lib/papercraft/extension_proxy.rb
|
96
139
|
- lib/papercraft/html.rb
|
97
140
|
- lib/papercraft/renderer.rb
|
98
141
|
- lib/papercraft/version.rb
|
@@ -104,7 +147,7 @@ metadata:
|
|
104
147
|
documentation_uri: https://www.rubydoc.info/gems/papercraft
|
105
148
|
homepage_uri: https://github.com/digital-fabric/papercraft
|
106
149
|
changelog_uri: https://github.com/digital-fabric/papercraft/blob/master/CHANGELOG.md
|
107
|
-
post_install_message:
|
150
|
+
post_install_message:
|
108
151
|
rdoc_options:
|
109
152
|
- "--title"
|
110
153
|
- Papercraft
|
@@ -123,8 +166,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
123
166
|
- !ruby/object:Gem::Version
|
124
167
|
version: '0'
|
125
168
|
requirements: []
|
126
|
-
rubygems_version: 3.
|
127
|
-
signing_key:
|
169
|
+
rubygems_version: 3.2.32
|
170
|
+
signing_key:
|
128
171
|
specification_version: 4
|
129
172
|
summary: 'Papercraft: component-based HTML templating for Ruby'
|
130
173
|
test_files: []
|