cable_ready 1.0.0 → 1.1.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.
Files changed (7) hide show
  1. checksums.yaml +4 -4
  2. data/Gemfile.lock +2 -2
  3. data/README.md +131 -31
  4. data/lib/cable_ready/broadcaster.rb +67 -15
  5. data/lib/cable_ready/version.rb +1 -1
  6. data/vendor/assets/javascripts/cable_ready.js +71 -29
  7. metadata +4 -4
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 13c675045811966ee490dd09ce772bda11f4280f
4
- data.tar.gz: b7b7a10cfd1c765d6a9c8f2400c3c2cc33c8ad88
3
+ metadata.gz: 4af592b2c92fa517e06a99e0f7c352be90c65ca7
4
+ data.tar.gz: 6f471df22a630daed758c14b8a141dfc4584a3bc
5
5
  SHA512:
6
- metadata.gz: 2b4e30d36f53018d4c3e95a6b111c7c20c77be12c121211d458a7d507b3c07f78e501df858baf64f653b173a4bde0eb25af49ea8e37892ecaf2f665663248963
7
- data.tar.gz: 61c307f9f518d4fa7250fe0ca2df2ea5c10994f91af2de2dbfcd645e98b9ad30c7086ea710b1f0a9d6f8b9676f83d2177c275048fb46fad7b7869613b73a3b39
6
+ metadata.gz: e33789c536e4d878808de59eac1db026224bb0c61eb948d3adc13ff93f0768ed3adc7f0dd971c51f13b82765c5e1bbb443e5f0b8c311b543d6f092b7109b814d
7
+ data.tar.gz: 005ce8accba916cf3e297d5262c4e51c1ddd1eba242a8e189c4548055c68492b977c4640046d8aaa66bef40522101a3af16496c006dffd8c85ab84eef4912aef
data/Gemfile.lock CHANGED
@@ -1,8 +1,8 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- cable_ready (1.0.0)
5
- activesupport
4
+ cable_ready (1.1.0)
5
+ activesupport (>= 5.0.0)
6
6
 
7
7
  GEM
8
8
  remote: https://rubygems.org/
