Skip to content

Commit dfaf699

Browse files
pascalwengerterpascalwengerter
committed
Remove duplicate content, fix indentation, try to make things clearer
1 parent abcf11d commit dfaf699

File tree

1 file changed

+90
-92
lines changed

1 file changed

+90
-92
lines changed

‎docs/api/100-components/cable.md

Lines changed: 90 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,8 @@
11
# Matestack Core Component: Cable
22

3-
The `cable` component enables us to update the DOM based on events and data pushed via ActionCable without browser reload. Please read the [ActionCable Guide](/docs/guides/1000-action_cable/README.md) if you need help setting up ActionCable for your project.
3+
The `cable` component enables us to update the DOM based on events and data pushed via ActionCable without a browser reload.
44

5-
Please read the [ActionCable Guide](/docs/guides/1000-action_cable/README.md) if you need help setting up ActionCable for your project.
6-
7-
Please make sure to setup ActionCable correctly. Esspecially following implementation is important in order to use the `cable` component correctly:
5+
Please read the [ActionCable Guide](/docs/guides/1000-action_cable/README.md) if you need help setting up ActionCable for your project, and make sure you have set up ActionCable correctly. The following code snippet is crucial to make the `cable` component work correctly:
86

97
`app/javascript/channels/matestack_ui_core_channel.js`
108

