objective_elements 0.2.0 → 0.3.0
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/README.md +57 -31
- data/lib/objective_elements/single_tag.rb +38 -6
- data/lib/objective_elements/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: 57bc0f1dbe710d5d20390881d1eb5fdedf7fbb09efc74f445905ddc3428158e2
|
4
|
+
data.tar.gz: 83f0691aad60a3f0c24d1faf270938449ddd8d2af90e2ebbc508bb32e18447ed
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 5e3a65c6eaa857398f5318f45fc37e871c4507830e40aa339cf2e00bd79a9d6979c3c350f7be92f096f21d5c2ef297853b7efd005b252522e5aaa562fe4f743e
|
7
|
+
data.tar.gz: 8e9d6e50e800803981430f7aaafe7914850024a79a90452aed6f6fe5f3ed45e5f617062d85b2a2f22094469af197ab2e3568a2292b99affeb3b34474b3401d97
|
data/README.md
CHANGED
@@ -3,13 +3,18 @@
|
|
3
3
|
This is a tiny gem that builds nicely formatted HTML using sane, readable Ruby. I use it for jekyll
|
4
4
|
plugins, but you can use it anywhere. It's ~100 lines, tested with rspec, and has no dependencies.
|
5
5
|
|
6
|
-
|
6
|
+
It doesn't actually know any HTML, just how to format it.
|
7
|
+
|
8
|
+
This is meant to be less involved and more flexible than nokogiri's XML/HTML generator. There's no
|
9
|
+
DSL to learn, and no cleverness to wrap your mind around. Its specialty is taking fragmented,
|
10
|
+
disjointed information and condensing it into a string of properly formatted HTML. It's as agnostic
|
11
|
+
as possible on the input, while being extremely consistent with its output.
|
7
12
|
|
8
13
|
## How it works:
|
9
14
|
|
10
15
|
* Instantiate a `SingleTag` or `DoubleTag`
|
11
16
|
|
12
|
-
* Add attributes & content
|
17
|
+
* Add attributes & content. Nest tags infinitely.
|
13
18
|
|
14
19
|
* Render it with `.to_s`
|
15
20
|
|
@@ -21,14 +26,15 @@ you only need sometimes, it turns into a horrible mess.
|
|
21
26
|
|
22
27
|
The problem, of course, is that building long, complex, varying blocks of text with string
|
23
28
|
concatenation and interpolation is fragile, unreadable, and painful. You know this, but you're not
|
24
|
-
going to write an entirely new class or pull in some big new dependency just for 10 lines of HTML
|
25
|
-
|
29
|
+
going to write an entirely new class or pull in some big new dependency just for 10 lines of HTML,
|
30
|
+
so instead you hammer through it and end up with code like this:
|
26
31
|
|
27
32
|
```ruby
|
28
33
|
picture_tag = "<picture>\n"\
|
29
|
-
|
30
|
-
|
31
|
-
"#{
|
34
|
+
"#{source_tags}"\
|
35
|
+
"#{markdown_escape * 4}"\
|
36
|
+
"<img src=\"#{url}#{instance['source_default'][:generated_src]}\" "\
|
37
|
+
"#{html_attr_string}>\n"\"#{markdown_escape * 2}</picture>\n"
|
32
38
|
```
|
33
39
|
|
34
40
|
or this:
|
@@ -56,11 +62,15 @@ p.to_s
|
|
56
62
|
# <p>
|
57
63
|
# </p>
|
58
64
|
|
59
|
-
# Add attributes as a hash, values can be
|
65
|
+
# Add attributes as a hash. keys can be strings or symbols, values can be arrays or strings:
|
60
66
|
p.add_attributes class: 'stumpy grumpy', 'id' => 'the-ugly-one'
|
61
|
-
|
67
|
+
|
68
|
+
# Add attributes as a string!
|
62
69
|
p.add_attributes 'class="slimy" data-awesomeness="11"'
|
70
|
+
|
71
|
+
# Add content. It can be anything, or an array of anythings.
|
63
72
|
p.add_content "Icky"
|
73
|
+
|
64
74
|
p.to_s
|
65
75
|
# <p class="stumpy grumpy slimy" id="the-ugly-one" data-awesomeness="11">
|
66
76
|
# Icky
|
@@ -69,21 +79,22 @@ p.to_s
|
|
69
79
|
# Want a oneliner?
|
70
80
|
p.oneline = true
|
71
81
|
p.to_s
|
72
|
-
# <p class="stumpy
|
82
|
+
# <p class="stumpy grumpy slimy" id="the-ugly-one" data-awesomeness="11">Icky</p>
|
73
83
|
p.oneline = false
|
74
84
|
|
75
|
-
# Build
|
85
|
+
# Build a tag all at once:
|
76
86
|
p.add_content DoubleTag.new(
|
77
87
|
'a',
|
78
88
|
content: 'Link!',
|
79
89
|
attributes: {href: 'awesome-possum.com'},
|
80
90
|
oneline: true
|
81
91
|
)
|
82
|
-
|
92
|
+
|
93
|
+
# Add a parent tag:
|
83
94
|
div = p.add_parent DoubleTag.new 'div'
|
84
95
|
|
85
96
|
# Ruby implicitly calls .to_s on things when you try to perform string functions with them, so
|
86
|
-
#
|
97
|
+
# this works:
|
87
98
|
"#{div}"
|
88
99
|
# <div>
|
89
100
|
# <p class="stumpy mopey grumpy slimy" id="the-ugly-one" data-awesomeness="11">
|
@@ -93,6 +104,11 @@ div = p.add_parent DoubleTag.new 'div'
|
|
93
104
|
# </div>
|
94
105
|
|
95
106
|
```
|
107
|
+
|
108
|
+
For complete example usage, see [jekyll_icon_list](https://github.com/rbuchberger/jekyll_icon_list), or
|
109
|
+
this [pull request](https://github.com/robwierzbowski/jekyll-picture-tag/pull/87/commits/d6b2deca0f19f173251a2984037e5e5f8d7c21d1)
|
110
|
+
to [jekyll-picture-tag](https://github.com/robwierzbowski/jekyll-picture-tag).
|
111
|
+
|
96
112
|
## Installation
|
97
113
|
|
98
114
|
```ruby
|
@@ -119,24 +135,24 @@ So we're on the same page, here's the terminology I'm using:
|
|
119
135
|
- c - content
|
120
136
|
- d - closing tag
|
121
137
|
|
138
|
+
|
139
|
+
## Usage
|
140
|
+
|
122
141
|
There are 2 classes: `SingleTag` is the base class, and `DoubleTag` inherits from it. A `SingleTag`
|
123
142
|
is a self-closing tag, meaning it has no content and no closing tag. A `DoubleTag` is the other
|
124
143
|
kind.
|
125
144
|
|
126
|
-
## Usage
|
127
|
-
|
128
145
|
### SingleTag Properties:
|
129
146
|
|
130
147
|
#### element
|
131
148
|
- String
|
132
149
|
- Mandatory
|
133
150
|
- Which type of tag it is, such as 'hr' or 'img'
|
134
|
-
- Defined on initialization, cannot be changed afterwards. (Should it be? I'm on the fence about it.)
|
135
151
|
|
136
152
|
#### attributes
|
137
153
|
- Hash
|
138
154
|
- Optional
|
139
|
-
- Keys are symbols, values are arrays of strings
|
155
|
+
- Keys are stored as symbols, values are stored as arrays of strings: `{class: ['stumpy', 'slimy']}`
|
140
156
|
- add them with `.add_attributes`, which can accept a few different formats.
|
141
157
|
|
142
158
|
### SingleTag Methods (that you care about)
|
@@ -145,20 +161,29 @@ kind.
|
|
145
161
|
|
146
162
|
`.to_s` - The big one. Returns your HTML as a string, nondestructively.
|
147
163
|
|
164
|
+
`.add_attributes(new)` - The strongly recommended way to add new attributes. Can accept a hash (keys
|
165
|
+
can be either symbols or strings, values can be either arrays or strings), or a string in the
|
166
|
+
standard HTML syntax (`attribute="value" attribute2="value2 value3"`). Returns self.
|
167
|
+
|
148
168
|
`.reset_attributes(new)` - Deletes all attributes, calls add_attributes on supplied argument if
|
149
169
|
given.
|
150
170
|
|
151
|
-
`.
|
152
|
-
|
153
|
-
|
171
|
+
`.delete_attributes(keys)` - Accepts a single attribute, or an array of attributes (keys or
|
172
|
+
strings), and deletes it.
|
173
|
+
|
174
|
+
`.rewrite_attributes` - Accepts anything add_attributes understands, but replaces existing
|
175
|
+
attributes instead of appending to them.
|
154
176
|
|
155
177
|
`.add_parent(DoubleTag)` - returns supplied DoubleTag, with self added as a child.
|
156
178
|
|
157
|
-
|
179
|
+
|
180
|
+
|
181
|
+
`attr_reader :attributes`
|
182
|
+
`attr_accessor :element`
|
158
183
|
|
159
184
|
### DoubleTag Properties:
|
160
185
|
|
161
|
-
#### `DoubleTag` Inherits all of `SingleTag`'s properties and methods,
|
186
|
+
#### `DoubleTag` Inherits all of `SingleTag`'s properties and methods, and adds content and a closing tag.
|
162
187
|
|
163
188
|
#### content
|
164
189
|
|
@@ -184,7 +209,9 @@ value3"`). Returns self.
|
|
184
209
|
content.
|
185
210
|
|
186
211
|
`add_content(anything)` - Smart enough to handle both arrays and not-arrays without getting dorked
|
187
|
-
up.
|
212
|
+
up. When given an array, its elements will be appended to the content array. When given a single
|
213
|
+
item, that item will be inserted at the end of the array. (Remember each element in the content
|
214
|
+
array gets at least one line!)
|
188
215
|
|
189
216
|
`attr_accessor: content` - You can modify the content array directly if you like. If you're just
|
190
217
|
adding items, you should use `.add_content`
|
@@ -194,8 +221,8 @@ appropriate indentation applied, this is how you can get it.
|
|
194
221
|
|
195
222
|
## Configuration
|
196
223
|
|
197
|
-
Indentation is defined by the `indent` method on the DoubleTag class
|
198
|
-
it:
|
224
|
+
Indentation is defined by the `indent` method on the DoubleTag class, which is two markdown-escaped
|
225
|
+
spaces by default ("\ \ "). If you'd like to change it:
|
199
226
|
|
200
227
|
1. Make a new class, inherit from DoubleTag.
|
201
228
|
2. Override `indent` with whatever you want.
|
@@ -223,11 +250,10 @@ MyDoubleTag.new('p', content: 'hello').to_s
|
|
223
250
|
|
224
251
|
## Limitations
|
225
252
|
|
226
|
-
* It doesn't know a single HTML element on its own, so it does nothing to ensure your
|
227
|
-
HTML is valid. Garbage in, garbage out.
|
253
|
+
* It doesn't know a single HTML element on its own, so it does nothing to ensure your HTML is valid.
|
228
254
|
|
229
|
-
* A parent tag can't put siblings on the same line. You can either
|
230
|
-
|
255
|
+
* A parent tag can't put siblings on the same line. You can either do this (with `oneline: true` on
|
256
|
+
the strong tag):
|
231
257
|
|
232
258
|
```html
|
233
259
|
|
@@ -247,7 +273,7 @@ MyDoubleTag.new('p', content: 'hello').to_s
|
|
247
273
|
text.
|
248
274
|
|
249
275
|
```
|
250
|
-
But you can't do this without string interpolation:
|
276
|
+
But you can't do this without string interpolation or something:
|
251
277
|
|
252
278
|
```html
|
253
279
|
|
@@ -258,7 +284,7 @@ MyDoubleTag.new('p', content: 'hello').to_s
|
|
258
284
|
source code layout.
|
259
285
|
|
260
286
|
* If you set 'oneline: true' on a parent DoubleTag, but not all its children DoubleTags, the output
|
261
|
-
will not be pretty. I advise against it.
|
287
|
+
will not be pretty. I advise against it. Handling this situation is on the TODO list.
|
262
288
|
|
263
289
|
* It doesn't wrap long lines of text, and it doesn't indent text with newlines embedded. It's on the
|
264
290
|
TODO list.
|
@@ -18,6 +18,8 @@ class SingleTag
|
|
18
18
|
def reset_attributes(new = nil)
|
19
19
|
@attributes = {}
|
20
20
|
add_attributes(new) if new
|
21
|
+
|
22
|
+
self
|
21
23
|
end
|
22
24
|
|
23
25
|
# This is the only way we add new attributes. Flexible about what you give
|
@@ -30,8 +32,36 @@ class SingleTag
|
|
30
32
|
else
|
31
33
|
add_hash_attributes(new)
|
32
34
|
end
|
35
|
+
|
36
|
+
self
|
37
|
+
end
|
38
|
+
alias add_attribute add_attributes
|
39
|
+
|
40
|
+
def delete_attributes(keys)
|
41
|
+
# accepts an array or a single element
|
42
|
+
to_delete = if keys.is_a? Array
|
43
|
+
keys.map(&:to_sym)
|
44
|
+
else
|
45
|
+
[keys.to_sym]
|
46
|
+
end
|
47
|
+
|
48
|
+
to_delete.each { |k| @attributes.delete k }
|
49
|
+
|
50
|
+
self
|
51
|
+
end
|
52
|
+
alias delete_attribute delete_attributes
|
53
|
+
|
54
|
+
def rewrite_attribute(new)
|
55
|
+
formatted_new = if new.is_a? String
|
56
|
+
hashify_attributes(new)
|
57
|
+
else
|
58
|
+
new.transform_keys(&:to_sym)
|
59
|
+
end
|
60
|
+
|
61
|
+
delete_attributes formatted_new.keys
|
62
|
+
|
63
|
+
add_hash_attributes formatted_new
|
33
64
|
end
|
34
|
-
alias_method :add_attribute, :add_attributes
|
35
65
|
|
36
66
|
# Turns attributes into a string we can insert.
|
37
67
|
def render_attributes
|
@@ -64,16 +94,19 @@ class SingleTag
|
|
64
94
|
|
65
95
|
private
|
66
96
|
|
67
|
-
def add_string_attributes(
|
97
|
+
def add_string_attributes(new_string)
|
98
|
+
add_hash_attributes hashify_attributes new_string
|
99
|
+
end
|
100
|
+
|
101
|
+
def hashify_attributes(new_string)
|
68
102
|
# looking for something like:
|
69
103
|
# 'class="something something-else" id="my-id"'
|
70
104
|
new_hash = {}
|
71
|
-
|
105
|
+
new_string.scan(/ ?([^="]+)="([^"]+)"/).each do |m|
|
72
106
|
# [['class','something something-else'],['id','my-id']]
|
73
107
|
new_hash[m.shift] = m.pop
|
74
108
|
end
|
75
|
-
|
76
|
-
add_hash_attributes(new_hash)
|
109
|
+
new_hash
|
77
110
|
end
|
78
111
|
|
79
112
|
def add_hash_attributes(new)
|
@@ -88,5 +121,4 @@ class SingleTag
|
|
88
121
|
end
|
89
122
|
self
|
90
123
|
end
|
91
|
-
|
92
124
|
end
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: objective_elements
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: 0.3.0
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Robert Buchberger
|
8
8
|
autorequire:
|
9
9
|
bindir: exe
|
10
10
|
cert_chain: []
|
11
|
-
date: 2018-10-
|
11
|
+
date: 2018-10-12 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: bundler
|