data/README.md CHANGED
@@ -1,81 +1,181 @@
1
- [![Lines of Code](http://img.shields.io/badge/lines_of_code-80-brightgreen.svg?style=flat)](http://blog.codinghorror.com/the-best-code-is-no-code-at-all/)
1
+ [![Lines of Code](http://img.shields.io/badge/lines_of_code-98-brightgreen.svg?style=flat)](http://blog.codinghorror.com/the-best-code-is-no-code-at-all/)
2
2
  [![Code Status](http://img.shields.io/codeclimate/github/hopsoft/cable_ready.svg?style=flat)](https://codeclimate.com/github/hopsoft/cable_ready)
3
3
  [![Dependency Status](http://img.shields.io/gemnasium/hopsoft/cable_ready.svg?style=flat)](https://gemnasium.com/hopsoft/cable_ready)
4
4
 
5
5
  # CableReady
6
6
 
7
7
  CableReady provides a standard interface for invoking common client-side DOM operations
8
- from the server via Ruby on Rails' [ActionCable](http://guides.rubyonrails.org/action_cable_overview.html).
8
+ from the server via [ActionCable](http://guides.rubyonrails.org/action_cable_overview.html).
9
9
 
10
- _NOTE: It's possible to invoke multiple DOM operations with a single ActionCable broadcast._
10
+ Learn more about CableReady by reading through & running the [CableReady Test](https://github.com/hopsoft/cable_ready_test) project.
11
11
 
12
12
  ## Supported DOM Operations
13
13
 
14
- ### [dispatchEvent](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent)
14
+ > The `selector` options use [Document.querySelector()](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector) to find elements.
15
+
16
+ > It's possible to invoke multiple DOM operations with a single ActionCable broadcast.
17
+
18
+ ### DOM Events
19
+
20
+ #### [dispatchEvent](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent)
15
21
 
16
22
  Dispatches a DOM event in the browser.
17
23
 
18
24
  ```ruby
19
25
  cable_ready_broadcast "MyChannel", dispatch_event: [{
20
- event_name: "string", # required - the name of the DOM event to dispatch (can be custom)
21
- element_id: "string", # [window] - the DOM element id of the desired event target
22
- detail: "object" # [null] - assigned to event.detail
26
+ name: "string", # required - the name of the DOM event to dispatch (can be custom)
27
+ detail: "object", # [null] - assigned to event.detail
28
+ selector: "string" # [window] - string containing one or more CSS selectors separated by commas
23
29
  }]
24
30
  ```
25
31
 
26
- ### [innerHTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML)
32
+ ### Element Mutations
33
+
34
+ #### [innerHTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML)
27
35
 
28
36
  Sets the innerHTML of a DOM element.
29
37
 
30
38
  ```ruby
31
39
  cable_ready_broadcast "MyChannel", inner_html: [{
32
- element_id: "string", # required - the DOM element id of the element to be mutated
33
- html: "string" # [null] - the HTML to assign
40
+ selector: "string", # required - string containing one or more CSS selectors separated by commas
41
+ focusSelector: "string", # [null] - string containing one or more CSS selectors separated by commas
42
+ html: "string" # [null] - the HTML to assign
34
43
  }]
35
44
  ```
36
45
 
37
- ### [insertAdjacentHTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentHTML)
46
+ #### [textContent](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent)
47
+
48
+ Sets the text content of a DOM element.
49
+
50
+ ```ruby
51
+ cable_ready_broadcast "MyChannel", text_content: [{
52
+ selector: "string", # required - string containing one or more CSS selectors separated by commas
53
+ text: "string" # [null] - the text to assign
54
+ }]
55
+ ```
56
+
57
+ #### [insertAdjacentHTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentHTML)
38
58
 
39
59
  Inserts HTML into the DOM relative to an element.
40
60
  Supports behavior akin to prepend & append.
41
61
 
42
62
  ```ruby
43
63
  cable_ready_broadcast "MyChannel", insert_adjacent_html: [{
44
- element_id: "string", # required - the DOM element id of the referenced element
45
- position: "string", # [beforeend] - the relative position to the DOM element (beforebegin, afterbegin, beforeend, afterend)
46
- html: "string" # [null] - the HTML to assign
64
+ selector: "string", # required - string containing one or more CSS selectors separated by commas
65
+ focusSelector: "string", # [null] - string containing one or more CSS selectors separated by commas
66
+ position: "string", # [beforeend] - the relative position to the DOM element (beforebegin, afterbegin, beforeend, afterend)
67
+ html: "string" # [null] - the HTML to insert
47
68
  }]
48
69
  ```
49
70
 
50
- ### [remove](https://developer.mozilla.org/en-US/docs/Web/API/ChildNode/remove)
71
+ #### [insertAdjacentText](https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentText)
72
+
73
+ Inserts text into the DOM relative to an element.
74
+ Supports behavior akin to prepend & append.
75
+
76
+ ```ruby
77
+ cable_ready_broadcast "MyChannel", insert_adjacent_text: [{
78
+ selector: "string", # required - string containing one or more CSS selectors separated by commas
79
+ position: "string", # [beforeend] - the relative position to the DOM element (beforebegin, afterbegin, beforeend, afterend)
80
+ text: "string" # [null] - the text to insert
81
+ }]
82
+ ```
83
+
84
+ #### [remove](https://developer.mozilla.org/en-US/docs/Web/API/ChildNode/remove)
51
85
 
52
86
  Removes an element from the DOM.
53
87
 
54
88
  ```ruby
55
89
  cable_ready_broadcast "MyChannel", remove: [{
56
- element_id: "string" # required - the DOM element id of the element to be removed
90
+ selector: "string", # required - string containing one or more CSS selectors separated by commas
91
+ focusSelector: "string" # [null] - string containing one or more CSS selectors separated by commas
57
92
  }]
58
93
  ```
59
94
 
60
- ### [replace](https://developer.mozilla.org/en-US/docs/Web/API/Node/replaceChild)
95
+ #### [replace](https://developer.mozilla.org/en-US/docs/Web/API/Node/replaceChild)
61
96
 
62
97
  Replaces a DOM element with new HTML.
63
98
 
64
99
  ```ruby
65
100
  cable_ready_broadcast "MyChannel", replace: [{
66
- element_id: "string", # required - the DOM element id of the element to be replaced
67
- html: "string" # [null] - the HTML to use as replacement
101
+ selector: "string", # required - string containing one or more CSS selectors separated by commas
102
+ focusSelector: "string", # [null] - string containing one or more CSS selectors separated by commas
103
+ html: "string" # [null] - the HTML to use as replacement
68
104
  }]
69
105
  ```
70
106
 
71
- ### [textContent](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent)
107
+ #### [setValue](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement)
72
108
 
73
- Sets the text content of a DOM element.
109
+ Sets the value of an element.
74
110
 
75
111
  ```ruby
76
- cable_ready_broadcast "MyChannel", text_content: [{
77
- element_id: "string", # required - the DOM element id of the element to be mutated
78
- text: "string" # [null] - the text to assign
112
+ cable_ready_broadcast "MyChannel", set_value: [{
113
+ selector: "string", # required - string containing one or more CSS selectors separated by commas
114
+ value: "string" # [null] - the value to assign to the attribute
115
+ }]
116
+ ```
117
+
118
+ ### Attribute Mutations
119
+
120
+ #### [setAttribute](https://developer.mozilla.org/en-US/docs/Web/API/Element/setAttribute)
121
+
122
+ Sets an attribute on an element.
123
+
124
+ ```ruby
125
+ cable_ready_broadcast "MyChannel", set_attribute: [{
126
+ selector: "string", # required - string containing one or more CSS selectors separated by commas
127
+ name: "string", # required - the attribute to set
128
+ value: "string" # [null] - the value to assign to the attribute
129
+ }]
130
+ ```
131
+
132
+ #### [removeAttribute](https://developer.mozilla.org/en-US/docs/Web/API/Element/removeAttribute)
133
+
134
+ Removes an attribute from an element.
135
+
136
+ ```ruby
137
+ cable_ready_broadcast "MyChannel", remove_attribute: [{
138
+ selector: "string", # required - string containing one or more CSS selectors separated by commas
139
+ name: "string" # required - the attribute to remove
140
+ }]
141
+ ```
142
+
143
+ ### CSS Class Mutations
144
+
145
+ #### [addCssClass](https://developer.mozilla.org/en-US/docs/Web/API/Element/classList)
146
+
147
+ Adds a css class to an element.
148
+ This is a `noop` if the css class is already assigned.
149
+
150
+ ```ruby
151
+ cable_ready_broadcast "MyChannel", add_css_class: [{
152
+ selector: "string", # required - string containing one or more CSS selectors separated by commas
153
+ name: "string" # [null] - the CSS class to add
154
+ }]
155
+
156
+ ```
157
+ #### [removeCssClass](https://developer.mozilla.org/en-US/docs/Web/API/Element/classList)
158
+
159
+ Removes a css class from an element.
160
+
161
+ ```ruby
162
+ cable_ready_broadcast "MyChannel", add_css_class: [{
163
+ selector: "string", # required - string containing one or more CSS selectors separated by commas
164
+ name: "string" # [null] - the CSS class to remove
165
+ }]
166
+ ```
167
+
168
+ ### Dataset Mutations
169
+
170
+ #### [setDatasetProperty](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset)
171
+
172
+ Sets an dataset property (data-* attribute) on an element.
173
+
174
+ ```ruby
175
+ cable_ready_broadcast "MyChannel", set_dataset_property: [{
176
+ selector: "string", # required - string containing one or more CSS selectors separated by commas
177
+ name: "string", # required - the property to set
178
+ value: "string" # [null] - the value to assign to the dataset
79
179
  }]
80
180
  ```
81
181
 
@@ -89,7 +189,7 @@ class User < ApplicationRecord
89
189
  include CableReady::Broadcaster
90
190
 
91
191
  def broadcast_name_change
92
- cable_ready_broadcast "UserChannel", text_content: [{ element_id: "user-name", text: name }]
192
+ cable_ready_broadcast "UserChannel", text_content: [{ selector: "#user-name", text: name }]
93
193
  end
94
194
  end
95
195
  ```
@@ -114,11 +214,11 @@ App.cable.subscriptions.create({ channel: "UserChannel" }, {
114
214
  });
115
215
  ```
116
216
 
117
- ## Testing & Experimenting
118
-
119
- Learn more about CableReady by running the [CableReady Test](https://github.com/hopsoft/cable_ready_test) project.
120
-
121
217
  ## Advanced Usage
122
218
 
123
- If you prefer server rendering, consider using CableReady in concert with a gem like
124
- [SelfRenderer](https://github.com/hopsoft/self_renderer) for a simple yet powerful workflow.
219
+ Consider using CableReady in concert with a gem like
220
+ [SelfRenderer](https://github.com/hopsoft/self_renderer) to create a powerful SPA style user experience with the simplicity of server side rendering.
221
+
222
+ <a target='_blank' rel='nofollow' href='https://app.codesponsor.io/link/QMSjMHrtPhvfmCnk5Hbikhhr/hopsoft/cable_ready'>
223
+ <img alt='Sponsor' width='888' height='68' src='https://app.codesponsor.io/embed/QMSjMHrtPhvfmCnk5Hbikhhr/hopsoft/cable_ready.svg' />
224
+ </a>
data/lib/cable_ready/broadcaster.rb CHANGED
@@ -5,36 +5,88 @@ module CableReady
5
5
  # Example Payload:
6
6
  #
7
7
  # {
8
+ # # DOM Events ..................................................................................................
9
+ #
8
10
  # dispatch_event: [{
9
- # event_name: "string",
10
- # element_id: "string",
11
- # detail: "object"
11
+ # name: "string",
12
+ # detail: "object",
13
+ # selector: "string",
12
14
  # }, ...],
13
15
  #
16
+ # # Element Mutations ...........................................................................................
17
+ #
14
18
  # inner_html: [{
15
- # element_id: "string",
16
- # html: "string"
19
+ # selector: "string",
20
+ # focusSelector: "string",
21
+ # html: "string"
17
22
  # }, ...],
18
23
  #
24
+ # text_content: [{
25
+ # selector: "string",
26
+ # text: "string"
27
+ # }, ...]
28
+ #
19
29
  # insert_adjacent_html: [{
20
- # element_id: "string",
21
- # position: "string",
22
- # html: "string"
30
+ # selector: "string",
31
+ # focusSelector: "string",
32
+ # position: "string",
33
+ # html: "string"
34
+ # }, ...],
35
+ #
36
+ # insert_adjacent_text: [{
37
+ # selector: "string",
38
+ # position: "string",
39
+ # text: "string"
23
40
  # }, ...],
24
41
  #
25
42
  # remove: [{
26
- # element_id: "string"
43
+ # selector: "string",
44
+ # focusSelector: "string,
27
45
  # }, ...],
28
46
  #
29
47
  # replace: [{
30
- # element_id: "string",
31
- # html: "string"
48
+ # selector: "string",
49
+ # focusSelector: "string",
50
+ # html: "string"
32
51
  # }, ...],
33
52
  #
34
- # textContent: [{
35
- # element_id: "string",
36
- # text: "string"
37
- # }, ...]
53
+ # set_value: [{
54
+ # selector: "string",
55
+ # value: "string"
56
+ # }, ...],
57
+ #
58
+ # # Attribute Mutations .........................................................................................
59
+ #
60
+ # set_attribute: [{
61
+ # selector: "string",
62
+ # name: "string",
63
+ # value: "string"
64
+ # }, ...],
65
+ #
66
+ # remove_attribute: [{
67
+ # selector: "string",
68
+ # name: "string"
69
+ # }, ...],
70
+ #
71
+ # # CSS Class Mutations .........................................................................................
72
+ #
73
+ # add_css_class: [{
74
+ # selector: "string",
75
+ # name: "string"
76
+ # }, ...],
77
+ #
78
+ # remove_css_class: [{
79
+ # selector: "string",
80
+ # name: "string"
81
+ # }, ...],
82
+ #
83
+ # # Dataset Mutations ...........................................................................................
84
+ #
85
+ # set_dataset_property: [{
86
+ # selector: "string",
87
+ # name: "string",
88
+ # value: "string"
89
+ # }, ...],
38
90
  # }
39
91
  def cable_ready_broadcast(channel, operations={})
40
92
  operations ||= {}
data/lib/cable_ready/version.rb CHANGED
@@ -1,3 +1,3 @@
1
1
  module CableReady
2
- VERSION = "1.0.0"
2
+ VERSION = "1.1.0"
3
3
  end
data/vendor/assets/javascripts/cable_ready.js CHANGED
@@ -1,52 +1,90 @@
1
1
  (function () {
2
2
  "use strict";
3
3
 
4
- function log (operation, config) {
5
- if (window.CableReady.debug) {
6
- console.log("CableReady", operation, config);
7
- }
8
- }
9
-
10
4
  var CableReadyOperations = {
5
+ // DOM Events .....................................................................................................
6
+
11
7
  dispatchEvent: function (config) {
12
- log("dispatchEvent", config);
13
- var event = new Event(config.eventName);
14
- var target = document.getElementById(config.elementId) || window;
15
- var event = new Event(config.eventName);
8
+ if (CableReady.debug) { console.log("CableReady.dispatchEvent", config); }
9
+ var target = document.querySelector(config.selector) || window;
10
+ var event = new Event(config.name);
16
11
  event.detail = config.detail;
17
12
  target.dispatchEvent(event);
18
13
  },
19
14
 
15
+ // Element Mutations ..............................................................................................
16
+
20
17
  innerHtml: function (config) {
21
- log("innerHTML", config);
22
- var element = document.getElementById(config.elementId);
23
- element.innerHTML = config.html;
18
+ if (CableReady.debug) { console.log("CableReady.innerHTML", config); }
19
+ document.querySelector(config.selector).innerHTML = config.html;
20
+ if (config.focusSelector) { document.querySelector(config.focusSelector).focus(); }
21
+ },
22
+
23
+ textContent: function (config) {
24
+ if (CableReady.debug) { console.log("CableReady.textContent", config); }
25
+ document.querySelector(config.selector).textContent = config.text;
24
26
  },
25
27
 
26
28
  insertAdjacentHtml: function (config) {
27
- log("insertAdjacentHTML", config);
28
- var element = document.getElementById(config.elementId);
29
- element.insertAdjacentHTML(config.position || "beforeend", config.html);
29
+ if (CableReady.debug) { console.log("CableReady.insertAdjacentHTML", config); }
30
+ document.querySelector(config.selector).insertAdjacentHTML(config.position || "beforeend", config.html);
31
+ if (config.focusSelector) { document.querySelector(config.focusSelector).focus(); }
32
+ },
33
+
34
+ insertAdjacentText: function (config) {
35
+ if (CableReady.debug) { console.log("CableReady.insertAdjacentText", config); }
36
+ document.querySelector(config.querySelector).insertAdjacentText(config.position || "beforeend", config.text);
30
37
  },
31
38
 
32
39
  remove: function (config) {
33
- log("remove", config);
34
- var element = document.getElementById(config.elementId);
35
- element.remove(element);
40
+ if (CableReady.debug) { console.log("CableReady.remove", config); }
41
+ document.querySelector(config.selector).remove();
42
+ if (config.focusSelector) { document.querySelector(config.focusSelector).focus(); }
36
43
  },
37
44
 
38
45
  replace: function (config) {
39
- log("replace", config);
40
- var element = document.getElementById(config.elementId);
41
- var clone = element.cloneNode(false);
42
- clone.innerHTML = config.html;
43
- element.parentNode.replaceChild(clone, element);
46
+ if (CableReady.debug) { console.log("CableReady.replace", config); }
47
+ var element = document.querySelector(config.selector);
48
+ var div = document.createElement("div");
49
+ div.innerHTML = config.html;
50
+ element.parentNode.replaceChild(div.firstElementChild, element);
51
+ if (config.focusSelector) { document.querySelector(config.focusSelector).focus(); }
44
52
  },
45
53
 
46
- textContent: function (config) {
47
- log("textContent", config);
48
- var element = document.getElementById(config.elementId);
49
- element.textContent = config.content;
54
+ setValue: function (config) {
55
+ if (CableReady.debug) { console.log("CableReady.setValue", config); }
56
+ document.querySelector(config.selector).value = config.value;
57
+ },
58
+
59
+ // Attribute Mutations ............................................................................................
60
+
61
+ setAttribute: function (config) {
62
+ if (CableReady.debug) { console.log("CableReady.setAttribute", config); }
63
+ document.querySelector(config.selector).setAttribute(config.name, config.value);
64
+ },
65
+
66
+ removeAttribute: function (config) {
67
+ if (CableReady.debug) { console.log("CableReady.removeAttribute", config); }
68
+ document.querySelector(config.selector).removeAttribute(config.name);
69
+ },
70
+
71
+ // CSS Class Mutations ............................................................................................
72
+
73
+ addCssClass: function (config) {
74
+ if (CableReady.debug) { console.log("CableReady.addCssClass", config); }
75
+ document.querySelector(config.selector).classList.add(config.name);
76
+ },
77
+
78
+ removeCssClass: function (config) {
79
+ if (CableReady.debug) { console.log("CableReady.removeCssClass", config); }
80
+ document.querySelector(config.selector).classList.remove(config.name);
81
+ },
82
+
83
+ // Dataset Mutations ..............................................................................................
84
+
85
+ setDatasetProperty: function (config) {
86
+ if (CableReady.debug) { console.log("CableReady.setDatasetProperty", config); }
87
+ document.querySelector(config.selector).dataset[config.name] = config.value;
50
88
  }
51
89
  };
52
90
 
@@ -57,7 +95,11 @@
57
95
  if (operations.hasOwnProperty(name)) {
58
96
  var entries = operations[name];
59
97
  for (var i = 0; i < entries.length; i++) {
60
- CableReadyOperations[name](entries[i]);
98
+ try {
99
+ CableReadyOperations[name](entries[i]);
100
+ } catch (e) {
101
+ console.log("CableReady detected an error! " + e.message);
102
+ }
61
103
  }
62
104
  }
63
105
  }
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: cable_ready
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.0.0
4
+ version: 1.1.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Nathan Hopkins
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2017-09-20 00:00:00.000000000 Z
11
+ date: 2017-09-24 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: activesupport
@@ -16,14 +16,14 @@ dependencies:
16
16
  requirements:
17
17
  - - ">="
18
18
  - !ruby/object:Gem::Version
19
- version: '0'
19
+ version: 5.0.0
20
20
  type: :runtime
21
21
  prerelease: false
22
22
  version_requirements: !ruby/object:Gem::Requirement
23
23
  requirements:
24
24
  - - ">="
25
25
  - !ruby/object:Gem::Version
26
- version: '0'
26
+ version: 5.0.0
27
27
  - !ruby/object:Gem::Dependency
28
28
  name: rake
29
29
  requirement: !ruby/object:Gem::Requirement