Book Viewer Component

Overview

Documentation of the "book viewer" component used on damienjay.com and littledamien.com.

PHP

• Base class: AlbumViewer
  • [COMMON_CLASS_DIR]filters\AlbumViewer.php
• Derived classes
  • In their __construct() method, they will call the parent's constructor, passing in a content type id, page content type id, and the path to the directory where the page images are located.

Markup

DOM elements required to operate the book viewer

+- {header}
|
+- .minimized-header (hidden)
|
+- .page-title
|
+- .album-container > data-id, data-type
|  |
|  +- .page-set
|  |  |
|  |  +- .alert-error
|  |  | 
|  |  +- .left-page > data-p, data-op
|  |  |  |
|  |  |  +- img
|  |  |
|  |  +- .right-page > data-p, data-op
|  |     |
|  |     +- img
|  |
|  +- .page-links-container
|  |  |
|  |  +- .prev-pg-btn > data-p, data-op
|  |
|  |  +- .page-number
|  |  |
|  |  +- .next-pg-btn > data-p, data-op
|  |  
|  +- .page-previews .scroll-pane .ui-widget .scroll-widget-header > data-id, data-type
|     |
|     +- .scroll-content
|     |  |
|     |  + .page-tn > data-p
|     |
|     +- .scroll-bar-wrap .ui-widget-content
|        |
|        +- .scroll-bar
|   
+- .book-previews
|  | 
|  +- .scroll-content
|  |
|  +- [...]
| 
+- .preload .preload-0
|
+- .preload .preload-1

Shared templates

• [COMMON_TEMPLATE_DIR]_templates/content/book-viewer/album-container.php
  • [COMMON_TEMPLATE_DIR]_templates/content/book-viewer/page-set.php
    • [COMMON_TEMPLATE_DIR]_templates/content/book-viewer/page-navigation.php
  • [COMMON_TEMPLATE_DIR]_templates/content/book-viewer/page-previews.php
• [COMMON_TEMPLATE_DIR]_templates/content/book-viewer/book-previews.php

CSS

It's necessary to define styles for the scrollbar elements, and for the width, height, and justification of the pages of the book.

On littledamien.com, refer to /sass/modules/content/_book_viewer.scss.

In the page initialization, set the right and left page widths and heights with JavaScript:

$('.page-set').css('width', (w*2)+'px').css('height', h+'px');
$('.page-set .left-page').css('width', w+'px').css('height', h+'px');
$('.page-set .right-page').css('width', w+'px').css('height', h+'px');

Also, if using jQuery Mobile, it's necessary to hide the loading element that the library inserts into the page:

.ui-loader { display: none; }

According to their documentation, you can hide the loader, but I had only partial success with it.

JavaScript

Page initialization

• $('.sketchbook-viewer').bookviewer('bindBookSetHandlers');
  Binds handlers for the page set, page previews, and book previews.
• $(document).bookviewer('bindKeyedNavigation');
  Configures navigation from page to page using right and left arrow keys, and right and left swipes on tablets.
• $('.header').bookviewer('toggleHeader', 4000);
  • With the 2nd argument value of 4000, replaces the "normal" header element with a minimized version after 4 seconds.
  • After the header is minimized, it can be restored by mousing over the minimized header.
  • After mousing out of the "normal" header it is again swapped with the minimized version.
  • The default minimized header element selector is .minimized-header and should be hidden initially.

jQuery libraries

• jQuery
• jQuery UI
• jQuery Mobile
  • UPDATE I removed jQuery Mobile library. It was causing too many problems.
  • Support for tablet swipe navigation.
  • CDN at //code.jquery.com/mobile/1.3.2/jquery.mobile.structure-1.3.2.min.css
  • IMPORTANT The jQuery Mobile library MUST be included on the page before the jQuery UI libraries. There is some sort of collision between the two and the scrollbars won't work otherwise.

jQuery Mobile issues

• Displays a loader widget which is very difficult to suppress.
• Links to new pages get loaded into a page element at the bottom of the page, instead of making a simple redirect.
• Clashes with jQuery UI slider widget.

"littled" libraries

• $.littled
• $.bookviewer