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

function TableOfContents () {
    this.getSections = function() {
        /*
        - return an array of section objects
        - in case there there is no table of content, return an empty array
        */
    }

    this.scrollToSection = function(index: number) {
        /*
        - scroll to a section with index in array returned by this.getSections
        - perform change to the page so that the section become available for reading, such as expanding the collapsed section  
        */
    }

    // OPTIONAL
    this.visibleSectionIndexes = function() {
        /*
        - return an array of visible section's indexes
        - in case there there is no table of content, return an empty array
        */
    }

    // OPTIONAL
    this.startVisibleSectionCallBack = function () {
        /*
        - start page visible section call back
        - 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
        - implementation to be discussed. It might not be a good idea to modify window.onscroll directly
        */
        var handleScroll = function() {
            var visible = tableOfContents.visibleSectionIndexes();
            if (visible.length > 0) {
                window.location = 'pagescroll:scrollEnded?start=' + visible[0] + '&length=' + visible.length;
            }
        }
        window.onscroll = handleScroll;
        handleScroll();
    }

    // OPTIONAL
    this.stopVisibleSectionCallBack = function () {
        /*
        - stop page visible section call back
        */
        window.onscroll = undefined;
    }
    
}

function Section(title: string, level: number) {}