raisetheapp
v1.1.0
Published
A configurable notification system that can be integrated as a module in a Vue.js web application.
Downloads
9
Readme
RaiseTheApp
Description
RaiseTheApp is a configurable notification system that can be integrated as a module in a Vue.js web application. It displays notifications that are published by the backend on a server-sent-events feed.
Run and build
# install dependencies
npm install
# serve with hot reload at localhost:8080
npm run dev
# build for production as Vue.js module
npm run build
# run all tests
npm test
Use as a Vue.js module
Add dependencies
Add as npm module in package.json
, either as path to folder or to git repo.
Note that the repo/path must have a valid package.json
in the root.
// ...
"raisetheapp": "<repo_url.git> | file:<path to folder>",
// ...
Note: if the path is a git repository, the dist
folder (i.e. the build output) must be committed.
External dependencies (i.e. not bundled in the module)
- Vue
- Vuex
- font-awesome
Import RaiseTheApp Vue.js component
import RaiseTheApp from 'raisetheapp';
// ...
// in HTML
<raise-the-app :server-url="..."></raise-the-app>
// ...
// Inside component definition:
components: { /* <other child components>, */ RaiseTheApp }
// ...
Import RaiseTheApp Vuex store
import { raiseTheAppStore } from 'raisetheapp';
store.registerModule('raiseTheApp', raiseTheAppStore);
Where store
is the existing Vuex store, otherwise create a new one.
This will add the store as a module to the existing one.
Import styling
import 'raisetheapp/dist/lib/static/app.min.css';
(needs webpack
with css-loader
)
API
EventSource docs
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
Setup Server for event streams
The client will subscribe to an event stream through a GET request when EventSource
is instantiated.
Example request:
GET <server-url:port>/subscribe
.
Setup server URL
The server URL must be setup by passing it as the server-url
prop when declaring the Vue.js component in the HTML.
<raise-the-app :server-url="http://..."></raise-the-app>
Server response headers
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
Server response body
<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.
Possible additional requirements for older browsers
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.
Notification read/delete requests
Set a single notification as read (happens when clicking the checkmark button)
POST <server-url:port>/notifications/:notification-id/read
Client expects just a status: 200
if succeeded.
Delete a notification (happens when clicking the "trash" button)
POST <server-url:port>/notifications/:notification-id/delete
Client expects just a status: 200
if succeeded.
Set all unread notifications as read
POST <server-url:port>/notifications/readAll
Client expects just a status: 200
if succeeded.
Delete all notifications
POST <server-url:port>/notifications/deleteAll
Client expects just a status: 200
if succeeded.
Optional query params
If needed, additional params can be configured to be sent with the read/delete requests.
Note that the parameter names must be fields of the Notification
interface (see src/lib/Notification.ts
). These are used if, for some reason, the server needs additional information regarding the affected notification.
Usage of event streams
Adding new event-stream listeners
Example
let connection: SSEConnection = new SSEConnection(`<stream_url>`);
connection.on(`<event_name>`, (evt: SSEEvent) => {
let data = JSON.parse(evt.data);
let id = JSON.parse(evt.id);
// ...
});
Where connection
must be of type SSEConnection
, and <event_name>
corresponds to the event type defined inside the stream response body.
For more features see the SSEConnection.ts
class.
Configuration and theming
Config file
src/config/config.json
example
{
// Priority levels
// "priority" field inside notification selects the
"levels" : [
{
"icon" : "fa-envelope-o", // must be a font-awesome icon name
"color" : "#4CAF50",
"backgroundColor" : "#C8E6C9",
"hoverColor" : "#E8F5E9"
},
// ...
],
// Show unread/important text on top of notification list
// e.g. "3 unread notifications (1 important)
"showUnreadText" : false,
// Length of notification text excerpt when
// notification is not expanded.
"excerptSize": 50,
// Change notification icon background color
// depending on the highest-priority unread notification's
"dynamicIconColor": false,
// Set-up query parameters for read/delete notification requests
// Note: they both are _optional_.
// "readParams": ["type"],
// "deleteParams": ["type"]
}
Configuration can be overridden at runtime by passing a new json (with the same format) as a prop into the component:
<raise-the-app :server-url="http://..." :config="newConfig"></raise-the-app>
Style
Edit .scss
files in src/theme
folder, where there's a file for each component.
Open Issues
Configuration and theming
The main theming issue is styling notifications based on their priority.
Right now, the priority-specific style is defined inside the src/config/config.json
file, since the number of priority levels is not fixed, and the JS code has to know it.
One possible rework is to only theme using *.scss
files, and for each notification priority level we add a class with a name such as notification-X
, where X
is the priority level.
In that case, the number of classes must be defined somewhere also in the config.
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.