kiwix/kiwix-js
1
0
Fork 0
mirror of https://github.com/kiwix/kiwix-js.git synced 2025-09-24 04:54:51 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #210 from kiwix/fix-README-for-browser-extensions

Browse Source 
Update README and About section to reflect the new target of this app.
This commit is contained in:
Mossroy 2017-04-07 20:21:04 +02:00 committed by GitHub
commit da2435831b
2 changed files with 23 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
README.md
View File

@ -3,34 +3,21 @@ kiwix-html5
Kiwix is an offline wikipedia viewer. See the official site: http://www.kiwix.org/
This application is developed in HTML5/Javascript, with Firefox OS as the primary target.
This is a browser extension developed in HTML5/Javascript.
You can search among the article titles, and read any of them without any Internet access.
All the content of wikipedia is inside your device (including the images). It also works with any content in the OpenZIM format: http://www.openzim.org/wiki/OpenZIM
All the content of wikipedia is inside your device (including the images).
It might also works with other content in the OpenZIM format: http://www.openzim.org/wiki/OpenZIM , but has been only tested on the wikipedia ones.
If your Internet access is expensive/rare/slow/unreliable/watched/censored, you still can browse this amazing amount of knowledge and culture.
A "search nearby" feature can also list articles found around your location (after geolocating your device, only for deprecated Evopedia archive format, for now)
It uses ZIM files that you can download from http://download.kiwix.org/
You have to store them in a sub-directory of your SD-card (or internal storage).
You have to download them separately, store them in your filesystem, and manually select them after starting the application.
It is unfortunately not technically possible to "remember" the selected ZIM file and open it automatically (the browsers refuse that for security reasons).
This application is released under the GPL v3 license. See http://www.gnu.org/licenses/ or the included LICENSE-GPLv3.txt file
The source code can be found at https://github.com/kiwix/kiwix-html5
Unit tests can be run by opening tests.html file on Firefox.
The first versions of this application were originally part of the Evopedia project: http://www.evopedia.info which is already available on the Marketplace: https://marketplace.firefox.com/app/evopedia/.
But the Evopedia project and archive format are now discontinued: the dev team has joined the Kiwix project, in particular to adapt the app to be able to read ZIM archives.
This application is currently in beta state, and not on the Mozilla Marketplace yet.
You can install it on a Firefox OS device through the WebIDE of Firefox :
- clone the source code from github
- run WebIDE (tools menu of Firefox)
- choose to open a packaged app, and select your local source code folder
- plug your Firefox OS device (adb needs to be configured on your computer, and adb option must be enabled in the developer settings of the device)
- click on your device name in WebIDE, and allow the connection on the device
- click on the "Play" button in WebIDE
You also can run it on a desktop browser of a computer (tested with Firefox and Chromium) :
- for jQuery mode, you can simply open the index.html file in the source code, but the browser will not allow to run a ServiceWorker this way
- for ServiceWorker mode, the source code needs to be served through a web server (even on localhost). On Firefox, you also need to use the developer edition of Firefox (>=v48.0a2) for now.
In both modes, you will have to manually select the ZIM file each time.
The first versions of this application were originally part of the Evopedia project: http://www.evopedia.info (now discontinued)
These first versions were targeting Firefox OS (now discontinued too : we're not lucky ;-) ).

39
www/index.html
View File

@ -14,7 +14,7 @@
Mossroy - mossroy@mossroy.fr
Peter-x - https://github.com/peter-x
Copyright 2013-2016 Mossroy, Peter-x and contributors
Copyright 2013-2017 Mossroy, Peter-x and contributors
License GPL v3:
This file is part of Kiwix.
@ -98,7 +98,7 @@
<br />Official site : <a href="http://www.kiwix.org/" target="_blank">http://www.kiwix.org/</a>
<br />
<br />You can search among the article titles, and read any of them without any Internet access.
<br />All the content of wikipedia is inside your device (including the images). It also works with any content in <a href="http://www.openzim.org//wiki/OpenZIM">OpenZIM format</a>.
<br />All the content of wikipedia is inside your device (including the images). It might also work with any content in <a href="http://www.openzim.org//wiki/OpenZIM">OpenZIM format</a>, but has been only tested on the wikipedia ones.
<br />If your Internet access is expensive/rare/slow/unreliable/watched/censored, you still can browse this amazing amount of knowledge and culture.
<br />
<h3>Usage</h3>
@ -109,17 +109,18 @@
<br />If your archive size is more than 2 GB, it might not be supported by your device if it's using a FAT filesystem. In this case, it can be splitted into several 2GB files : see <a href="http://www.kiwix.org/wiki/FAQ">the Kiwix FAQ</a>
<br />
<br />NB : version 1.x of this application was designed for <a href="http://dumpathome.evopedia.info/dumps/finished/">Evopedia archives</a> and it's still compatible with it, but this format and <a href="http://www.evopedia.info">project</a> are now discontinued.
<h4>Step 2 : put it on your SD-card (or internal storage)</h4>
The archive can be stored in any subdirectory of your SD-card or internal storage (ex: /zim). If you have enough space, you can put several archives
<h4>Step 3 : enjoy wikipedia offline!</h4>
<h4>Step 2 : put it on device storage</h4>
If you have enough space, you can put several archives
<h4>Step 3 : open the extension, go to the "Configure" menu and select your ZIM file</h4>
<h4>Step 4 : enjoy wikipedia offline!</h4>
<h3>Privacy policy</h3>
<h4>Short answer :</h4>
This application works offline. We do not collect any of your personal data and don't even know what you are doing with this application.
<br /><h4>Longer answer :</h4>
Anyway, if you think your Internet access can be watched and/or if you are paranoid, you should shut down your 3G and Wifi access before using the application. Depending on your device, the "nearby articles" feature might also communicate with some Internet servers (usually Google) to geolocate your device (through your IP address and/or the Wifi networks detected around you)
<br />This application only reads the ZIM files of your SD-card (or internal storage) : it does not read any other files.
<br />This application only reads the archive files of your device : it does not read any other files.
<h3>Feedback / helping / contributing</h3>
This application is still in beta state. There are bugs and improvements that need to be done. In particular :
This application is still a work in progress. There are many bugs and improvements that need to be done. In particular :
<ul>
<li><a href="https://github.com/kiwix/kiwix-html5/issues/114" target="_blank">Issue #114</a> : Add a way to easily download ZIM files directly from the device</li>
<li><a href="https://github.com/kiwix/kiwix-html5/issues/13" target="_blank">Issue #13</a> : All the user interface is in English : I plan to translate it at least in French. If you feel able to translate it in your language, please contact me</li>
@ -147,12 +148,11 @@
We have to distribute some thanks to :
<ul>
<li>Kelson and all the Kiwix community for welcoming peter-x and me in this project</li>
<li>Mozilla for building Firefox OS. It's an amazing platform. Many thanks in general for your commitment to keeping the web open, alive and respectful. For those who didn't, please read their <a href="https://www.mozilla.org/en-US/about/manifesto/" target="_blank">Manifesto</a> to see what are the goals of this non-profit organization</li>
<li>Wikipedia teams and contributors to help spreading knowledge to everybody</li>
<li>All the developers of libraries and tools I used for releasing them as Free software (see License paragraph)</li>
</ul>
<h3>License information</h3>
Copyright 2013-2016 Mossroy, Peter-x and contributors
Copyright 2013-2017 Mossroy, Peter-x and contributors
<br />This application is licensed under the GPL v3 license :
<br />
<i>
@ -187,22 +187,13 @@
</ul>
<h3>Other platforms/versions</h3>
Other Kiwix clients exist on various platforms. See the official site : <a href="http://www.kiwix.org/" target="_blank">http://www.kiwix.org/</a>
<br />
<br />This HTML5/javascript application is currently mainly targeted on Firefox OS devices. But it also can be used on some other platforms :
<ul>
<li>It works perfectly on the <a href="https://developer.mozilla.org/docs/Mozilla/Firefox_OS/Using_the_App_Manager" target="_blank">Firefos OS simulator</a> (a Firefox plugin, used through the "WebIDE" of Firefox), you have to put the ZIM files in any subdirectory in a "fake-sdcard" folder of your firefox profile (ex : ~/.mozilla/firefox/xxxx.default/extensions/fxos_2_x_simulator@mozilla.org/profile/fake-sdcard/zim/)</li>
<li>On desktops, it can work (by pointing to the index.html file) but is less user friendly : you have to manually select the ZIM file(s), and it's not yet easily deployable as a "web application". I tested it on recent Firefox and Chromium, but it probably works on some other browsers. You can test on <a href="http://kiwix.github.io/kiwix-html5/" target="_blank">this online page</a> or from a local copy of the <a href="https://github.com/kiwix/kiwix-html5" target="_blank">source code</a></li>
<li>It also works on Android (since Firefox 34). You need to install Firefox first, then install Kiwix from the MarketPlace of Firefox. For now, there is a <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1117136">major bug</a> that prevents a ZIM file to be found in an external SD card : it has to be put in the internal storage of the device (if you have enough space in it)</li>
<li>An Apache Cordova port has been started (but is not ready yet, help welcome) : it should make this HTML5/javascript version available on many mobile platforms</li>
</ul>
</div>
<div id="configuration" style="display: none;" class="category-padding">
<h2>Configuration</h2>
This application needs an archive of wikipedia to work. If you did not download one yet, please see the About section
This application needs a ZIM archive to work. If you did not download one yet, please see the About section
<div id="openLocalFiles" style="display: none;">
Please select the .zim file<br />
Please select the .zim file (or all the .zimaa, .zimab etc in case of a split ZIM file)<br />
<input type="file" id="archiveFiles" multiple class="btn" /><br />
NB : for an Evopedia archive, please select all the files inside the archive (wikipedia_*.dat, metadata.txt etc)<br />
</div>
@ -213,11 +204,14 @@
<br /> Please select the archive you want to use : <select id="archiveList" class="form-control"></select>
<br /> Click <a id="btnRescanDeviceStorage">here</a> to rescan your SD Cards and internal memory
</div>
<br />
<h2>Expert settings</h2>
<div id="contentInjectionModeDiv">
Do not touch unless you know what you're doing. <br />
Content injection mode : <br/>
<input type="radio" name="contentInjectionMode" value="jquery" id="jQueryModeRadio" checked><label for="jQueryModeRadio">JQuery</label> (slow and memory hungry, but safer)
<br>
<input type="radio" name="contentInjectionMode" value="serviceworker" id="serviceworkerModeRadio"><label for="serviceworkerModeRadio">ServiceWorker</label> (faster but unstable, and not supported by all platforms)
<input type="radio" name="contentInjectionMode" value="serviceworker" id="serviceworkerModeRadio"><label for="serviceworkerModeRadio">ServiceWorker</label> (faster but unstable, and not supported by all platforms. In particular, Firefox extensions do not allow ServiceWorkers for now)
</div>
<div id="serviceWorkerStatus"></div>
<div id="messageChannelStatus"></div>
@ -225,9 +219,8 @@
</div>
<div id="welcomeText" class="container category-padding">
You can search the content of your Wikipedia archive by typing in the above search field.
You can search the content of your ZIM archive by typing in the above search field.
<br />It will propose articles starting with what you typed
<br />Or you can search for articles located around you (geolocation needed on your device)
</div>
<!-- List of articles matching the typed prefix -->