Eleanor Holley
15 Mar 2021
•
4 min read
This article will serve to document and demonstrate the rescript-notifications
npm package, a complete set of bindings for the JavaScript-compiling ReScript language (formerly BuckleScript/ReasonML). At the close of this article, the reader should be able to enable and display notifications in an entirely type safe and functional way.
Be advised that there are some limitations to web notifications, and I encourage the reader to review the JavaScript Notifications API documentation. TL;DR: Notifications require an HTTPS connection, and they are widely but not universally supported.
This article is meant to be both a tutorial and a demo. While I've included the code snippets I think are important, I also want to give a tour of the source so that the reader can browse it in context.
I am adapting this article for Functional Works by stripping out the demo-ness of it all.
So feel free to read how you want! But if you'd like to see the notifications, visit the live demo site on my blog.
You'll need to install the rescript-notifications
npm package and add it to your bsconfig.json in the usual way.
I'm also using a local clone of bs-webapi
, although of course you can always just write your own bindings for DOM manipulation.
Lastly, I just want to flag that I'm using two open
statements like so:
open Notifications;
open Webapi.Dom;
(I usually try to limit myself to two or three open statements per file.)
The first thing to establish is notification permissions. We do this through the Notification.permission
static property and the Notification.requestPermission()
static method.
For example:
NotificationsDemo.res
open Notifications;
open Webapi.Dom;
window |> Window.addEventListener("load", _ => {
let spanPermissions: option<Dom.element> =
Document.querySelector(# span-permission", document);
let setSpanText = (span: option<Dom.element>, text: string): unit => {
let _ = span -> Belt.Option.map(span => Element.setInnerText(span, text));
Js.log("Permission text: " |> Js.String.concat(text));
};
let _ = spanPermissions -> setSpanText(Notification.permission);
let onBtnRequestClick = (event: Dom.event): unit => {
Js.log("button-request clicked.");
let _ = Notification.requestPermission()
|> Js.Promise.then_(str => {
spanPermissions -> setSpanText(str)
|> Js.Promise.resolve
});
};
let _ = Document.querySelector(# button-request", document)
-> Belt.Option.map(btn => {
btn |> Element.addEventListener("click", onBtnRequestClick);
Js.log("button-request event added.");
});
});
As you can see, this demo sets the span
text to the current notification permission state and then wires up an even to the button to ask for permission and update the span
accordingly. You can see the result below:
Demo omitted in cross-post
Go ahead and grant permission if you'd like--I am only using notifications for the purposes of this demo. Ordinarily, I would hide the button after permission has been granted because it only works once, but as a demo this is fine.
As long as permissions are granted, notifications are displayed as soon as they're constructed.
The rescript-notifications
binding includes two Notification constructors, makeWithoutOptions
and makeWithOptions
.
Notifications are typed with a type parameter because they can include a data object of any datatype. If you don't need it, you can always just use a throwaway object of some sort.
The options object includes a lot of properties that the calling code won't necessarily need (and isn't necessarily widely supported), so the library includes an init
function for convenience.
NotificationsDemo.res continues:
let onBtnNotifyClick = (_: Dom.event): unit => {
Js.log("button-notify clicked.");
let _ = Notification.makeWithoutOptions("You have been notified.");
};
let onBtnWithOptionsClick = (_: Dom.event): unit => {
Js.log("button-with-options clicked.");
let options: NotificationOptions.t<string> = {
...NotificationOptions.init(Js.Nullable.return("unused data.")),
icon: "https://webbureaucrat.gitlab.io/img/icons/192.png",
body: "with an icon and additional text."
};
let _ = Notification.makeWithOptions("You have been thoroughly notified", options);
};
let _ = Document.querySelector(# button-notify", document)
-> Belt.Option.map(btn => {
btn
|> Element.addEventListener("click", onBtnNotifyClick);
});
let _ = Document.querySelector(# button-with-options", document)
-> Belt.Option.map(btn => {
btn
|> Element.addEventListener("click", onBtnWithOptionsClick);
});
As you can see, the click events call the make
methods, which, by ReScript convention, bind to the Notification object constructor. The notifications will appear as soon as they are constructed.
The feel free to play with the live demo below:
Demo omitted in cross-post
This has been a quick demonstration of using JavaScript notifications in a type-safe way using ReScript. I hope you have found this helpful and informative, and, as always, feel free to reach out with questions or comments.
Ground Floor, Verse Building, 18 Brunswick Place, London, N1 6DZ
108 E 16th Street, New York, NY 10003
Join over 111,000 others and get access to exclusive content, job opportunities and more!