stimulizer 0.1.0 → 0.1.2
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 +27 -7
- metadata +6 -6
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: b7ff225da6cb516af29d0cd30787586c6c13a9ac6db4bb26eaa2e8dc11f832d0
|
|
4
|
+
data.tar.gz: 88c7d3e6259d1052c19e254f15402ff859ccd8e480d21254b13f29f141d80ff6
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: f4b33e806d801cebce6220f0c6d63ed14facc335fd6e8eeb38c893b38fffba85e8fa6cde19b30d9a42d0bea36dcf7e833b895c2648a54c9a8d9da231cfb26da3
|
|
7
|
+
data.tar.gz: d7049053a80543023684f9581c37ac4d32b11a6ab835079af617a9a6a7a12850cabcad8b316d3b4ecd8c4053bb693d2490f7be98de6ad4ffda4e323db60d0a4a
|
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 class:
|
|
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
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
|
+
require "stimulizer"
|
|
4
|
+
|
|
3
5
|
require "active_support/concern"
|
|
4
6
|
require "dry-configurable"
|
|
5
7
|
require "lucky_case"
|
|
@@ -31,8 +33,20 @@ module Stimulizer
|
|
|
31
33
|
build_stimulus_controller
|
|
32
34
|
end
|
|
33
35
|
|
|
36
|
+
def stimulus_hash(*args)
|
|
37
|
+
if args.size == 1 && !args.first.is_a?(Hash)
|
|
38
|
+
build_stimulus_hash(args.first)
|
|
39
|
+
elsif args.size == 1 && args.first.is_a?(Hash)
|
|
40
|
+
build_stimulus_hash(**args.first)
|
|
41
|
+
elsif args.size == 2 && args[1..].all? { |a| a.is_a?(Hash) }
|
|
42
|
+
build_stimulus_hash(args[0], **args[1..].first)
|
|
43
|
+
else
|
|
44
|
+
raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 1..2)"
|
|
45
|
+
end
|
|
46
|
+
end
|
|
47
|
+
|
|
34
48
|
def stimulus(*args)
|
|
35
|
-
output =
|
|
49
|
+
output = stimulus_hash(*args)
|
|
36
50
|
return output if _stimulizer_opts[:output] == :hash
|
|
37
51
|
|
|
38
52
|
raw(
|
|
@@ -71,7 +85,8 @@ module Stimulizer
|
|
|
71
85
|
# ... or combine them:
|
|
72
86
|
#
|
|
73
87
|
# <%= 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)
|
|
88
|
+
def build_stimulus_hash(default_controller = false, controller_name: nil, controller: nil, target: nil, action: nil, params: nil, values: nil, classes: nil)
|
|
89
|
+
raise ArgumentError(":controller_name specified, but blank") if controller_name&.blank?
|
|
75
90
|
raise ArgumentError(":controller specified, but blank") if controller&.blank?
|
|
76
91
|
raise ArgumentError(":target specified, but blank") if target&.blank?
|
|
77
92
|
raise ArgumentError(":action specified, but blank") if action&.blank?
|
|
@@ -82,8 +97,13 @@ module Stimulizer
|
|
|
82
97
|
{}.tap do |hash|
|
|
83
98
|
hash[:"data-controller"] = ""
|
|
84
99
|
|
|
100
|
+
local_controller_name = stimulus_controller
|
|
101
|
+
|
|
85
102
|
if default_controller.to_s.downcase.to_sym == :controller
|
|
86
103
|
hash[:"data-controller"] += " #{stimulus_controller}"
|
|
104
|
+
elsif controller_name.present?
|
|
105
|
+
hash[:"data-controller"] += " #{controller_name}"
|
|
106
|
+
local_controller_name = controller_name
|
|
87
107
|
end
|
|
88
108
|
|
|
89
109
|
hash[:"data-controller"] += " #{controller}" if controller
|
|
@@ -100,7 +120,7 @@ module Stimulizer
|
|
|
100
120
|
if function.include?("#")
|
|
101
121
|
"#{event}#{function}"
|
|
102
122
|
else
|
|
103
|
-
"#{event}#{
|
|
123
|
+
"#{event}#{local_controller_name}##{function}"
|
|
104
124
|
end
|
|
105
125
|
end.compact
|
|
106
126
|
|
|
@@ -108,18 +128,18 @@ module Stimulizer
|
|
|
108
128
|
end
|
|
109
129
|
|
|
110
130
|
params&.each do |key, value|
|
|
111
|
-
hash[:"data-#{
|
|
131
|
+
hash[:"data-#{local_controller_name}-#{LuckyCase.dash_case(key.to_s)}-param"] = value
|
|
112
132
|
end
|
|
113
133
|
|
|
114
134
|
values&.each do |key, value|
|
|
115
|
-
hash[:"data-#{
|
|
135
|
+
hash[:"data-#{local_controller_name}-#{LuckyCase.dash_case(key.to_s)}-value"] = value
|
|
116
136
|
end
|
|
117
137
|
|
|
118
138
|
classes&.each do |key, value|
|
|
119
|
-
hash[:"data-#{
|
|
139
|
+
hash[:"data-#{local_controller_name}-#{LuckyCase.dash_case(key.to_s)}-class"] = value
|
|
120
140
|
end
|
|
121
141
|
|
|
122
|
-
hash[:"data-#{
|
|
142
|
+
hash[:"data-#{local_controller_name}-target"] = target if target
|
|
123
143
|
end
|
|
124
144
|
end
|
|
125
145
|
end
|
metadata
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: stimulizer
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.1.
|
|
4
|
+
version: 0.1.2
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Matt E Patterson
|
|
8
|
-
autorequire:
|
|
8
|
+
autorequire:
|
|
9
9
|
bindir: exe
|
|
10
10
|
cert_chain: []
|
|
11
11
|
date: 2022-11-04 00:00:00.000000000 Z
|
|
@@ -52,7 +52,7 @@ dependencies:
|
|
|
52
52
|
- - ">="
|
|
53
53
|
- !ruby/object:Gem::Version
|
|
54
54
|
version: '0'
|
|
55
|
-
description:
|
|
55
|
+
description:
|
|
56
56
|
email:
|
|
57
57
|
- mattp@digimonkey.com
|
|
58
58
|
executables: []
|
|
@@ -81,7 +81,7 @@ metadata:
|
|
|
81
81
|
homepage_uri: https://github.com/mepatterson/stimulizer
|
|
82
82
|
source_code_uri: https://github.com/mepatterson/stimulizer
|
|
83
83
|
changelog_uri: https://github.com/mepatterson/stimulizer/blob/main/CHANGELOG.md
|
|
84
|
-
post_install_message:
|
|
84
|
+
post_install_message:
|
|
85
85
|
rdoc_options: []
|
|
86
86
|
require_paths:
|
|
87
87
|
- lib
|
|
@@ -96,8 +96,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
|
96
96
|
- !ruby/object:Gem::Version
|
|
97
97
|
version: '0'
|
|
98
98
|
requirements: []
|
|
99
|
-
rubygems_version: 3.
|
|
100
|
-
signing_key:
|
|
99
|
+
rubygems_version: 3.3.7
|
|
100
|
+
signing_key:
|
|
101
101
|
specification_version: 4
|
|
102
102
|
summary: Stimulizer provides convenience methods for working with StimulusJS in views,
|
|
103
103
|
templates, and components.
|