@@ -20,7 +18,7 @@ consumer.subscriptions.create("MatestackUiCoreChannel", {
2018
## `cable(*args, &block)`
2119
----
2220

23-
Returns a vue.js driven cable component initially containing content specified by a block.
21+
Returns a vue.js driven cable component, initially containing content specified by a block.
2422

2523
Imagine something like this:
2624

@@ -29,8 +27,8 @@ class Page < Matestack::Ui::Page
2927

3028
def response
3129
cable id: 'foo' [...] do
32-
#this block will be rendered as initial content
33-
#and may be modified on the client later on when receiving defined events
30+
# this block will be rendered as initial content and may be
31+
# modified on the client side later upon receiving defined events
3432
DummyModel.all.each do |instance|
3533
list_component item: instance
3634
end
@@ -39,16 +37,16 @@ class Page < Matestack::Ui::Page
3937
end
4038
```
4139

42-
with an as `list_component` registered component:
40+
where the `list_component` is registered like this:
4341

4442
```ruby
4543
class ListComponent < Matestack::Ui::Component
4644

4745
requires :item
4846

4947
def response
50-
#make sure to define a unique ID on the root element of your component
51-
#this ID may be used to update or delete this component on the client later on
48+
# make sure to define an unique ID on the root element of your component
49+
# the declared ID may be used later on to update or delete this component on the client side
5250
div id: "item-#{item.id}", class: "row" do
5351
#...
5452
end
@@ -57,132 +55,132 @@ class ListComponent < Matestack::Ui::Component
5755
end
5856
```
5957

60-
Please notice: when rendering a list of items, we recommend to use a custom component for each item. This makes it easy to render unique items on the serverside and push them via ActionCable to the client. But it is possible to also use another component or a html string. Any given html will be used to update the list.
61-
58+
Please note: When rendering a list of items, we recommend to use a custom component for each item. This makes it easy to render unique items on the serverside and push them via ActionCable to the client. Technically, it is also possible to use another component or a simple html string. Any given html will be used to update the item.
6259

6360
**Required options**
6461

65-
* `id` - Expects a unique string identifying the component
62+
* `id` - Expects an unique string that identifies the component
6663

6764
**Optional options**
6865

69-
* `append_on` - Expects a string matching the event which will be emitted via ActionCable on the serverside. Event payload data in form of HTML will be **appended** to the current cable component DOM
66+
* `append_on` - Expects a string that matches the event which will be emitted via ActionCable on the serverside. Event payload data in form of HTML will be **appended** to the current cable component DOM.
7067

71-
In your app, page or component:
68+
In your app, page or component:
7269

73-
```ruby
74-
cable id: 'foo', append_on: "model_created" do
75-
DummyModel.all.each do |instance|
76-
list_component item: instance
77-
end
70+
```ruby
71+
cable id: 'foo', append_on: "model_created" do
72+
DummyModel.all.each do |instance|
73+
list_component item: instance
7874
end
79-
```
75+
end
76+
```
8077

81-
In your controller:
78+
In your controller:
8279

83-
```ruby
84-
ActionCable.server.broadcast("matestack_ui_core", {
85-
event: "model_created",
86-
data: matestack_component(:list_component, item: @new_model_instance)
87-
})
88-
```
80+
```ruby
81+
ActionCable.server.broadcast("matestack_ui_core", {
82+
event: "model_created",
83+
data: matestack_component(:list_component, item: @new_model_instance)
84+
})
85+
```
8986

90-
`data` can also be an Array of components
87+
`data` can also be an array of components.
9188

9289

93-
* `prepend_on` - Expects a string which matches the event which will be emitted via ActionCable on the serverside. Event payload data in form of HTML will be **prepended** to the current cable component DOM
90+
* `prepend_on` - Expects a string that matches the event which will be emitted via ActionCable on the serverside. Event payload data in form of HTML will be **prepended** to the current cable component DOM.
9491

95-
In your app, page or component:
92+
In your app, page or component:
9693

97-
```ruby
98-
cable id: 'foo', prepend_on: "model_created" do
99-
DummyModel.all.each do |instance|
100-
list_component item: instance
101-
end
94+
```ruby
95+
cable id: 'foo', prepend_on: "model_created" do
96+
DummyModel.all.each do |instance|
97+
list_component item: instance
10298
end
103-
```
99+
end
100+
```
104101

105-
In your controller:
102+
In your controller:
106103

107-
```ruby
108-
ActionCable.server.broadcast("matestack_ui_core", {
109-
event: "model_created",
110-
data: matestack_component(:list_component, item: @new_model_instance)
111-
})
112-
```
104+
```ruby
105+
ActionCable.server.broadcast("matestack_ui_core", {
106+
event: "model_created",
107+
data: matestack_component(:list_component, item: @new_model_instance)
108+
})
109+
```
113110

114-
`data` can also be an Array of components
111+
`data` can also be an array of components.
115112

116113

117-
* `replace_on` - Expects a string which matches the event which will be emitted via ActionCable on the serverside. Event payload data in form of HTML will **replace** the whole current cable component DOM
114+
* `replace_on` - Expects a string that matches the event which will be emitted via ActionCable on the serverside. Event payload data in form of HTML will **replace** the whole current cable component DOM.
118115

119-
In your app, page or component:
116+
In your app, page or component:
120117

121-
```ruby
122-
cable id: 'foo', replace_on: "model_created" do
118+
```ruby
119+
cable id: 'foo', replace_on: "model_created" do
120+
DummyModel.all.each do |instance|
123121
list_component item: instance
124122
end
125-
```
126-
127-
In your controller:
123+
end
124+
```
128125

129-
```ruby
130-
ActionCable.server.broadcast("matestack_ui_core", {
131-
event: "model_created",
132-
data: matestack_component(:list_component, item: @new_model_instance)
133-
})
134-
```
126+
In your controller:
135127

136-
`data` can also be an Array of components
128+
```ruby
129+
ActionCable.server.broadcast("matestack_ui_core", {
130+
event: "model_created",
131+
data: matestack_component(:list_component, item: @new_model_instance)
132+
})
133+
```
137134

135+
`data` can also be an array of components.
138136

139137

140-
* `update_on` - Expects a string which matches the event which will be emitted via ActionCable on the serverside. Event payload data in form of HTML will **update** a specific element iditified by its root ID within the current cable component DOM
138+
* `update_on` - Expects a string that matches the event which will be emitted via ActionCable on the serverside. Event payload data in form of HTML will **update** a specific element iditified by its root ID within the current cable component DOM.
141139

142-
In your app, page or component:
140+
In your app, page or component:
143141

144-
```ruby
145-
cable id: 'foo', append_on: "model_created" do
146-
DummyModel.all.each do |instance|
147-
list_component item: instance
148-
end
142+
```ruby
143+
cable id: 'foo', append_on: "model_created" do
144+
DummyModel.all.each do |instance|
145+
list_component item: instance
149146
end
150-
```
147+
end
148+
```
151149

152-
In your controller:
150+
In your controller:
153151

154-
```ruby
155-
ActionCable.server.broadcast("matestack_ui_core", {
156-
event: "model_created",
157-
data: matestack_component(:list_component, item: @new_model_instance)
158-
})
159-
```
152+
```ruby
153+
ActionCable.server.broadcast("matestack_ui_core", {
154+
event: "model_created",
155+
data: matestack_component(:list_component, item: @new_model_instance)
156+
})
157+
```
160158

161-
`data` can also be an Array of components
159+
`data` can also be an array of components.
162160

163161

164-
* `delete_on` - Expects a string which matches the event which will be emitted via ActionCable on the serverside. Event payload data in form of a string containing the ID will **remove** a specific element identified by its root ID within the current cable component DOM
162+
* `delete_on` - Expects a string that matches the event which will be emitted via ActionCable on the serverside. Event payload data in form of a string containing the ID will **remove** a specific element identified by its root ID within the current cable component DOM.
165163

166-
In your app, page or component:
164+
In your app, page or component:
167165

168-
```ruby
169-
cable id: 'foo', delete_on: "model_deleted" do
170-
DummyModel.all.each do |instance|
171-
list_component item: instance
172-
end
166+
```ruby
167+
cable id: 'foo', delete_on: "model_deleted" do
168+
DummyModel.all.each do |instance|
169+
list_component item: instance
173170
end
174-
```
171+
end
172+
```
175173

176-
In your controller:
174+
In your controller:
177175

178-
```ruby
179-
ActionCable.server.broadcast("matestack_ui_core", {
180-
event: "model_deleted",
181-
data: "item-#{params[:id]}"
182-
})
183-
```
176+
```ruby
177+
ActionCable.server.broadcast("matestack_ui_core", {
178+
event: "model_deleted",
179+
data: "item-#{params[:id]}"
180+
})
181+
```
184182

185-
`data` can also be an Array of ID-strings
183+
`data` can also be an Array of ID-strings.
186184

187185

188-
* Html attributes - all w3c confirm html attributes for div's can be set via options and will be added to the surrounding card div.
186+
* `html attributes` - all the canonical [HTML global attributes](https://www.w3schools.com/tags/ref_standardattributes.asp) can be set via options and will be added to the surrounding cable div.

0 commit comments

Comments
 (0)