From: Dan Scott Date: Fri, 14 Apr 2017 04:29:04 +0000 (-0400) Subject: Add Progressive Web App examples and docs X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=fc584eddbe695e08befed621802aaea281019c9a;p=working%2FEvergreen.git Add Progressive Web App examples and docs Reflect the state of the Evergreen PWA as presented at the 2017 Evergreen International Conference. Signed-off-by: Dan Scott --- diff --git a/Open-ILS/examples/pwa/README.adoc b/Open-ILS/examples/pwa/README.adoc new file mode 100644 index 0000000000..8bc0e2393b --- /dev/null +++ b/Open-ILS/examples/pwa/README.adoc @@ -0,0 +1,128 @@ += Progressive Web App (PWA) = + +This document and associated samples will help reproduce the state of the PWA +demonstrated at the Evergreen International Conference 2017 by Dan Scott during +his talk https://stuff.coffeecode.net/2017/evergreen-progressive-web-app[We aim +to misbehave - Evergreen: Progressive Web App]. + +For a very basic PWA, we need to offer: + +. a manifest to give browsers the URL, icons, descriptions, and theme they need + to launch in a fashion similar to native apps +. a service worker that can handle poor or entirely offline network conditions + by intercepting network requests and rerouting them to a dedicated local + cache (if necessary). By bypassing the network, we can also reduce the overall + bandwidth consumed and improve the performance of the application. + +We will focus on the public catalogue at /eg/opac and specifically the My Account +section at /eg/opac/myopac. However, the service worker must be registered at +the highest scope to exert control over its assets, and the existence of a +number of relevant CSS and JavaScript files under paths like /js and /css means +it will have to be registered at the root (/). + +== Create the service worker == + +. In the `service-worker` directory, run `npm install` to install the + `sw-precache` package. +. Adjust `sw-precache.js` to reflect your site's logo files, etc. +. Run `node_modules/sw-precache/cli.js --config sw-precache.js` to generate + the `service-worker.js` file, based on the configuration in `sw-precache.js` +. Copy `service-worker.js` into the `web` directory. +. Copy the service worker registration template into the public catalogue + templates directory: ++ +[source,bash] +------------------------------------------------------------ +cp templates/opac/parts/sw-register.tt2 /openils/var/templates/opac/parts/. +------------------------------------------------------------ ++ +. Add the service worker registration code to the `` section of + `templates/opac/parts/base.tt2`: ++ +[source,txt] +------------------------------------------------------------ +[% INCLUDE 'opac/parts/sw-register.tt2' %] +------------------------------------------------------------ + +== Add a manifest == + +. Add the following lines to `templates/opac/parts/base.tt2`: ++ +[source,html] +------------------------------------------------------------ + + + +------------------------------------------------------------ ++ +. Adjust the manifest details to suit your theme and site name: +.. Keep the `name` and `short_name` fields to 12 characters or + less, and keep them the same. +.. Also match the `theme-color` `` value with the `theme_color` field in + the manifest. + +== Deploy the code! == + +. Copy the contents of the `web` directory into `/openils/var/web`: ++ +[source,bash] +------------------------------------------------------------ +cp -r web/* /openils/var/web/. +------------------------------------------------------------ + +== Optimizations == + +If you are running the staff client with requests proxied by nginx, you can +take advantage of the support that has been built into modern versions of +nginx for the https://http2.github.io/[HTTP/2] protocol and gain the advantages +of multiplexing by simply adding 'http2' to your `listen` line: + +[source,txt] +------------------------------------------------------------ +server { + listen 443 ssl http2; +------------------------------------------------------------ + +We're loading Dojo on every page, even though by default the only page that +absolutely requires it is the advanced search page. This results in +approximately an extra half-second initial page load time, which makes +https://developers.google.com/web/tools/lighthouse/[Lighthouse] unhappy about +our performance. The https://bugs.launchpad.net/evergreen/+bug/1411699[Don't +load Dojo widgets] branch shifts the requirement to only the advanced search +page. + +Our "My Account" pages are currently hard-coded as `Expires: -1` and +`Cache-Control: no-store` which makes browsers reluctant to cache them, +understandably. The behaviour of the `sw-precache` generator appears to be to +respect the header and not cache the request. Commit e7f11d5 in this branch +removes the hard-coded setting from `EGCatLoader.pm` and enables us to control +this in the HTTP server configuration instead. + +See https://bugs.launchpad.net/evergreen/+bug/1681095[Extend browser +cache-busting branch] for a way to greatly extend the cache expiration for all +non-HTML assets while still allowing changes to propagate quickly, if +necessary. + +== Limitations == + +There are currently many! + +As the public catalogue currently appends stateful GET params to URLs, even when +accessing `My Account`, the cached content can often only be accessed if you +follow the same path to access a given page when offline. For example, if you +start a session by searching for "Potter", and then click on "My Account", any +of the account pages you visit will have a `;query=Potter` param attached to +their URL. If you happen to perform a different search, then access "My Account", +you may not be able to access the page at all, or you might see different cached +results. + +Searching offline doesn't make much sense anyway. Ideally we would detect when +network conditions are bad and serve up an offline page with options greyed out +if they are unlikely to work, with highlighting of options that are available +offline. + +== Icon credits == + +The icons in `web/images` are based on the PWA logo made freely available by +Chris Love at https://github.com/docluv/pwa-logo under the terms _The logo +should be considered publically available for everyone to use._ diff --git a/Open-ILS/examples/pwa/sw-precache.js b/Open-ILS/examples/pwa/sw-precache.js new file mode 100644 index 0000000000..dff6001dac --- /dev/null +++ b/Open-ILS/examples/pwa/sw-precache.js @@ -0,0 +1,47 @@ +module.exports = { + staticFileGlobs: [ + '/openils/var/web/favicon.ico', + '/openils/var/web/offline.html', + '/openils/var/web/js/sw-register.js', + '/openils/var/web/css/skin/default/opac/semiauto.css', + '/openils/var/web/js/ui/default/opac/simple.js', + '/openils/var/web/opac/images/small_logo.png', + '/openils/var/web/opac/images/progressbar_green.png', + '/openils/var/web/opac/images/main_logo.png', + '/openils/var/web/opac/images/eg_tiny_logo.png' + ], + stripPrefix: '/openils/var/web/', + runtimeCaching: [ + // aggressively cache images + { + urlPattern: /\.(gif|jpg|jpeg|png)$/, + handler: 'fastest' + }, + // aggressively cache stylesheets and JavaScript + { + urlPattern: /\.(css|js)$/, + handler: 'fastest' + }, + // cache added content too + { + urlPattern: /\/opac\/extras\/ac\//, + handler: 'fastest' + }, + // results can take a long time to respond + { + urlPattern: /\/eg\/opac\/results\//, + handler: 'networkFirst', + options: { + networkTimeoutSeconds: 60 + } + }, + // prefer the network, but fall back to the cache + { + urlPattern: /\/(eg|js|opac|staff)\//, + handler: 'networkFirst', + options: { + networkTimeoutSeconds: 4 + } + } + ] +}; diff --git a/Open-ILS/examples/pwa/templates/opac/parts/sw-register.tt2 b/Open-ILS/examples/pwa/templates/opac/parts/sw-register.tt2 new file mode 100644 index 0000000000..c9681abbe9 --- /dev/null +++ b/Open-ILS/examples/pwa/templates/opac/parts/sw-register.tt2 @@ -0,0 +1,61 @@ + diff --git a/Open-ILS/examples/pwa/web/images/icon192.png b/Open-ILS/examples/pwa/web/images/icon192.png new file mode 100644 index 0000000000..b978eb0b02 Binary files /dev/null and b/Open-ILS/examples/pwa/web/images/icon192.png differ diff --git a/Open-ILS/examples/pwa/web/images/icon48.png b/Open-ILS/examples/pwa/web/images/icon48.png new file mode 100644 index 0000000000..cae1525a93 Binary files /dev/null and b/Open-ILS/examples/pwa/web/images/icon48.png differ diff --git a/Open-ILS/examples/pwa/web/images/icon96.png b/Open-ILS/examples/pwa/web/images/icon96.png new file mode 100644 index 0000000000..d7d101d601 Binary files /dev/null and b/Open-ILS/examples/pwa/web/images/icon96.png differ diff --git a/Open-ILS/examples/pwa/web/manifest.json b/Open-ILS/examples/pwa/web/manifest.json new file mode 100644 index 0000000000..364d51e566 --- /dev/null +++ b/Open-ILS/examples/pwa/web/manifest.json @@ -0,0 +1,27 @@ + + "short_name": "Shiny Cap'n", + "name": "Shiny Cap'n", + "description": "A shiny Evergreen progressive web app (PWA)", + "background_color": "#007a54", + "theme_color": "#007a54", + "icons": [ + { + "src": "/images/icon48.png", + "type": "image/png", + "sizes": "48x48" + }, + { + "src": "/images/icon96.png", + "type": "image/png", + "sizes": "96x96" + }, + { + "src": "/images/icon192.png", + "type": "image/png", + "sizes": "192x192" + } + ], + "start_url": "/eg/opac/home", + "display": "standalone", + "orientation": "portrait" +}