Events Supported¶

Kitaboo SDK can also be used to customize the reader experience using the following events and callbacks

Book loading events¶

These callbacks can be added when a book starts or finishes loading :
/**
 * Book load complete. Parsing and Intilization Done
 * Book rendering ends
 * @event on("book:loaded") Book load complete. Parsing and Intilization Done
 * @memberof KitabooRenderer
 * @instance
 * @param {Object} book book inforamtion eg., meta-data, spine info, toc etc
 * @param {String} book.baseurl OPS path. book loading folder path
 * @param {Object} book.bookdata complete book object ie., manifest, metadata, nav, spine, toc 
 * @param {Object[]} [book.chapters] custom chapter object created using kitaboo toc.xml which hold pages and chapter information
 * @param {Object} book.displayNum_pageNum_map custom mapping created using kitaboo tox.xml for displayNum to pageNum
 * @param {Object} [book.kitabooFixedData] custom kitaboo toc.xml object
 * @param {Object} book.pageNum_displayNum_map custom mapping created using kitaboo tox.xml for pageNum to page object
 * @param {String} book.pckgpath current book path
 * @param {Object[]} [book.resources] custom resource object created using kitaboo toc.xml
 * @param {Object[]} [book.toc] custom toc object created using kitaboo toc.xml
 * @return {BookVO} book inforamtion eg., meta-data, spine info, toc etc
 * @example render.on("book:loaded", function(book) { });
 */
render.on("book:loaded", function(book) {
});

/**
 * Book loading failed.
 * Either parsing error for book path or corrupt content.
 * book path or related path ie., opf, ncx, toc not proper
 * @event on("book:error") Book loading and parsing failed.
 * @memberof KitabooRenderer
 * @instance
 * @example render.on("book:error", function(error) { });
 */
render.on("book:error", function(error) {
  alert(error);
});

/**
 * Event triggers for each current active page's get unloaded
 * @event on(page:unloaded) Each current active page's get unloaded
 * @memberof KitabooRenderer
 * @instance
 * @param {Object} event current un-loading page object
 * @param {Object} event.page current un-loading page object
 * @return {Object} current unloading page object
 * @example render.on(page:unloaded, function(event) { });
 */
render.on('page:unloaded', function(event) { //page:navigation-started
});

/**
 * Event triggers multiple times.
 * Notifiy user when page's comes in visible area.
 * In reflow notify's user till reaches last spread of loaded page
 * @event on("viewer:pagechange") Current page's change
 * @memberof KitabooRenderer
 * @instance
 * @param {Object} event
 * @param {Object} event.chapter Current loading page object
 * @param {Object} [event.location] current location in page. used in reflow book
 * @param {Object} [event.next] next page information. used in reflow book
 * @param {Object} [event.prev] previous page information. used in reflow book
 * @return {Object} current pages and xhtml points details
 * @example render.on("viewer:pagechange", function(event) { });
 */
render.on("viewer:pagechange", function(event) {
});

/**
 * Event triggers when current page's are visible on screen
 * @event on('viewer:pageloaded') Current page's are visible on screen
 * @memberof KitabooRenderer
 * @instance
 * @param {Object} event
 * @param {Object[]} event.pages Current loaded pages collection
 * @param {Object} [event.next] next page information. used in reflow book
 * @param {Object} [event.prev] previous page information. used in reflow book
 * @return {Object} currents pages collection
 * @example render.on('viewer:pageloaded', function(event) { });
 */
render.on('viewer:pageloaded', function(event) {
    isPageLoaded = true; // one time variable use
});

/**
 * Event triggers when book pages(iframe) gets loaded in DOM.
 * Notify's user for each loaded page(iframe) in background(Cached).
 * @event on("viewer:doc_loaded") Book pages(iframe) gets loaded in DOM
 * @memberof KitabooRenderer
 * @instance
 * @param {Object} event contains chapter and document information of current xhtml
 * @param {Object} event.chapter Current loading chapter object
 * @param {Object} event.data DOM Object. Current loading document.
 * @return {Object} current Document with page data
 * @example render.on("viewer:doc_loaded", function(event) { });
 */
render.on("viewer:doc_loaded", function(event) {
    console.log(event)
});

