0
# DOM Events
1

2
DOM event system for communicating with LiveReload and integrating with other development tools. LiveReload fires custom DOM events for connection state changes and listens for shutdown commands via DOM events.
3

4
## Capabilities
5

6
### Connection Events
7

8
LiveReload fires DOM events on the document when connection state changes occur.
9

10
```javascript { .api }
11
/**
12
 * Fired when LiveReload establishes connection to server
13
 * Event target: document
14
 * Event type: 'LiveReloadConnect' 
15
 */
16
document.addEventListener('LiveReloadConnect', handler);
17

18
/**
19
 * Fired when LiveReload loses connection to server  
20
 * Event target: document
21
 * Event type: 'LiveReloadDisconnect'
22
 */
23
document.addEventListener('LiveReloadDisconnect', handler);
24
```
25

26
**Usage Examples:**
27

28
```javascript
29
// Show connection status indicator
30
document.addEventListener('LiveReloadConnect', () => {
31
    const indicator = document.getElementById('livereload-status');
32
    if (indicator) {
33
        indicator.textContent = 'Connected';
34
        indicator.className = 'status-connected';
35
    }
36
    console.log('LiveReload connected to server');
37
});
38

39
document.addEventListener('LiveReloadDisconnect', () => {
40
    const indicator = document.getElementById('livereload-status');
41
    if (indicator) {
42
        indicator.textContent = 'Disconnected';
43
        indicator.className = 'status-disconnected';
44
    }
45
    console.log('LiveReload disconnected from server');
46
});
47
```
48

49
### Shutdown Command
50

51
Send a shutdown command to LiveReload by firing a custom DOM event.
52

53
```javascript { .api }
54
/**
55
 * Command LiveReload to shut down by firing a DOM event
56
 * Event target: document
57
 * Event type: 'LiveReloadShutDown'
58
 */
59
const shutdownEvent = document.createEvent('HTMLEvents');
60
shutdownEvent.initEvent('LiveReloadShutDown', true, true);
61
document.dispatchEvent(shutdownEvent);
62
```
63

64
**Usage Examples:**
65

66
```javascript
67
// Shut down LiveReload with a button click
68
document.getElementById('disable-livereload').addEventListener('click', () => {
69
    const event = document.createEvent('HTMLEvents');
70
    event.initEvent('LiveReloadShutDown', true, true);
71
    document.dispatchEvent(event);
72
    
73
    console.log('LiveReload shutdown requested');
74
});
75

76
// Conditional shutdown based on page state
77
function disableInProduction() {
78
    if (window.location.hostname.includes('production')) {
79
        const event = document.createEvent('HTMLEvents');
80
        event.initEvent('LiveReloadShutDown', true, true);
81
        document.dispatchEvent(event);
82
    }
83
}
84
```
85

86
### Event Utilities
87

88
Cross-browser utilities for working with custom DOM events, used internally by LiveReload.
89

90
```javascript { .api }
91
/**
92
 * Cross-browser event binding utility
93
 * @param element - DOM element to bind event to
94
 * @param eventName - Name of the event
95
 * @param handler - Event handler function
96
 */
97
function bind(element, eventName, handler);
98

99
/**
100
 * Cross-browser event firing utility  
101
 * @param element - DOM element to fire event on
102
 * @param eventName - Name of the event to fire
103
 */
104
function fire(element, eventName);
105
```
106

107
**Usage Examples:**
108

109
```javascript
110
// These utilities are used internally by LiveReload
111
// They handle cross-browser compatibility for custom events
112

113
// Example of internal usage (not typically needed in user code):
114
// LiveReload uses these internally for:
115
// bind(document, 'LiveReloadShutDown', shutdownHandler);
116
// fire(document, 'LiveReloadConnect');
117
```
118

119
### Integration Patterns
120

121
Common patterns for integrating LiveReload events with development tools and frameworks.
122

123
**Usage Examples:**
124

