A Leaflet plugin to enable real-time data updates using server sent events.
The events published by the server must have a valid geojson feature in the data
field.
The geojson feature's properties must include a field that uniquely identifies the feature. This identifier is used to facilitate replacement of the current feature with its updated instance when the server sends an update event.
{
"data": {
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [125.6, 10.1]
},
"id": 1,
"properties": {
"name": "My Feature"
}
}
}
Add the file to your map HTML head tag below LeafletJS.
<!-- Insert below LeafletJs -->
<script
type="text/javascript"
src="https://www.unpkg.com/browse/leaflet-geosse@1.0.1/dist/Leaflet.GeoSSE.min.js"
></script>
Initialize same as any L.geoJson
instance. You must pass in a streamUrl
and optional featureIdField
to identify the event source and individual features respectively.
Initialize an empty layer when you don't care about history and only want to monitor events that are created after establishing connection to event stream.
var sseLyr = L.geoSSE(null, {
streamUrl: "https://my-site.com/stream",
// set other layer options...
});
Alternatively you can initialize with some existing data when you want to establish the initial state by loading previously created features on connection to event stream.
var sseLyr = L.geoSSE('my-data.geojson', {
streamUrl: 'https://my-site.com/stream'
// set other layer options...
});
// Connect to an event stream.
sseLyr.connectToEventStream();
When a successful connection is established, by default the layer listens for the following types of events:
- Add event
When an
add
event is received from the server, the feature is added or updated. - Remove event
When a
remove
event is received from the server, the feature is removed.
- Create event
When a
create
event is received from the server, the feature is added. - Update event
When an
update
event is received from the server, the feature is replaced. Update events are sent after any change to one or more feature properties. - Delete event
When a
delete
event is received from the server, the feature is removed. Alias ofremove
event.
In addition to standard events, you can configure your event server to return any other type of events. For example, if your server will be sending crash
events you can monitor and handle that event by attaching an event listener.
// Listen for crash event and log data to console.
sseLyr.eventSource.addEventListener(
"crash",
function crashEvent(event) {
console.log(event.data);
},
false
);
This will only stop monitoring the crash
event. Note the second and third arguments to removeEventListener
must match the listener function name and useCapture
boolean that was entered in the addEventListener
call above.
// Stop listening for crash events.
sseLyr.eventSource.removeEventListener("crash", crashEvent, false);
Disconnect from the source to stop listening to all events and close the connection to the server.
sseLyr.disconnect();
Switching streams just involves passing in a new stream url and unique id field to switchStream()
.
sseLyr.switchStream("https://some-other/stream", "otherFieldId");
If you want to remove all currently displayed features in your layer when switching streams simply add a boolean of true
as the third argument. By default, all features that were loaded by the old stream will remain after connecting to the new stream.
sseLyr.switchStream("https://some-other/stream", "otherFieldId", true);
To see the working example of this plugin locally
# install dependencies if needed
npm install -w examples
npm run dev -w examples
An example map will be available at localhost:3000
where you can see point features being created, updated and deleted.