/**
 * Event triggers loaded page(iframe) layout change ie., fit-width, fid-height, zoom, scroll change etc., 
 * @event on(EVENTS.LAYOUT.UPDATED) Loaded page(iframe) page layout changed
 * @memberof KitabooRenderer
 * @instance
 * @param {Object} event layout update information
 * @param {String} event.flow page flow ie., paginated, scrolled, continous-scrolled
 * @param {String} event.type page is fit-to-width or fit-to-height
 * @param {Boolean} event.is2PageView single or double page view enable
 * @return {Object} event layout information
 * @example render.on(EVENTS.LAYOUT.UPDATED, function(event) { });
 */
render.on(EVENTS.LAYOUT.UPDATED, function(event){
  console.log(event, 'LAYOUT.UPDATE');
});

/**
 * event triggers when user clicks table. User can show the table in popup.
 * Only for Reflow Layout Books
 * @return {object} event: table clicked
 */
render.on(EVENTS.TABLE_CLICKED, function(event) {
    // show table in popup
    console.log(event, 'EVENTS.TABLE_CLICKED');
});

/**
 * event triggers when user clicks image. User can show the image in popup.
 * Only for Reflow Layout Books
 * @return {object} event: image clicked
 * @param {object} event.src: image clicked src
 * @param {object} event: clicked image DOM object
 */
render.on(EVENTS.IMAGE_CLICKED, function(event){
    // show image in popup
    console.log(event, 'EVENTS.IMAGE_CLICKED');
});

Use the navigation to load or jump to a particular page or chapter.

Next page: render.nextPage()
Previous page: render.previousPage()
Jump to a page or chapter: render.navigateToPage(page-number)

Where, page-number is equal to the integer value for the fixed paginate book or string for reflow chapter-name with anchor.

There are two methods which returns a boolean value whether the next or previous should be enabled it helps to stop the navigation and give better user experience.

render.isPreviousDisabled()// returns true if needs to be disabled
render.isNextDisabled())// returns true if needs to be disabled

Adding Style for sdk or Customizing font of book¶

If we want to load the Epub in any different font to enhance readability then we can add the style sheet rules in book loaded event.

@example:
if (book.bookdata.metadata.layout != "pre-paginated") {
render.addStylesheetRules({
                    '@font-face': {
                        'font-family': 'kitabooread',
                        'src': "url(" + <basePath>+ '/kitabooread.eot?60jjsx' + ");" +
                            "src: url(" + <basePath> + '/kitabooread.eot?60jjsx#iefix' + ") format('embedded-opentype'), url(" + <basePath>+ '/kitabooread.woff2?60jjsx' + ") format('woff2'), url(" + relPathToAbs + '/kitabooread.ttf?60jjsx' + ") format('truetype'), url(" + <basePath>+ 
'/kitabooread.woff?60jjsx' + ") format('woff'), url(" + <basePath>+ 
 '/kitabooread.svg?60jjsx#icomoon' + ") format('svg')",
                        'font-weight': 'normal',
                        'font-style': 'normal'
                    },
                    'img': {
                        'max-width': '100%',
                        'height': 'auto !important'
                    }
                });

} else{
// Style rules for reflowable Epub
}

Text Selection callback¶

Select text on the renderer using mouse scroll or long press (handholds) to invoke the callback.

highlight.on("highlight:section", function(textobject) {
        console.log(textobject);
  });
Where,
textobject :
{selection: <Selection>, range: <Range>, selectedText: "<selected text>"}
    selection: document current selection object
range: document current range object along with start and end offset
selectedText: document current selected text

Reader modes¶

Reader Modes are applicable only for Reflowable type of Epub's as we can change its background and forecolor to enhance its readability.

By default there are two modes- Day and Night, but we can add additional modes as well and it will render the book in that mode.

Day Mode
Night Mode
Sepia Mode

you can use any combination of background color and color value to apply on the book.

render.switchDayNightMode({ 'backgroundColor': 'rgb(19, 19, 19)', 'color': '#fff' });
render.switchDayNightMode();// default Day Mode with White background and Black color.

Font size¶

Font Size Slider is applicable only for Reflowable type of Epub's as we can increase or decrease the font size for readability.

Kitaboo Sdk exposes the method to Increase or Decrease Font Size as per the user requirement for better user experience.

