Skip to content

Commit 642ad4b

Browse files
brandonocaseygkatsev
brandonocasey
authored and
gkatsev
committed
docs: move examples out of code into docs
1 parent 0493f54 commit 642ad4b

23 files changed

+952
-884
lines changed

‎docs/guides/components.md‎

Lines changed: 209 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,13 @@ The architecture of the Video.js player is centered around components. The `Play
77
* [What is a Component?](#what-is-a-component)
88
* [Creating a Component](#creating-a-component)
99
* [Component Children](#component-children)
10+
* [Basic Example](#basic-example)
11+
* [Using Options](#using-options)
12+
* [Event Listening](#event-listening)
13+
* [using on](#using-on)
14+
* [Using off](#using-off)
15+
* [Using one](#using-one)
16+
* [Using trigger](#using-trigger)
1017
* [Default Component Tree](#default-component-tree)
1118
* [Specific Component Details](#specific-component-details)
1219
* [Progress Control](#progress-control)
@@ -36,8 +43,42 @@ In addition, there are a couple methods worth recognizing:
3643
* `videojs.registerComponent(String name, Function Comp)`: Registers component constructors with Video.js.
3744
* `videojs.extend(Function component, Object properties)`: Provides prototype inheritance. Can be used to extend a component's constructor, returning a new constructor with the given properties.
3845

46+
Creation:
47+
48+
```js
49+
// adding a button to the player
50+
var player = videojs('some-video-id');
51+
var Component = videojs.getComponent('Component');
52+
var button = new Component(player);
53+
54+
console.log(button.el());
55+
```
56+
57+
The above code will output
58+
59+
```html
60+
<div class="video-js">
61+
<div class="vjs-button">Button</div>
62+
</div>
63+
```
64+
65+
Adding the new button to the player
66+
67+
```js
68+
// adding a button to the player
69+
var player = videojs('some-video-id');
70+
var button = player.addChild('button');
71+
72+
console.log(button.el());
73+
// will have the same html result as the previous example
74+
```
75+
3976
## Component Children
4077

78+
Again, refer to [the component API docs](http://docs.videojs.com/docs/api/component.html) for complete details on methods available for managing component structures.
79+
80+
### Basic Example
81+
4182
When child component is added to a parent component, Video.js inserts the element of the child into the element of the parent. For example, adding a component like this:
4283

4384
```js
@@ -69,7 +110,174 @@ Results in a DOM that looks like this:
69110
</div>
70111
```
71112

72-
Again, refer to [the component API docs](http://docs.videojs.com/docs/api/component.html) for complete details on methods available for managing component structures.
113+
### Using Options
114+
115+
Pass in options for child constructors and options for children of the child.
116+
117+
```js
118+
var player = videojs('some-vid-id');
119+
var Component = videojs.getComponent('Component');
120+
var myComponent = new Component(player);
121+
var myButton = myComponent.addChild('MyButton', {
122+
text: 'Press Me',
123+
buttonChildExample: {
124+
buttonChildOption: true
125+
}
126+
});
127+
```
128+
129+
Children can also be added via options when a component is initialized.
130+
131+
> Note: Include a 'name' key which will be used if two child components of the same
132+
> type that need different options.
133+
134+
```js
135+
// MyComponent is from the above example
136+
var myComp = new MyComponent(player, {
137+
children: ['button', {
138+
name: 'button',
139+
someOtherOption: true
140+
}, {
141+
name: 'button',
142+
someOtherOption: false
143+
}]
144+
});
145+
```
146+
147+
## Event Listening
148+
149+
### Using `on`
150+
151+
```js
152+
var player = videojs('some-player-id');
153+
var Component = videojs.getComponent('Component');
154+
var myComponent = new Component(player);
155+
var myFunc = function() {
156+
var myComponent = this;
157+
console.log('myFunc called');
158+
};
159+
160+
myComponent.on('eventType', myFunc);
161+
myComponent.trigger('eventType');
162+
// logs 'myFunc called'
163+
```
164+
165+
The context of `myFunc` will be `myComponent` unless it is bound. You can add
166+
a listener to another element or component.
167+
168+
```js
169+
var otherComponent = new Component(player);
170+
171+
// myComponent/myFunc is from the above example
172+
myComponent.on(otherComponent.el(), 'eventName', myFunc);
173+
myComponent.on(otherComponent, 'eventName', myFunc);
174+
175+
otherComponent.trigger('eventName');
176+
// logs 'myFunc called' twice
177+
```
178+
179+
### Using `off`
180+
181+
```js
182+
var player = videojs('some-player-id');
183+
var Component = videojs.getComponent('Component');
184+
var myComponent = new Component(player);
185+
var myFunc = function() {
186+
var myComponent = this;
187+
console.log('myFunc called');
188+
};
189+
myComponent.on('eventType', myFunc);
190+
myComponent.trigger('eventType');
191+
// logs 'myFunc called'
192+
193+
myComponent.off('eventType', myFunc);
194+
myComponent.trigger('eventType');
195+
// does nothing
196+
```
197+
198+
If myFunc gets excluded, *all* listeners for the event type will get removed. If
199+
eventType gets excluded, *all* listeners will get removed from the component.
200+
You can use `off` to remove listeners that get added to other elements or
201+
components using:
202+
203+
`myComponent.on(otherComponent...`
204+
205+
In this case both the event type and listener function are **REQUIRED**.
206+
207+
```js
208+
var otherComponent = new Component(player);
209+
210+
// myComponent/myFunc is from the above example
211+
myComponent.on(otherComponent.el(), 'eventName', myFunc);
212+
myComponent.on(otherComponent, 'eventName', myFunc);
213+
214+
otherComponent.trigger('eventName');
215+
// logs 'myFunc called' twice
216+
myComponent.off(ootherComponent.el(), 'eventName', myFunc);
217+
myComponent.off(otherComponent, 'eventName', myFunc);
218+
otherComponent.trigger('eventName');
219+
// does nothing
220+
```
221+
222+
### Using `one`
223+
224+
```js
225+
var player = videojs('some-player-id');
226+
var Component = videojs.getComponent('Component');
227+
var myComponent = new Component(player);
228+
var myFunc = function() {
229+
var myComponent = this;
230+
console.log('myFunc called');
231+
};
232+
myComponent.one('eventName', myFunc);
233+
myComponent.trigger('eventName');
234+
// logs 'myFunc called'
235+
236+
myComponent.trigger('eventName');
237+
// does nothing
238+
```
239+
240+
You can also add a listener to another element or component that will get
241+
triggered only once.
242+
243+
```js
244+
var otherComponent = new Component(player);
245+
246+
// myComponent/myFunc is from the above example
247+
myComponent.one(otherComponent.el(), 'eventName', myFunc);
248+
myComponent.one(otherComponent, 'eventName', myFunc);
249+
250+
otherComponent.trigger('eventName');
251+
// logs 'myFunc called' twice
252+
253+
otherComponent.trigger('eventName');
254+
// does nothing
255+
```
256+
257+
### Using `trigger`
258+
259+
```js
260+
var player = videojs('some-player-id');
261+
var Component = videojs.getComponent('Component');
262+
var myComponent = new Component(player);
263+
var myFunc = function(data) {
264+
var myComponent = this;
265+
console.log('myFunc called');
266+
console.log(data);
267+
};
268+
myComponent.one('eventName', myFunc);
269+
myComponent.trigger('eventName');
270+
// logs 'myFunc called' and 'undefined'
271+
272+
myComponent.trigger({'type':'eventName'});
273+
// logs 'myFunc called' and 'undefined'
274+
275+
myComponent.trigger('eventName', {data: 'some data'});
276+
// logs 'myFunc called' and "{data: 'some data'}"
277+
278+
myComponent.trigger({'type':'eventName'}, {data: 'some data'});
279+
// logs 'myFunc called' and "{data: 'some data'}"
280+
```
73281

74282
## Default Component Tree
75283

‎docs/guides/event-target.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Event Target
2+
3+
## Table of Contents
4+
5+
* [Overview](#overview)
6+
* [on() and addEventListener()](#on-and-addeventlistener)
7+
* [off() and removeEventListener](#off-and-removeeventlistener)
8+
* [one()](#one)
9+
* [trigger() and dispatchEvent](#trigger-and-dispatchevent)
10+
11+
## Overview
12+
13+
Events in video.js are setup so that they mimic the DOM API that is used on object, but also have helpful shorthand functions with the same functionality.
14+
15+
## `on()` and `addEventListener()`
16+
17+
This function is used to add an event listener to an EventTarget.
18+
19+
```js
20+
var foo = new EventTarget();
21+
var handleBar = function() {
22+
console.log('bar was triggered');
23+
};
24+
25+
foo.on('bar', handleBar);
26+
27+
// This causes any `event listeners` for the `bar` event to get called
28+
// see {@link EventTarget#trigger} for more information
29+
foo.trigger('bar');
30+
// logs 'bar was triggered'
31+
```
32+
33+
## `off()` and `removeEventListener()`
34+
35+
This function is used to remove an listener function from an EventTarget.
36+
37+
```js
38+
var foo = new EventTarget();
39+
var handleBar = function() {
40+
console.log('bar was triggered');
41+
};
42+
43+
// adds an `event listener` for the `bar` event
44+
// see {@link EventTarget#on} for more info
45+
foo.on('bar', handleBar);
46+
47+
// runs all `event listeners` for the `bar` event
48+
// see {@link EventTarget#trigger} for more info
49+
foo.trigger('bar');
50+
// logs 'bar was triggered'
51+
52+
foo.off('bar', handleBar);
53+
foo.trigger('bar');
54+
// does nothing
55+
```
56+
57+
## `one()`
58+
59+
This function is used to only have an event listener called once and never again.
60+
61+
Using `on()` and `off()` to mimic `one()` (not recommended)
62+
63+
```js
64+
var foo = new EventTarget();
65+
var handleBar = function() {
66+
console.log('bar was triggered');
67+
// after the first trigger remove this handler
68+
foo.off('bar', handleBar);
69+
};
70+
71+
foo.on('bar', handleBar);
72+
foo.trigger('bar');
73+
// logs 'bar was triggered'
74+
75+
foo.trigger('bar');
76+
// does nothing
77+
```
78+
79+
Using `one()`
80+
81+
```js
82+
var foo = new EventTarget();
83+
var handleBar = function() {
84+
console.log('bar was triggered');
85+
};
86+
87+
// removed after the first trigger
88+
foo.one('bar', handleBar);
89+
foo.trigger('bar');
90+
// logs 'bar was triggered'
91+
92+
foo.trigger('bar');
93+
// does nothing
94+
```
95+
96+
## `trigger()` and `dispatchEvent()`
97+
98+
This function is used to trigger an event on an EventTarget which will cause all listeners to run.
99+
100+
> Note: if 'click' is in `EventTarget.allowedEvents_`, trigger will attempt to call the
101+
> `onClick` function if it exists.
102+
103+
```js
104+
var foo = new EventTarget();
105+
var handleBar = function() {
106+
console.log('bar was triggered');
107+
};
108+
109+
foo.on('bar', handleBar);
110+
foo.trigger('bar');
111+
// logs 'bar was triggered'
112+
113+
foo.trigger('bar');
114+
// logs 'bar was triggered'
115+
116+
foo.trigger('foo');
117+
// does nothing
118+
```

0 commit comments

Comments
 (0)