Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Switch to sw mode by default #903

Merged
merged 36 commits into from
Oct 24, 2022
Merged

Switch to sw mode by default #903

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
36 commits
Select commit Hold shift + click to select a range
e0edfee
First step to switch to SW mode by default
mossroy Aug 4, 2022
7194ee9
Inform the user if we switch to SW mode (untested)
mossroy Aug 5, 2022
6d0e45c
Clean up some typos and better formatting
Jaifroid Oct 16, 2022
8412840
Simplify variable naming
Jaifroid Oct 16, 2022
d5a2ada
Complete variable name simplification
Jaifroid Oct 16, 2022
b7a7e29
Edit switching logic
Jaifroid Oct 16, 2022
ee68e2b
Remove bootstrap code and use systemAlert
Jaifroid Oct 16, 2022
27fb93c
Change variable descriptor and add preliminary support for moz-extension
Jaifroid Oct 16, 2022
c0c92e0
Conditional messaging for FF extension
Jaifroid Oct 16, 2022
ce65bf9
Deal with default mode change alert if FF extension has launched PWA
Jaifroid Oct 16, 2022
7b5bac1
Deal with case where use cancels switch to SW mode
Jaifroid Oct 16, 2022
c24e3db
Fix inverted messaging instructions!
Jaifroid Oct 16, 2022
c5ed6b1
Set PWA server to development PWA
Jaifroid Oct 16, 2022
897e024
Add messaging for when SW mode is unsupported
Jaifroid Oct 16, 2022
65fa546
Add some handling for reverting to jQuery mode
Jaifroid Oct 16, 2022
f2b203a
Attempt to jump straight back to jQuery mode
Jaifroid Oct 16, 2022
3809b3b
Make clear it is an attempt
Jaifroid Oct 16, 2022
56791b3
Attempt to prevent loop
Jaifroid Oct 16, 2022
f6f4a6a
Use same messaging as in local app
Jaifroid Oct 16, 2022
548ab1e
Simplify some messaging
Jaifroid Oct 16, 2022
ca331b3
Neater
Jaifroid Oct 16, 2022
e8ee442
Make it clear mode was tested
Jaifroid Oct 16, 2022
007a466
Let user cancel return to local code if they wish
Jaifroid Oct 16, 2022
6c02445
Make button clearer
Jaifroid Oct 16, 2022
0f15c60
Finished testing, return to production server
Jaifroid Oct 16, 2022
150cf55
Remove unusued code
Jaifroid Oct 16, 2022
be101f8
Finesse descriptions of modes
Jaifroid Oct 17, 2022
ab0cf6c
Normalize use of "ServiceWorker Mode"
Jaifroid Oct 17, 2022
fc5a459
Describe SW mode before JQuery in other documentation
Jaifroid Oct 17, 2022
f558b1f
Remove delay before displaying alert
Jaifroid Oct 22, 2022
619dfd2
Update app.js
Jaifroid Oct 22, 2022
651dafd
If user presses cancel or X or backdrop, display deprecation warning …
Jaifroid Oct 22, 2022
10f95b3
Handle display of deprecation after SW mode registration failure
Jaifroid Oct 23, 2022
6783426
Temporarily set test server
Jaifroid Oct 23, 2022
390efb1
Revert " Temporarily set test server"
Jaifroid Oct 23, 2022
d738825
Reinstate WIP label in manifest.json
Jaifroid Oct 23, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 38 additions & 37 deletions www/index.html
View file
Open in desktop
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