You can add any button or slider as per your requirement and call the below mentioned method and pass the required font size to render the book.

    render.applyFonts({ 'fontSize': fontSize });
    For Example:
    $(".font-slider").slider({
        min: 4,
        max: 24,
        value: fontSize,
        slide: function (event, ui) {
            console.log(ui.value, 'slider');
            fontSize = ui.value;
            render.applyFonts({ 'fontSize': fontSize });
        }
    });

Scroll view¶

Scroll view toggle button is applicable only for Reflowable type of Epub's. We can enable and disable the scroll view navigation for reflowable Epub to read the entire chapter with scroll like pdf and disable the same to render the Epub like normal book with basic view and page navigation.

Kitaboo Sdk exposes the method to enable or disable the scroll view as per the user requirement for better user experience.

You can add any checkbox or toggle button as per your requirement and call the below mentioned method and it toggles automatically by checking its current view.

render.switchScrollMode(); 
For Example:  
function scrollMode(element) {
    if ($(element).is(':checked')) {
        $('#nextBttn').show();
        $('#prevBttn').show();

    } else {
        $('#nextBttn').hide();
        $('#prevBttn').hide();

    }
    highlight.setScrollMode($(element).is(':checked'));
    bookmarkobj.setScrollMode($(element).is(':checked'));
    player.setScrollmode($(element).is(':checked'));
    render.switchScrollMode(); // change the default scroll mode(defaultHorizontalPageScrolling) fro render

    if(book.bookdata.metadata.layout != "pre-paginated"){

        setTimeout(function(){ highlight.recalculatingstickyNote(render.getCurrentPages()[0].index); }, 300);
    }
}

Audio sync¶

Kitaboo SDK supports audio sync as well which actually works like text to speech for reflowable Epubs. In reader we can Initialize mediaoverlayplayer and sdk exposes few methods which we can use to customize the behaviour as per our requirement.

If book package has the Audio sync support, then we can enable the same in reader and can provide the button on which player can start reading the content.

Use the following code to add Audio sync to your Reader:

  player = new mediaoverlayplayer();
  player.setbook(book);
  player.addhighlightclass(highlightstyle);

  player.on('mediaoverlay:onpause', function (e) {
      console.log('on pause');
  });

  player.on('mediaoverlay:onplay', function (e) {
      console.log('on onplay');
  });

  player.on('mediaoverlay:onplaying', function (e) {
      console.log('on onplaying', e);
  });

  player.on('mediaoverlay:onended', function (e) {
      console.log('on onended', e);
  });

  player.on('mediaoverlay:onerror', function (e) {
      console.log('on onerror', e);
  });

  player.on('mediaoverlay:onloadstart', function (e) {

  });

  player.on('mediaoverlay:onnext', function () {
      render.nextPage();
  });

  player.on('mediaoverlay:pagescroll', function (ele) {
      //ele.scrollIntoViewIfNeeded();
      var iframe = document.getElementById('Epub_' + render.getCurrentPages()[0].index);
      render.jumpToPageOnElement(iframe, ele);
  });

  render.on("viewer:pagechange", function (event) {

    if (player != null) {
        player.setChapterIndex(event.chapter.index);
    }

    if (!player.scrollmode) {
        player.stop();
    }
  });

Text Alignment¶

Text Alignment is applicable only for Reflowable type of Epub's as we can align the text left, right, center, justify.

We will be able to call these methods on any buttons. It support all the four Right, Left, Justify, Center text alignments.

    render.alignText('left');
    For Example:
    1. render.alignText(''); // apply default book text alignment
    2. render.alignText('left');
    3. render.alignText('right');
    4. render.alignText('center');
    5. render.alignText('justify');

Line Spacing¶

Line Spacing(line-height) is applicable only for Reflowable type of Epub's. User can provide line spacing to content to improve readability.

We will be able to call method's on any buttons.

  render.applyLineSpacing(1);
  For Example:

  1. render.applyLineSpacing(1.6);
  2. render.applyLineSpacing(1.8);
  3. render.applyLineSpacing(''); // to reset to default

Side Margin¶

Margin is applicable only for Reflowable type of Epub's. User can provide margin to content to improve readability.