Open-ILS/examples/pwa/README.adoc

   1 = Progressive Web App (PWA) =
   2
   3 This document and associated samples will help reproduce the state of the PWA
   4 demonstrated at the Evergreen International Conference 2017 by Dan Scott during
   5 his talk https://stuff.coffeecode.net/2017/evergreen-progressive-web-app[We aim
   6 to misbehave - Evergreen: Progressive Web App].
   7
   8 For a very basic PWA, we need to offer:
   9
  10 . a manifest to give browsers the URL, icons, descriptions, and theme they need
  11   to launch in a fashion similar to native apps
  12 . a service worker that can handle poor or entirely offline network conditions
  13   by intercepting network requests and rerouting them to a dedicated local
  14   cache (if necessary). By bypassing the network, we can also reduce the overall
  15   bandwidth consumed and improve the performance of the application.
  16
  17 We will focus on the public catalogue at /eg/opac and specifically the My Account
  18 section at /eg/opac/myopac. However, the service worker must be registered at
  19 the highest scope to exert control over its assets, and the existence of a
  20 number of relevant CSS and JavaScript files under paths like /js and /css means
  21 it will have to be registered at the root (/).
  22
  23 == Create the service worker ==
  24
  25 . In the `service-worker` directory, run `npm install` to install the
  26   `sw-precache` package.
  27 . Adjust `sw-precache.js` to reflect your site's logo files, etc.
  28 . Run `node_modules/sw-precache/cli.js --config sw-precache.js` to generate
  29   the `service-worker.js` file, based on the configuration in `sw-precache.js`
  30 . Copy `service-worker.js` into the `web` directory.
  31 . Copy the service worker registration template into the public catalogue
  32   templates directory:
  33 +
  34 [source,bash]
  35 ------------------------------------------------------------
  36 cp templates/opac/parts/sw-register.tt2 /openils/var/templates/opac/parts/.
  37 ------------------------------------------------------------
  38 +
  39 . Add the service worker registration code to the `<head>` section of
  40   `templates/opac/parts/base.tt2`:
  41 +
  42 [source,txt]
  43 ------------------------------------------------------------
  44 [% INCLUDE 'opac/parts/sw-register.tt2' %]
  45 ------------------------------------------------------------
  46
  47 == Add a manifest ==
  48
  49 . Add the following lines to `templates/opac/parts/base.tt2`:
  50 +
  51 [source,html]
  52 ------------------------------------------------------------
  53 <link rel="manifest" href="/manifest.json">
  54 <link rel="icon" sizes="192x192" href="/images/icon192.png">
  55 <meta name="theme-color" content="#007a54">
  56 ------------------------------------------------------------
  57 +
  58 . Adjust the manifest details to suit your theme and site name:
  59 .. Keep the `name` and `short_name` fields to 12 characters or
  60    less, and keep them the same.
  61 .. Also match the `theme-color` `<meta>` value with the `theme_color` field in
  62    the manifest.
  63
  64 == Deploy the code! ==
  65
  66 . Copy the contents of the `web` directory into `/openils/var/web`:
  67 +
  68 [source,bash]
  69 ------------------------------------------------------------
  70 cp -r web/* /openils/var/web/.
  71 ------------------------------------------------------------
  72
  73 == Optimizations ==
  74
  75 If you are running the staff client with requests proxied by nginx, you can
  76 take advantage of the support that has been built into modern versions of
  77 nginx for the https://http2.github.io/[HTTP/2] protocol and gain the advantages
  78 of multiplexing by simply adding 'http2' to your `listen` line:
  79
  80 [source,txt]
  81 ------------------------------------------------------------
  82 server {
  83     listen 443 ssl http2;
  84 ------------------------------------------------------------
  85
  86 We're loading Dojo on every page, even though by default the only page that
  87 absolutely requires it is the advanced search page. This results in
  88 approximately an extra half-second initial page load time, which makes
  89 https://developers.google.com/web/tools/lighthouse/[Lighthouse] unhappy about
  90 our performance. The https://bugs.launchpad.net/evergreen/+bug/1411699[Don't
  91 load Dojo widgets] branch shifts the requirement to only the advanced search
  92 page.
  93
  94 Our "My Account" pages are currently hard-coded as `Expires: -1` and
  95 `Cache-Control: no-store` which makes browsers reluctant to cache them,
  96 understandably. The behaviour of the `sw-precache` generator appears to be to
  97 respect the header and not cache the request. Commit e7f11d5 in this branch
  98 removes the hard-coded setting from `EGCatLoader.pm` and enables us to control
  99 this in the HTTP server configuration instead.
 100
 101 See https://bugs.launchpad.net/evergreen/+bug/1681095[Extend browser
 102 cache-busting branch] for a way to greatly extend the cache expiration for all
 103 non-HTML assets while still allowing changes to propagate quickly, if
 104 necessary.
 105
 106 == Limitations ==
 107
 108 There are currently many!
 109
 110 As the public catalogue currently appends stateful GET params to URLs, even when
 111 accessing `My Account`, the cached content can often only be accessed if you
 112 follow the same path to access a given page when offline. For example, if you
 113 start a session by searching for "Potter", and then click on "My Account", any
 114 of the account pages you visit will have a `;query=Potter` param attached to
 115 their URL. If you happen to perform a different search, then access "My Account",
 116 you may not be able to access the page at all, or you might see different cached
 117 results.
 118
 119 Searching offline doesn't make much sense anyway. Ideally we would detect when
 120 network conditions are bad and serve up an offline page with options greyed out
 121 if they are unlikely to work, with highlighting of options that are available
 122 offline.
 123
 124 == Icon credits ==
 125
 126 The icons in `web/images` are based on the PWA logo made freely available by
 127 Chris Love at https://github.com/docluv/pwa-logo under the terms _The logo
 128 should be considered publically available for everyone to use._