stimulizer 0.1.0 → 0.1.1
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 +144 -3
- data/lib/stimulizer/version.rb +1 -1
- data/lib/stimulizer.rb +17 -7
- metadata +1 -1
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: c4ffb6c46838fb14026e86fdd23fcdaf02e96c54cc083f61de0700a00a3887da
|
4
|
+
data.tar.gz: 5d55ddacece2a9458bd3f1b1b44bdaf686e31e1295572d55a0ee83a16af29a26
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: db21b71f5bc84d6fc9244d3ef2d918d5512c70aa5fe51c0149e968c85377287681ee5ff1d40b9c84b52861eeb683254f7a3a4bf09e0d3a82457950a9c7c61dc0
|
7
|
+
data.tar.gz: c7532b43834fe459df96cbbf623493a553a5cbafe8611ae77f682af9e29851fcaa08f68c3d2c246f9a224ba92cd19c04954859b11a6a041222b57c44f5d1031f
|
data/README.md
CHANGED
@@ -1,8 +1,36 @@
|
|
1
1
|
# Stimulizer
|
2
2
|
|
3
|
-
|
3
|
+
Easily work with StimulusJS `data-*` attributes in ViewComponents, Phlex templates, etc.
|
4
4
|
|
5
|
-
|
5
|
+
This gem is particularly handy in ViewComponents and Phlex when you have a 1-1 relationship between a component and a Stimulus controller, especially when using 'sidecar' controllers.
|
6
|
+
|
7
|
+
For example:
|
8
|
+
|
9
|
+
### ViewComponent
|
10
|
+
```ruby
|
11
|
+
class Mynamespace::Deeper::ButtonsGridComponent < ApplicationComponent
|
12
|
+
# ...
|
13
|
+
```
|
14
|
+
#### Before
|
15
|
+
```html
|
16
|
+
<div
|
17
|
+
data-controller="mynamespace--deeper--buttons-grid-component"
|
18
|
+
data-mynamespace--deeper--buttons-grid-component-url-value="http://example.com"
|
19
|
+
data-mynamespace--deeper--buttons-grid-component-url-color="#ff0000"
|
20
|
+
data-action="click->data-mynamespace--deeper--buttons-grid-component#doSomething"
|
21
|
+
>
|
22
|
+
```
|
23
|
+
|
24
|
+
#### After
|
25
|
+
```html
|
26
|
+
<div
|
27
|
+
<%= stimulus(
|
28
|
+
:controller,
|
29
|
+
values: {url: "http://example.com", color: "#ff0000"},
|
30
|
+
action: "click->doSomething"
|
31
|
+
)%>
|
32
|
+
>
|
33
|
+
```
|
6
34
|
|
7
35
|
## Installation
|
8
36
|
|
@@ -21,8 +49,121 @@ Or install it yourself as:
|
|
21
49
|
$ gem install stimulizer
|
22
50
|
|
23
51
|
## Usage
|
52
|
+
Include this in your model:
|
53
|
+
|
54
|
+
```ruby
|
55
|
+
class MyComponent < ApplicationComponent
|
56
|
+
include Stimulizer
|
57
|
+
# ...
|
58
|
+
```
|
59
|
+
|
60
|
+
Render the stimulusjs data strings into your template...
|
61
|
+
|
62
|
+
```html
|
63
|
+
<!-- use the derived controller name -->
|
64
|
+
<%= stimulus(:controller) %>
|
65
|
+
|
66
|
+
<!-- specify the controller explicity, and/or add more controllers space-separated -->
|
67
|
+
<%= stimulus(controller: "another foo")
|
68
|
+
|
69
|
+
<!-- Note: 'action' is singular because it works like 'data-action' -->
|
70
|
+
<%= stimulus(action: "click->doThing")
|
71
|
+
|
72
|
+
<!-- but you can have multiple actions separated by spaces -->
|
73
|
+
<%= stimulus(action: "click->doThing mouseup->otherThing")
|
74
|
+
|
75
|
+
<!-- you can also skip the event, just like usual -->
|
76
|
+
<%= stimulus(action: "doThing")
|
77
|
+
|
78
|
+
<!--
|
79
|
+
target for this element (if you need to also target it for other controllers, you'll have to do that manually with the old 'data-blah-target=' approach)
|
80
|
+
-->
|
81
|
+
<%= stimulus(target: "button")
|
82
|
+
|
83
|
+
<!-- supports the 'classes' feature -->
|
84
|
+
<%= stimulus(classes: {foo: "text-red-500", busy: "opacity-50 animate-spin"})
|
85
|
+
|
86
|
+
<!-- supports the 'values' feature -->
|
87
|
+
<%= stimulus(values: {url: "https://example.com"})
|
88
|
+
|
89
|
+
<!-- supports the 'params' feature -->
|
90
|
+
<%= stimulus(params: {foo: "bar", this_thing: "whatever"})
|
91
|
+
```
|
92
|
+
... or combine them:
|
93
|
+
```
|
94
|
+
<%= stimulus(:controller, target: "button", action: "click->doThing")
|
95
|
+
```
|
96
|
+
|
97
|
+
## Options
|
98
|
+
|
99
|
+
### `stimulize`
|
100
|
+
Use the `stimulize` method after including the module to set some config options...
|
101
|
+
|
102
|
+
#### `ignore_prefix`
|
103
|
+
Use the `ignore_prefix` option to chop off some of the namespacing if you want to shorten up those crazy-long controller filenames.
|
104
|
+
```ruby
|
105
|
+
stimulize ignore_prefix: "Components::"
|
106
|
+
```
|
107
|
+
|
108
|
+
#### `output`
|
109
|
+
Use the `output` option to change from an html-style string of data attributes (default) to a Hash of data attributes, useful in other circumstances, like tag builders and Phlex views.
|
110
|
+
```ruby
|
111
|
+
stimulize output: :hash
|
112
|
+
```
|
113
|
+
|
114
|
+
## Overriding the derived controller name
|
115
|
+
My main use case for Stimulizer is with so-called 'sidecar' javascript. That is, if I have a component in the filepath `components/foo/bar/other/button_component.rb`, I will also have a stimulus controller at `components/foo/bar/other/button_component_controller.js`.
|
116
|
+
|
117
|
+
**In this case, Stimulizer will auto-derive the controller name properly.**
|
118
|
+
|
119
|
+
If you're not doing things this way, you may need to manually set your controller name in each component/template...
|
24
120
|
|
25
|
-
|
121
|
+
```ruby
|
122
|
+
def stimulus_controller
|
123
|
+
"whatever--name--you-want-here"
|
124
|
+
end
|
125
|
+
```
|
126
|
+
|
127
|
+
**or...**
|
128
|
+
|
129
|
+
You can also pass the controller name directly to the `stimulus()` method. This starts to become less automagical, but still handy in reducing the repetition of those controller names.
|
130
|
+
|
131
|
+
```ruby
|
132
|
+
<div
|
133
|
+
<%= stimulus(
|
134
|
+
controller_name: "my--fancy--buttons",
|
135
|
+
action: "click->show",
|
136
|
+
values: {url: "example.com"}
|
137
|
+
) %>
|
138
|
+
>
|
139
|
+
|
140
|
+
# => <div data-controller='my--fancy--buttons' data-action='click->my--fancy--buttons#show' data-my--fancy--buttons-url-value="example.com">
|
141
|
+
```
|
142
|
+
|
143
|
+
## Using with Phlex (or if you want a hash for some other reason)
|
144
|
+
By default, Stimulizer returns a html-style string of `data-*` attributes from the `stimulus()` method. But if you're using something like Phlex templates, or if you want to use this with a tag-building method, you might want the original Hash instead. You have two options:
|
145
|
+
|
146
|
+
### 1. Class-level configuration
|
147
|
+
```ruby
|
148
|
+
module Views
|
149
|
+
class ApplicationView < Phlex::View
|
150
|
+
include Stimulizer
|
151
|
+
stimulize output: :hash
|
152
|
+
```
|
153
|
+
|
154
|
+
### 2. Specifically ask for a hash with `stimulus_hash` instead
|
155
|
+
```ruby
|
156
|
+
stimulus_hash(:controller, action: "click->doThis")
|
157
|
+
```
|
158
|
+
|
159
|
+
## Phlex: Destructuring for the win!
|
160
|
+
Thanks to [@joeldrapper](https://github.com/joeldrapper) for suggesting this and for inspiring the idea of this gem. You can use destructuring to great effect in Phlex views:
|
161
|
+
|
162
|
+
```ruby
|
163
|
+
div(**stimulus(:controller, action: "click->show"), class: "text-red-500") do
|
164
|
+
# ...
|
165
|
+
```
|
166
|
+
*Note that this example is assuming you've turned on `:hash` mode as above. You could also use `**stimulus_hash()` in the same way.*
|
26
167
|
|
27
168
|
## Development
|
28
169
|
|
data/lib/stimulizer/version.rb
CHANGED
data/lib/stimulizer.rb
CHANGED
@@ -31,8 +31,12 @@ module Stimulizer
|
|
31
31
|
build_stimulus_controller
|
32
32
|
end
|
33
33
|
|
34
|
+
def stimulus_hash(*args)
|
35
|
+
build_stimulus_hash(*args)
|
36
|
+
end
|
37
|
+
|
34
38
|
def stimulus(*args)
|
35
|
-
output =
|
39
|
+
output = stimulus_hash(*args)
|
36
40
|
return output if _stimulizer_opts[:output] == :hash
|
37
41
|
|
38
42
|
raw(
|
@@ -71,7 +75,8 @@ module Stimulizer
|
|
71
75
|
# ... or combine them:
|
72
76
|
#
|
73
77
|
# <%= stimulus(:controller, target: "button", action: "click->doThing")
|
74
|
-
def build_stimulus_hash(default_controller = false, controller: nil, target: nil, action: nil, params: nil, values: nil, classes: nil)
|
78
|
+
def build_stimulus_hash(default_controller = false, controller_name: nil, controller: nil, target: nil, action: nil, params: nil, values: nil, classes: nil)
|
79
|
+
raise ArgumentError(":controller_name specified, but blank") if controller_name&.blank?
|
75
80
|
raise ArgumentError(":controller specified, but blank") if controller&.blank?
|
76
81
|
raise ArgumentError(":target specified, but blank") if target&.blank?
|
77
82
|
raise ArgumentError(":action specified, but blank") if action&.blank?
|
@@ -82,8 +87,13 @@ module Stimulizer
|
|
82
87
|
{}.tap do |hash|
|
83
88
|
hash[:"data-controller"] = ""
|
84
89
|
|
90
|
+
local_controller_name = stimulus_controller
|
91
|
+
|
85
92
|
if default_controller.to_s.downcase.to_sym == :controller
|
86
93
|
hash[:"data-controller"] += " #{stimulus_controller}"
|
94
|
+
elsif controller_name.present?
|
95
|
+
hash[:"data-controller"] += " #{controller_name}"
|
96
|
+
local_controller_name = controller_name
|
87
97
|
end
|
88
98
|
|
89
99
|
hash[:"data-controller"] += " #{controller}" if controller
|
@@ -100,7 +110,7 @@ module Stimulizer
|
|
100
110
|
if function.include?("#")
|
101
111
|
"#{event}#{function}"
|
102
112
|
else
|
103
|
-
"#{event}#{
|
113
|
+
"#{event}#{local_controller_name}##{function}"
|
104
114
|
end
|
105
115
|
end.compact
|
106
116
|
|
@@ -108,18 +118,18 @@ module Stimulizer
|
|
108
118
|
end
|
109
119
|
|
110
120
|
params&.each do |key, value|
|
111
|
-
hash[:"data-#{
|
121
|
+
hash[:"data-#{local_controller_name}-#{LuckyCase.dash_case(key.to_s)}-param"] = value
|
112
122
|
end
|
113
123
|
|
114
124
|
values&.each do |key, value|
|
115
|
-
hash[:"data-#{
|
125
|
+
hash[:"data-#{local_controller_name}-#{LuckyCase.dash_case(key.to_s)}-value"] = value
|
116
126
|
end
|
117
127
|
|
118
128
|
classes&.each do |key, value|
|
119
|
-
hash[:"data-#{
|
129
|
+
hash[:"data-#{local_controller_name}-#{LuckyCase.dash_case(key.to_s)}-class"] = value
|
120
130
|
end
|
121
131
|
|
122
|
-
hash[:"data-#{
|
132
|
+
hash[:"data-#{local_controller_name}-target"] = target if target
|
123
133
|
end
|
124
134
|
end
|
125
135
|
end
|