papercraft 0.8.3 → 0.9
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +6 -0
- data/README.md +50 -105
- data/lib/papercraft/html.rb +27 -3
- data/lib/papercraft/version.rb +1 -1
- metadata +43 -1
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: e1f7aa5872a78830c1a5662f055639ae2012b5b9d0f029640dce041f58d1ef4e
|
4
|
+
data.tar.gz: 0c5acc8b14254c63db2132caab42ce003a8ae4713ae6daea7225d0390a420219
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 02bf1f7bc1300f4fa7871a6942c6a2eae2dd2f8202c7f3cc354171806f82e8a68262c3ca5e2232b7b6dcf6788a33b134b5811641561fa5baba3b7c342643b082
|
7
|
+
data.tar.gz: 97a68a0f854f631a6a36b52a350faae4b1da1e337b27701209c6eec9dc16c62856555fdff3ab3d8f33e144e7fed8dc892b22433f38dd3f951a04010f710b63c4
|
data/CHANGELOG.md
CHANGED
data/README.md
CHANGED
@@ -2,26 +2,36 @@
|
|
2
2
|
|
3
3
|
[INSTALL](#installing-papercraft) |
|
4
4
|
[TUTORIAL](#getting-started) |
|
5
|
-
[
|
6
|
-
[REFERENCE](#api-reference)
|
5
|
+
[DOCS](https://www.rubydoc.info/gems/papercraft)
|
7
6
|
|
8
7
|
## What is Papercraft?
|
9
8
|
|
9
|
+
```ruby
|
10
|
+
require 'papercraft'
|
11
|
+
|
12
|
+
page = H { |*args|
|
13
|
+
html {
|
14
|
+
head { }
|
15
|
+
body { emit_yield *args }
|
16
|
+
}
|
17
|
+
}
|
18
|
+
|
19
|
+
hello = H.apply { |name| h1 "Hello, #{name}!" }
|
20
|
+
hello.render('world')
|
21
|
+
#=> "<html><head/><body><h1>Hello, world!</h1></body></html>"
|
22
|
+
```
|
23
|
+
|
10
24
|
Papercraft is an HTML templating engine for Ruby that offers the following
|
11
25
|
features:
|
12
26
|
|
13
|
-
- HTML templating using plain Ruby syntax
|
27
|
+
- HTML and XML templating using plain Ruby syntax
|
14
28
|
- Minimal boilerplate
|
15
29
|
- Mix logic and tags freely
|
16
|
-
-
|
17
|
-
- Automatic HTML escaping
|
30
|
+
- Automatic HTML and XML escaping
|
18
31
|
- Composable components
|
32
|
+
- Explicit parameter passing to nested components
|
19
33
|
- 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!
|
34
|
+
- Built-in support for rendering [Markdown](#emitting-markdown)
|
25
35
|
|
26
36
|
With Papercraft you can structure your templates as nested HTML components, in a
|
27
37
|
somewhat similar fashion to React.
|
@@ -48,7 +58,8 @@ To use Papercraft in your code just require it:
|
|
48
58
|
require 'papercraft'
|
49
59
|
```
|
50
60
|
|
51
|
-
To create a template use `Papercraft.new` or the global method
|
61
|
+
To create a template use `Papercraft::Component.new` or the global method
|
62
|
+
`Kernel#H`:
|
52
63
|
|
53
64
|
```ruby
|
54
65
|
# can also use Papercraft.new
|
@@ -114,8 +125,9 @@ H { p "foobar", class: 'important' }.render #=> "<p class=\"important\">foobar</
|
|
114
125
|
|
115
126
|
## Template parameters
|
116
127
|
|
117
|
-
|
118
|
-
template on
|
128
|
+
In Papercraft, parameters are always passed explicitly. This means that template
|
129
|
+
parameters are specified as block parameters, and are passed to the template on
|
130
|
+
rendering:
|
119
131
|
|
120
132
|
```ruby
|
121
133
|
greeting = H { |name| h1 "Hello, #{name}!" }
|
@@ -328,110 +340,43 @@ H { str 'hi&lo' }.render #=> "hi&lo"
|
|
328
340
|
|
329
341
|
## Emitting Markdown
|
330
342
|
|
331
|
-
|
343
|
+
Markdown is rendered using the
|
344
|
+
[Kramdown](https://kramdown.gettalong.org/index.html) gem. To emit Markdown, use
|
345
|
+
`#emit_markdown`:
|
332
346
|
|
333
347
|
```ruby
|
334
348
|
template = H { |md| div { emit_markdown md } }
|
335
|
-
template.render("Here's some *Markdown*") #=> "<div>Here's some <em>Markdown</em
|
349
|
+
template.render("Here's some *Markdown*") #=> "<div><p>Here's some <em>Markdown</em><p>\n</div>"
|
336
350
|
```
|
337
351
|
|
338
|
-
|
339
|
-
|
340
|
-
|
341
|
-
together pieces of HTML. Feel free to explore the API!
|
352
|
+
[Kramdown
|
353
|
+
options](https://kramdown.gettalong.org/options.html#available-options) can be
|
354
|
+
specified by adding them to the `#emit_markdown` call:
|
342
355
|
|
343
|
-
|
356
|
+
```ruby
|
357
|
+
template = H { |md| div { emit_markdown md, auto_ids: false } }
|
358
|
+
template.render("# title") #=> "<div><h1>title</h1></div>"
|
359
|
+
```
|
344
360
|
|
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:
|
361
|
+
The default Kramdown options are:
|
348
362
|
|
349
363
|
```ruby
|
350
|
-
|
351
|
-
|
352
|
-
|
353
|
-
|
354
|
-
|
355
|
-
li { emit item_component }
|
356
|
-
}
|
357
|
-
}
|
358
|
-
}
|
359
|
-
}
|
364
|
+
{
|
365
|
+
entity_output: :numeric,
|
366
|
+
syntax_highlighter: :rouge,
|
367
|
+
input: 'GFM',
|
368
|
+
hard_wrap: false
|
360
369
|
}
|
361
|
-
|
362
|
-
TodoItem = H {
|
363
|
-
span item.text, class: item.completed ? 'completed' : 'pending'
|
364
|
-
}
|
365
|
-
|
366
|
-
def todo_list(items)
|
367
|
-
H {
|
368
|
-
div { List(items, TodoItem) }
|
369
|
-
}
|
370
|
-
end
|
371
370
|
```
|
372
371
|
|
373
|
-
|
374
|
-
|
375
|
-
#### `Papercraft#initialize(**context, &block)` a.k.a. `Kernel#H`
|
376
|
-
|
377
|
-
- `context`: local context hash
|
378
|
-
- `block`: template block
|
372
|
+
The deafult options can be configured by accessing
|
373
|
+
`Papercraft::HTML.kramdown_options`:
|
379
374
|
|
380
|
-
|
381
|
-
|
382
|
-
|
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
|
410
|
-
|
411
|
-
Caches the markup in the given block, storing it in the Papercraft cache store.
|
412
|
-
If a cache entry for the given block is found, it will be used instead of
|
413
|
-
invoking the block. If one or more variables given, those will be used to create
|
414
|
-
a separate cache entry.
|
415
|
-
|
416
|
-
#### `#context`
|
417
|
-
|
418
|
-
Accesses the [global context](#global-context).
|
419
|
-
|
420
|
-
#### `#emit(object)` a.k.a. `#e(object)`
|
421
|
-
|
422
|
-
- `object`: `Proc`, `Papercraft` instance or `String`
|
423
|
-
|
424
|
-
Adds the given object to the current template. If a `String` is given, it is
|
425
|
-
rendered verbatim, i.e. without escaping.
|
426
|
-
|
427
|
-
#### `html5(&block)`
|
428
|
-
|
429
|
-
- `block`: inner HTML block
|
430
|
-
|
431
|
-
Adds an HTML5 `doctype` tag, followed by an `html` tag with the given block.
|
432
|
-
|
433
|
-
#### `#text(data)`
|
375
|
+
```ruby
|
376
|
+
Papercraft::HTML.kramdown_options[:auto_ids] = false
|
377
|
+
```
|
434
378
|
|
435
|
-
|
379
|
+
## Documentation
|
436
380
|
|
437
|
-
|
381
|
+
The complete documentation for this library can be found
|
382
|
+
[here](https://www.rubydoc.info/gems/papercraft).
|
data/lib/papercraft/html.rb
CHANGED
@@ -1,9 +1,10 @@
|
|
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
|
-
|
7
|
+
module Papercraft
|
7
8
|
# HTML Markup extensions
|
8
9
|
module HTML
|
9
10
|
# Emits the p tag (overrides Object#p)
|
@@ -42,5 +43,28 @@ module Papercraft
|
|
42
43
|
end
|
43
44
|
link(**attributes)
|
44
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
|
45
69
|
end
|
46
70
|
end
|
data/lib/papercraft/version.rb
CHANGED
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: papercraft
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: '0.9'
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Sharon Rosner
|
@@ -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
|