npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

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

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.

Possible additional requirements for older browsers

See EventSource polyfill docs

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.