Javascript API

Overview

Zim files can be seem as subset and snapshot of a website. Webpages in the zim file could have totally different structure and layout.

The problem arises when interaction with the webpage is needed, since it is impossible to perform those interactions when there's little information regarding if and how an interaction should be performed.

Some kind of indication should be provided to allow zim readers to turn interactions on or off once a page is loaded. Further, implementations to perform those interactions needs to be included in the zim file itself.

Motivation

A basic function of zim readers is to provide a table of content of an article. But it is impossible come up with one javascript function to extract table of content in all sorts of zim files. It would make sense for each webpage to come with its own `getTableOfContent()` and `scrollToSection()` function. Some webpages, such as phet or main page, it might make little sense to provide table of content. A way to check `hasTableOfContent` could also be provided.

Proposed Solution

Add javascript with indication and implementation of capabilities to each offliner and load the javascript when page loads. A standard interface should be defined and documented.

Potential capabilities to include:

• title

• table of content
  • extraction
  • scrolling position indicating
  • scroll to section
• font
  • size
  • line spacing
  • justification
• night mode
• readability
• snippet
• page thumb image
• in page search

Capabilities

Table of content

 1 function TableOfContents () {
 2 
 3     this.getSections = function() {
 4 
 5         /*
 6 
 7         - return an array of section objects
 8 
 9         - in case there there is no table of content, return an empty array
10 
11         */
12 
13     }
14 
15 
16 
17     this.scrollToSection = function(index: number) {
18 
19         /*
20 
21         - scroll to a section with index in array returned by this.getSections
22 
23         - perform change to the page so that the section become available for reading, such as expanding the collapsed section  
24 
25         */
26 
27     }
28 
29 
30 
31     // OPTIONAL
32 
33     this.visibleSectionIndexes = function() {
34 
35         /*
36 
37         - return an array of visible section's indexes
38 
39         - in case there there is no table of content, return an empty array
40 
41         */
42 
43     }
44 
45 
46 
47     // OPTIONAL
48 
49     this.startVisibleSectionCallBack = function () {
50 
51         /*
52 
53         - start page visible section call back
54 
55         - using this call back, the reader app could know which section is currently visible to the user and highlighting the location in table of content
56 
57         - implementation to be discussed. It might not be a good idea to modify window.onscroll directly
58 
59         */
60 
61         var handleScroll = function() {
62 
63             var visible = tableOfContents.visibleSectionIndexes();
64 
65             if (visible.length > 0) {
66 
67                 window.location = 'pagescroll:scrollEnded?start=' + visible[0] + '&length=' + visible.length;
68 
69             }
70 
71         }
72 
73         window.onscroll = handleScroll;
74 
75         handleScroll();
76 
77     }
78 
79 
80 
81     // OPTIONAL
82 
83     this.stopVisibleSectionCallBack = function () {
84 
85         /*
86 
87         - stop page visible section call back
88 
89         */
90 
91         window.onscroll = undefined;
92 
93     }
94 
95 }
96 
97 
98 
99 function Section(title: string, level: number) {}