Skip to content

Commit

Permalink
Switch to ServiceWorker Mode by default #196 (#903)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Jaifroid
Jaifroid authored Oct 24, 2022
1 parent b737a8b commit b678034
Show file tree
Hide file tree
Showing 3 changed files with 127 additions and 55 deletions.
75 changes: 38 additions & 37 deletions www/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -176,11 +176,11 @@ <h4>Step 1: Download some content</h4>
everything except video and audio. Larger versions without any of these qualifiers contain everything, though pictures are always compressed.
</p>
<p>
<strong>Currently only Mediawiki-based content (for instance <a href="https://download.kiwix.org/zim/wikipedia/"
target="_blank">Wikipedia&nbsp;<img src="img/Icon_External_Link.png" /></a> and <a href="https://download.kiwix.org/zim/wikivoyage/" target="_blank">
Wikivoyage&nbsp;<img src="img/Icon_External_Link.png" /></a>), and <a href="https://download.kiwix.org/zim/stack_exchange/" target="_blank"> StackExchange&nbsp;<img
src="img/Icon_External_Link.png" /></a>, have been thoroughly tested</strong>. Dynamic content (e.g. PhET) is only supported in ServiceWorker Mode
(see <a href="#modes">technical explanation</a> below).
<strong>Dynamic content (e.g. PhET, or the proprietary User Interface in Gutenberg and TED Talks ZIMs) is supported in ServiceWorker Mode only (the default),
but not in JQuery mode (see <a href="#modes">technical explanation</a> below). If you cannot run ServiceWorker mode, then you will most likely be limited to
static Mediawiki-based content (for instance <a href="https://download.kiwix.org/zim/wikipedia/" target="_blank">Wikipedia&nbsp;<img src="img/Icon_External_Link.png" /></a>
and <a href="https://download.kiwix.org/zim/wikivoyage/" target="_blank">Wikivoyage&nbsp;<img src="img/Icon_External_Link.png" /></a>), and
<a href="https://download.kiwix.org/zim/stack_exchange/" target="_blank"> StackExchange&nbsp;<img src="img/Icon_External_Link.png" /></a>.</strong>
</p>
<p>
For a quick test, you can start with the <a href="https://download.kiwix.org/zim/wikipedia_en_ray_charles_maxi.zim" target="_blank">
Expand Down Expand Up @@ -299,36 +299,37 @@ <h4 id="FAT">Downloading and storing large archives</h4>
</p>
<p style="text-align: right"><a href="#contents">↑ Back to Contents</a></p>

