sentioo-vue-3

A configurable notification system, based on server sent events (SSE): it displays notifications that are published by the backend on a server-sent-events feed. It can be integrated as a module in a Vue.js web application. Now compatible with Vue3.

For further documentation please read the old package's documentation.

Package installation and use

Install in your project as a NPM dependency:

#Install in your project as a NPM dependency:
yarn add sentioo-vue-3

# In your "main.ts" (or main.js) file:
import 'sentioo-vue-3/dist/lib/sentioo.css';
import ExmSentioo from 'sentioo-vue-3';
createApp(App).use(ExmSentioo).mount('#app');

# In your "component.vue" file:
<exm-sentioo :server-url="serverUrl"></exm-sentioo>

Where serverUrl is the endpoint pointing to your server's SSE notification service.

# In a Quasar Framework boot file:
import 'sentioo-vue-3/dist/lib/sentioo.css';
import ExmSentioo from 'sentioo-vue-3';

export default ({ app }) => {
  app.use(ExmSentioo);
};

Development

# install dependencies
yarn install

Compiles and hot-reloads for development

App.vue file instantiate the component in two ways:

1. the deployed NPM package version: (useful to test the deployed version)
2. the local component implementation: (useful during development)

# Run in develoment mode:
yarn serve

The default configuration starts a local dev server on http://localhost:8080.

Developing, building, and deploying a release

# 1. Write your code, then update the package version in package.json
"version": "0.8.3"

# 2. Build as a library:
yarn build:lib

# 3. Commit and push your changes on git repo

# 4. Publish on NPM
npm publish

# 5. Update your project's dependency, depending on your needs:
yarn remove sentioo-vue-3
yarn add sentioo-vue-3

Test server

You can run a test server, which sends a predefined notification, using the test_see_server.jsfile. Just run in your terminal:

node test_sse_server.js

The NodeJs server starts on port 3000, and listens for connections (CORS enabled) from origin http://localhost:8080. The policy is defined by: 'Access-Control-Allow-Origin': 'http://localhost:8080'.

Server response body

Event stream format

<field>:<value>\n
<field>:<value>\n
<field2>:<value>\n\n

Example response

event: notify\n
id: 123\n
data: { "title": "Notification Title",
  "text": "Lorem ipsum.",
  "priority": 2,
  "id": "1345f488-5aaa-4c4b-9076-f3eb12905556",
  "unread": true,
  "time": "Fri, 15 Dec 2017 08:53:12 GMT" }\n\n

The connection is kept open, and new events should be sent to the same connection using the specified format.

Notification format

{
  "title": "Notification Title",
  "text": "Notification text content",
  "priority": 2, // priority level of the notification
  "id": "unique ID",
  "unread": true,
  "time": "Fri, 15 Dec 2017 08:53:12 GMT",
  "type": "broadcast" // OPTIONAL
}

All fields are mandatory, except for the type.

The text field can contain html tags and they will be rendered (e.g. links). Be aware that this may be unsafe if the notification contents are user generated.

The type field is completely optional, and in our implementation is used to avoid potential collisions between notification IDs generated by the backend, since in our case they are stored in multiple tables. This issue is very implementation-specific, and therefore for most use cases that field can be left empty.

Possible additional requirements for older browsers

See EventSource polyfill docs

EventSource references

https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events https://developer.mozilla.org/en-US/docs/Web/API/EventSource

License

Copyright 2018 ExMachina SAGL (http://www.exmachina.ch)

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.