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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: c4c0fe32e16955ce1cd02692f9c128243e3c7dcab8e55a0eca02e2a158d11e4d
4
- data.tar.gz: 85e92867bb922c53924d2205f8db804f5aee7b41dd67d656ee49ea0a4eb7bf50
3
+ metadata.gz: c4ffb6c46838fb14026e86fdd23fcdaf02e96c54cc083f61de0700a00a3887da
4
+ data.tar.gz: 5d55ddacece2a9458bd3f1b1b44bdaf686e31e1295572d55a0ee83a16af29a26
5
5
  SHA512:
6
- metadata.gz: 0ad40b936ef85923d186925342c25631066657dec4a1ebc8c7cb5adbf704d403fcb82ced1e922e4369a4cb7e036769fd96728ab4480d6e48cf1c4916bf762ae4
7
- data.tar.gz: 90c2bc2f3cdd12cb919ba4f5d2d301a9cf49d11c4441a18d59c6825cb0e35a15fce7c9027a54a18634c2137cc8640a392924394ce8e970c96680b0076b0a34a1
6
+ metadata.gz: db21b71f5bc84d6fc9244d3ef2d918d5512c70aa5fe51c0149e968c85377287681ee5ff1d40b9c84b52861eeb683254f7a3a4bf09e0d3a82457950a9c7c61dc0
7
+ data.tar.gz: c7532b43834fe459df96cbbf623493a553a5cbafe8611ae77f682af9e29851fcaa08f68c3d2c246f9a224ba92cd19c04954859b11a6a041222b57c44f5d1031f
data/README.md CHANGED
@@ -1,8 +1,36 @@
1
1
  # Stimulizer
2
2
 
3
- Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/stimulizer`. To experiment with that code, run `bin/console` for an interactive prompt.
3
+ Easily work with StimulusJS `data-*` attributes in ViewComponents, Phlex templates, etc.
4
4
 
5
- TODO: Delete this and the text above, and describe your gem
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
- TODO: Write usage instructions here
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
 
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Stimulizer
4
- VERSION = "0.1.0"
4
+ VERSION = "0.1.1"
5
5
  end
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 = build_stimulus_hash(*args)
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}#{stimulus_controller}##{function}"
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-#{stimulus_controller}-#{LuckyCase.dash_case(key.to_s)}-param"] = value
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-#{stimulus_controller}-#{LuckyCase.dash_case(key.to_s)}-value"] = value
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-#{stimulus_controller}-#{LuckyCase.dash_case(key.to_s)}-class"] = value
129
+ hash[:"data-#{local_controller_name}-#{LuckyCase.dash_case(key.to_s)}-class"] = value
120
130
  end
121
131
 
122
- hash[:"data-#{stimulus_controller}-target"] = target if target
132
+ hash[:"data-#{local_controller_name}-target"] = target if target
123
133
  end
124
134
  end
125
135
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: stimulizer
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.1.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Matt E Patterson