<h4 id="modes">JQuery and ServiceWorker Modes</h4>
<h4 id="modes">ServiceWorker and JQuery Modes</h4>
<p>
Depending on your browser or framework, this app may be capable of running in two different modes, which we call
"JQuery Mode" and "ServiceWorker Mode" for short. There is a toggle under Compatibility Settings in Configuration.
"ServiceWorker Mode" and "JQuery Mode" for short. There is a toggle under Compatibility Settings in Configuration.
Here is a technical explanation of what these modes do:
<ul>
<li>
<b>JQuery Mode</b>: This mode (which does not in fact require JQuery) is fine for everyday use with
Wikipedia / WikiMedia archives, and is stable and safe. It is a way of inserting articles extracted from the
ZIM into the DOM (browser document) by injecting the content into an iframe or tab. We then use
native DOM methods, or sometimes JQuery, to parse the article's HTML and insert required assets
(images, stylesheets, event listeners for hyperlinks, etc.). On old devices DOM traversal can be slow,
but it is compensated for because we do not extract or run JavaScript assets (which would be technically
extremely complicated). As a result, for WikiMedia archives this mode is usually quite fast. On the downside,
ZIMs that have a proprietary dynamic UI (such as Gutenberg or TED talks) are only partially supported in this
mode: the UI does not work, but articles can be searched for and loaded from the search bar. This mode is
compatible with older browsers and frameworks.
<b>ServiceWorker Mode</b>: This is the default mode. As its name implies, it requires that the browser or framework
be capable of installing a Service Worker, which is usually the case in modern browsers. It works by intercepting
the browser or framework's Fetch calls (network requests) and supplying the requested content from the ZIM. In this
mode, the content is read and supplied as-is from the archive to the browser. Dynamic content (e.g. JavaScript) and
proprietary UIs are fully supported in this mode. However, Zimit archives are <b>not</b> currently supported due to
a conflict between the Kiwix JS Service Worker and the WARC Service Worker. This mode can feel initially a little
slower than JQuery mode until commonly used assets are cached, but it soon equals JQuery mode in speed, at least in
modern browsers. However, older browsers such as IE11 are incompatible with this mode, and the app must be running
in a secure context (<code>https:</code>, <code>localhost</code>, or certain browser extensions). While this mode is
not natively supported in Mozilla (Firefox) browser extensions, we provide a functional workaround by re-launching
the extension as a Progressive Web App (PWA). Note that this mode cannot run with the <code>file:</code> protocol
(but only IE11 and old Edge allow the app to run by launching <code>index.html</code> from the file system).
</li>
<li>
<b>ServiceWorker Mode</b>: This mode, as its name implies, requires that the browser or framework be capable of
installing a Service Worker. It works by intercepting the browser or framework's Fetch calls (network requests)
and supplying the requested content from the ZIM. This mode requires no DOM traversal, and the content is
read and supplied as-is from the archive. Dynamic content (e.g. JavaScript) and proprietary UIs are fully
supported in this mode. It can feel initially a little slower while commonly used assets are being cached,
but it soon equals JQuery mode in speed, at least in modern browsers. However, older browsers such as IE11 are
incompatible with this mode, and the app must be running in a secure context (<code>https:</code>, <code>localhost</code>,
or certain browser extensions). While this mode is not natively supported in Mozilla (Firefox) browser
extensions, we provide a functional workaround by re-launching the extension as a Progressive Web App (PWA).
Note that this mode cannot run with the <code>file:</code> protocol (but only IE11 and old Edge allow the app to run
by launching <code>index.html</code> from the file system).
<b>JQuery Mode</b>: This mode is now deprecated (and does not in fact require JQuery). It is retained for
compatibility with older browsers or frameworks that cannot run Service Workers. The mode has limitations which
mean that only static content can be displayed, such as that found in Wikipedia / WikiMedia archives and (for now)
Stackexchange. It is a way of inserting articles extracted from the ZIM into the DOM (browser document) by injecting
the content into an iframe or tab. We then use native DOM methods, or sometimes JQuery, to parse the article's HTML
and insert required assets (images, stylesheets, event listeners for hyperlinks, etc.). On old devices, DOM traversal
can be slow, but it is compensated for because we do not extract or run JavaScript assets (which would be technically
extremely complicated). As a result, for WikiMedia archives this mode is usually quite fast. On the downside, ZIMs
that have a proprietary dynamic UI (such as Gutenberg or TED talks) are only partially supported in this mode: the UI
does not work, but articles can be searched for and loaded from the search bar.
</li>
</ul>
</p>
Expand Down Expand Up @@ -568,18 +569,18 @@ <h3>Compatibility settings</h3>
<div class="card-header">Content injection mode</div>
<div class="card-body">
<p>See <a href="#modes" id="modesLink">About (Technical Information)</a> for an explanation of the difference between these modes:</p>
<div class="radio">
<label title="This mode is fine for everyday use with Wikipedia / WikiMedia archives, and is stable and safe.">
<input type="radio" name="contentInjectionMode" value="jquery"
id="jQueryModeRadio" checked>
<strong>JQuery</strong> (compatible with older browsers and frameworks)
</label>
</div>
<div class="radio">
<label title="This mode requires that the browser or framework be capable of installing a Service Worker. It works by intercepting the browser or framework's Fetch calls and supplying the requested content from the ZIM.">
<input type="radio" name="contentInjectionMode" value="serviceworker"
id="serviceworkerModeRadio">
<strong>ServiceWorker</strong> (supports archives with dynamic content)
<strong>ServiceWorker</strong> (default, supports archives with dynamic content)
</label>
</div>
<div class="radio">
<label title="This mode is deprecated, but should be fine for Wikipedia / WikiMedia archives. It works on all devices.">
<input type="radio" name="contentInjectionMode" value="jquery"
id="jQueryModeRadio" checked>
<strong>JQuery</strong> (deprecated, but compatible with older browsers and frameworks)
</label>
</div>
</div>
Expand Down Expand Up @@ -663,7 +664,7 @@ <h3>Expert settings</h3>
<button type="button" class="close" data-hide="alert">&times;</button>
<strong>Unable to display active content:</strong> This ZIM is not fully supported in jQuery mode.<br />
Content may be available by searching above (type a letter of the alphabet), or else
<a id="swModeLink" href="#contentInjectionModeDiv" class="alert-link">switch to Service Worker mode</a>
<a id="swModeLink" href="#contentInjectionModeDiv" class="alert-link">switch to ServiceWorker mode</a>
if your platform supports it. &nbsp;[<a id="stop" href="#expertSettingsDiv" class="alert-link">Permanently hide</a>]
</div>
</div>
Expand Down
Loading

0 comments on commit b678034

Please sign in to comment.