125
```javascript
126
// React component that shows LiveReload status
127
class LiveReloadStatus extends React.Component {
128
    constructor(props) {
129
        super(props);
130
        this.state = { connected: false };
131
    }
132
    
133
    componentDidMount() {
134
        document.addEventListener('LiveReloadConnect', () => {
135
            this.setState({ connected: true });
136
        });
137
        
138
        document.addEventListener('LiveReloadDisconnect', () => {
139
            this.setState({ connected: false });
140
        });
141
    }
142
    
143
    render() {
144
        return (
145
            <div className={`status ${this.state.connected ? 'connected' : 'disconnected'}`}>
146
                LiveReload: {this.state.connected ? 'Connected' : 'Disconnected'}
147
            </div>
148
        );
149
    }
150
}
151

152
// Vue.js integration
153
new Vue({
154
    el: '#livereload-status',
155
    data: {
156
        connected: false
157
    },
158
    mounted() {
159
        document.addEventListener('LiveReloadConnect', () => {
160
            this.connected = true;
161
        });
162
        
163
        document.addEventListener('LiveReloadDisconnect', () => {
164
            this.connected = false;
165
        });
166
    },
167
    template: `
168
        <div :class="['status', connected ? 'connected' : 'disconnected']">
169
            LiveReload: {{ connected ? 'Connected' : 'Disconnected' }}
170
        </div>
171
    `
172
});
173

174
// jQuery integration
175
$(document).on('LiveReloadConnect', function() {
176
    $('#livereload-indicator').addClass('connected').removeClass('disconnected');
177
    console.log('LiveReload connected');
178
});
179

180
$(document).on('LiveReloadDisconnect', function() {
181
    $('#livereload-indicator').addClass('disconnected').removeClass('connected');
182
    console.log('LiveReload disconnected');
183
});
184

185
// Development toolbar integration
186
class DevToolbar {
187
    constructor() {
188
        this.setupLiveReloadIntegration();
189
    }
190
    
191
    setupLiveReloadIntegration() {
192
        document.addEventListener('LiveReloadConnect', () => {
193
            this.updateStatus('livereload', 'connected');
194
        });
195
        
196
        document.addEventListener('LiveReloadDisconnect', () => {
197
            this.updateStatus('livereload', 'disconnected');
198
        });
199
        
200
        // Add toggle button
201
        this.addButton('Toggle LiveReload', () => {
202
            if (window.LiveReload) {
203
                const event = document.createEvent('HTMLEvents');
204
                event.initEvent('LiveReloadShutDown', true, true);
205
                document.dispatchEvent(event);
206
            }
207
        });
208
    }
209
}
210
```
211

212
### Event Timing
213

214
Understanding when LiveReload events are fired in relation to other page events.
215

216
**Event Sequence:**
217

218
1. LiveReload script loads and initializes
219
2. Connection attempt begins
220
3. `LiveReloadConnect` event fires when connection succeeds
221
4. During development, file changes trigger reloads
222
5. `LiveReloadDisconnect` event fires if connection is lost
223
6. Automatic reconnection attempts occur
224
7. `LiveReloadConnect` fires again when reconnected
225

226
**Usage Examples:**
227

228
```javascript
229
// Track connection uptime
230
let connectionStartTime = null;
231

232
document.addEventListener('LiveReloadConnect', () => {
233
    connectionStartTime = Date.now();
234
    console.log('LiveReload connection established');
235
});
236

237
document.addEventListener('LiveReloadDisconnect', () => {
238
    if (connectionStartTime) {
239
        const uptime = Date.now() - connectionStartTime;
240
        console.log(`LiveReload was connected for ${uptime}ms`);
241
        connectionStartTime = null;
242
    }
243
});
244

245
// Delay other operations until LiveReload is ready
246
function waitForLiveReload() {
247
    return new Promise((resolve) => {
248
        if (window.LiveReload) {
249
            // Already loaded, check if connected
250
            document.addEventListener('LiveReloadConnect', resolve, { once: true });
251
        } else {
252
            // Wait for script to load
253
            const checkInterval = setInterval(() => {
254
                if (window.LiveReload) {
255
                    clearInterval(checkInterval);
256
                    document.addEventListener('LiveReloadConnect', resolve, { once: true });
257
                }
258
            }, 100);
259
        }
260
    });
261
}
262

263
// Usage
264
waitForLiveReload().then(() => {
265
    console.log('LiveReload is ready and connected');
266
    // Initialize development-specific features
267
});
268
```