Design notes

Some things to take into consideration when designing / styling your book.

• If the element passed to wowBook is not positioned, wowBook will make it position to 'relative'.
• Every element that contains a page's content will be put inside another element, a page container.
• An element that contains a page's content cannot have margins.
• An element that contains a page's content will have the css "box-sizing" set to "border-box". Javascript is used to set the element's dimensions if the browser does not support it.
• An element that contains a page's content will have a class "wowbook-page-content". His parent will have a class "wowbook-page".
• If you need to change a style to all pages (like padding or background), change the class "wowbook-page-content".
• Every element that contains a page's content will have the css "overflow" set to "hidden".

Flash and Video

To create the flip effect the plugin use css transformations. Unfortunately, browsers doesn't like when you mix css transformations with flash and video. In order to avoid any problems, put a CSS class 'wowbook-basic-page' in every page that have a flash object or a video tag. This will force the plugin to use only the basic(a.k.a boring) page flipping effect.

Gutter shadow

The gutter shadow is a div placed over the book page's content.

This can be a problem if the div is over a element that the user may interact using the mouse (like selecting a text of the page, a link or a input field). In those cases, you can:

Remove the gutter shadow

set gutterShadow configuration option to false

Put the page content above the gutter

Put the page content inside a positioned div with z-index above the gutter shadow div (a number like 10 will do the trick)

Make the gutter shadow smaller

You can use CSS to change the width of the gutter shadow

For instance, to change the width to 20 pixels, put the snippet below in you css file or inside a style tag:

				.wowbook-gutter-shadow {
					width: 20px;
				}
			

Using the wowbook API

You can use the api to have greater control over the book capabilites at runtime.

To use the api, you need to use the "$.wowBook" function to get the wowBook object related to the book you created.

				// create the book
				$("#some_element").wowBook({
					width: 500, height: 500
				});

				// get the book object reference
				var book = $.wowBook("#some_element");

				// now you can call methods and properties
				book.startSlideShow();
				book.stopSlideShow();
				alert("This book has "+book.pages.length+" pages.");
			

Alternatively, you can use a jqueryUI style. To call methods:

				// create the book
				$("#some_element").wowBook({
					width: 500, height: 500
				});
				// get the book object reference
				$("#some_element").wowBook("zoom", 1);
			

To set and get book properties:

				// get the book object reference
				$("#some_element").wowBook("prop", "pageHeight"); // return 500
				$("#some_element").wowBook("prop", "shadows", false); // disable shadows
				$("#some_element").wowBook("options", "shadows", false); // 'options' works too
			

Glossary

page index

All the pages in the book have a associate page index. The cover has index 0, the second page has index 1, and so on.

spread

two adjacent, facing pages in a newspaper, magazine, or book. In wowBook, pages on the same spread are pages that are exhibited together. The book's covers are exhibited alone, but the other pages are always viewed in pairs. Pages in the same spread are pages 1 and 2, 3 and 4, 5 and 6, and so on. The front cover (page 0) and back cover (if exist) has no other page in the spread.

Pages

All the pages in the book have a associate page index. The cover has index 0, the second page has index 1, and so on. Some configuration options and methods accepts a negative page index. A negative page index is assumed to be relative to the end of the book — that is, an index of -1 indicates the last page, -2 is the second to last page, and so on.

onShowPage

null

function

A callback function that will be called every time a page is showed. the function will be called with parameters :

• book : is a book object, not the jquery element. To access the jquery element use 'book.elem'.
• page : page container (obtained from book.pages[index]), is the jquery object created around each page of the book.
• pageIndex : the index of the page being showed.

Important : when 2 pages are showed (the normal case), the onShowPage function will be called twice.

currentPage

integer

read only property. This property gives the page index of the current page (the visible page).Use the showPage method to change it.

pages

array

read only property. Array of page containers of the book. Each page container is a jquery Object.

insertPages

pages : a array or a JQuery object of "page content". Each "page content" can be a jquery object or a string of HTML.

dontShowPage : boolean, default to false. If false, book.showPage(currentPage) is called after inserting the pages.

inserts new pages at the end of the book.

insertPage

content : the page content, can be a jquery object or a string of HTML.

isBatchInsert : boolean, set it to true to avoid calling updateBook after the page insert.

inserts one new page at the end of the book. When inserting multiple pages, (for example, calling insertPage several times in sequence), pass isBatchInsert as true and call updateBook after you're done inserting.

removePages

from : the index of the first page to be removed.

to : the index of the last page to be removed.

Removes pages from the book. The parameters 'from' or 'to' can be a negative value, e.g. use book.remove(-1) to remove the last page. Some examples:

						book.remove();      // remove all pages from the book
						book.remove(1);     // remove the second page from the book
						book.remove(-2);    // remove the second-to-last page from the book
						book.remove(1,3);   // remove the second, third and fourth pages from the book
						book.remove(-3,-1); // remove the last, penultimate and antepenultimate pages of the book
					

updateBook

dontShowPage : boolean, default to false. If false, book.showPage(currentPage) is called after updating the book.

updates the book after insert or remove pages. Updates stuff like page numbering, sections, etc.

findPagesType

determine which pages are "softpages" and "hardpages" according to the configuration options "hardPages", "hardcovers" and pages marked with CSS class "wowbook-hardpage".

showPage

pageIndex : the index of the page to be showed.

updateLocationHash : boolean. If not false, updates the URL hash to reflect the page being shown.

Shows the page pageIndex.

By default, this method updates the URL hash to reflect the page being shown. See page_urls for more information.

Pass the parameter updateLocationHash as false(it has to be false, not a falsy value) to prevent this.

This method is not responsible for any flipping animation.

onShowPage

null

function

A callback function that will be called every time a page is showed. the function will be called with parameters :

• book : is a book object, not the jquery element. To access the jquery element use 'book.elem'.
• page : page container (obtained from book.pages[index]), is the jquery object created around each page of the book.
• pageIndex : the index of the page being showed.

Important : when 2 pages are showed (the normal case), the onShowPage function will be called twice.

advance

advances a page in the book and returns the new current page. Keep in mind that it advances 2 pages each time, ie, if currentPage is 2, after calling the 'advance' method the property currentPage will be 4.

back

back a page in the book and returns the new current page. Keep in mind that it goes back 2 pages each time, ie, if currentPage is 2, after calling the 'back' method the property currentPage will be 0.

leftPage

pageIndex : a page index, default is currentPage.

given a page index, returns the page that is on the left side of the spread at which that page index belongs. Some examples:

						book.showPage(2);
						book.leftPage(0); // returns null
						book.leftPage(); // returns 1 because currentPage==1
						book.leftPage(1); // returns 1
						book.leftPage(2); // also returns 1
						book.leftPage(3); // returns 3
						book.leftPage(4); // returns 3
					

rightPage

pageIndex : a page index, default is currentPage.

given a page index, returns the page that is on the right side of the spread at which that page index belongs. Some examples:

						book.showPage(2);
						book.rightPage(0); // returns 0
						book.rightPage(); // returns 2 because currentPage==1
						book.rightPage(1); // returns 2
						book.rightPage(2); // also returns 2
						book.rightPage(3); // returns 4
						book.rightPage(4); // returns 4
					

If there's no page on the right side of the page pageIndex, returns null.

pageIsOnTheLeft

pageIndex : a page index, default is currentPage.

returns true if the page pageIndex is on the left side of the book, false otherwise.

pageIsOnTheRight

pageIndex : a page index, default to currentPage.

returns true if the page pageIndex is on the right side of the book, false otherwise.

otherPage

pageIndex : a page index.

given a page index, returns the page index of the other page in same spread.

isOnPage

pageIndex : a page index

returns true if the book is at page "pageIndex" (if the page "pageIndex" is visible right now). For instance, when the user is viewing pages 1 and 2 of the book, isOnPage(1) and isOnPage(2) returns true, but will return false for any other page index.

backPage

pageIndex : a page index.

returns the page object(NOT the page index) that is on the back of the page pageIndex.

Automatic page numbering

Although you can put the page numbers on each book's page manually, it is easier to use the automatic page numbering feature.

pageNumbers

true

boolean

If set to true, the automatic page numbering is enabled.

firstPageNumber

1

integer

the number of the first numbered page.

numberedPages

[2,-3] or [2, -2]

string or array

Can be a string "all", in which case all the book pages will be numbered, or can be an array containing 2 elements. The first element is the page index of the first numbered page and the second element is the page index of the last numbered page. You can pass negative page indices.

By default, wowbook will number all pages except the covers (both internal and external).

doPageNumbering

Numbers the pages of the book, according to the config options pageNumbers, firstPageNumber and numberedPages.

Zoom

wowBook has a built-in zoom feature. To let your user use it, you can use the mouseWheel option or use the api to create buttons for zooming in and out.

				// create the book
				$("#mybook").wowBook({ width: 600, height: 500 });
				// get the book object
				var book=$.wowBook("#mybook");
				// make the element "zoomin" into a zoom button
				$("#zoomin").click(function(){ book.zoomIn() });
				// make the element "zoomout"into a zoom out button
				$("#zoomout").click(function(){ book.zoomOut() });
				// make the element "nozoom"  a remove zoom button
				$("#nozoom").click(function(){ book.zoom(1) });
			

zoomLevel

1

number

the initial zoom level. The default value 1 means no zoom.

zoomMax

2

number

the maximum value that the zoom level can be set.

zoomMin

1

number

the minimum value that the zoom level can be set.

zoomStep

0.05

number

the amount that the zoom level will change when the user zoom in or zoom out the book.

zoomBoundingBox

window

DOM, jquery selector or a jquery object

When the User's zoom in book, the book will be expanded until it occupies the entire browser window. To better adapt to your design, you can specify a bounding box to limit the area of the browser that the book occupies during zooming. The book will continue to be zoomed, but the visible part of it is limited by the boundingBox. The boundingBox element don't need be an element containing the book. During zooming, the book will be displaced and will occupy the same area of the element.

onZoom

null

function

Callback that is called after the zoom level changes. the function will be called with parameters :

• book : is a book object, not the jquery element. To access the jquery element use 'book.elem'.

zoomLevel

number

The current zoom level, or 'how many times the book is zoomed'.

1 means no zoom, 2 means the book is magnified 2 times its normal size.

This is a read-only property, to change the zoomLevel you must use the methods zoom, zoomIn and zoomOut.

minimum value is zoomMin, maximum value is zoomMax.

zoomWindow

jquery Object

ZoomWindow is the element that contains the book when it's zoomed. His position and dimensions are the same of the zoomBoundingBox. When the zoomed book gets bigger than the zoomWindow, only the part of the book that is inside the zoomWindow's area is visible to the user.

onZoom

Callback that is called after the zoom level changes. the function will be called with parameters :

• book : is a book object, not the jquery element. To access the jquery element use 'book.elem'.

zoomMax

2

number

the maximum value that the zoom level can be set.

zoomMin

1

number

the minimum value that the zoom level can be set.

zoomStep

0.05

number

the amount that the zoom level will change when the user zoom in or zoom out the book.

zoom

level

sets the zoom level to param level.

zoomIn

step

increase the zoom level in step units. if step is not provided, the zoomStep config option is used instead.

zoomOut

step

decrease the zoom level in step units. if step is not provided, the zoomStep config option is used instead.

Slide show

slideShow

false

boolean

if true, starts the slide show automatically after the book is created.

slideShowDelay

1000

integer

time between page changes, in milliseconds.

pauseOnHover

true

boolean

if true, pauses the slide show when hover over the book.

slideShowDelay

1000

integer

time between page changes, in milliseconds.

pauseOnHover

true

boolean

if true, pauses the slide show when hover over the book.

slideShowRunning

false

boolean

when true, indicates that the slideshow is running.

startSlideShow

starts the slide show. The property slideShowDelay is the time between page changes.

stopSlideShow

stops the slide show.

toggleSlideShow

If the slideshow is running, then it is stopped. If the slideshow is not running, then it is started.

Page flip sound

wowBook uses the HTML5 audio element to play a "flipping page" sound when the user flips a page. If the user browser does not support it, nothing happens.

Changing the sound file

If you want to change the sound file it's recommended that you provide 2 versions of the file, one in mp3 format and the other in Ogg Vorbis format. Then pass those files names in the config option "flipSoundFile".

Put those files on you server and use the flipSoundFile configuration option, like this:

				$('#mybook').wowBook({
				  // ... other configuration options
				  ,flipSound     : true
				   // array with the files
				  ,flipSoundFile : ["my_sound_file.mp3", "my_sound_file.ogg" ]
				  // where are these files. This value will be prepended in each file name.
				  // Don't forget the ending "/"
				  ,flipSoundPath : "www.mysite.com/sounds/"

				  // ... other configuration options
				});
			

the browser will search for the appropriate audio file format that he supports.

Using another audio player

To use another audio player, you can use the onPlayFlipSound callback to tell the player when to play the sound, like this:

				$('#mybook').wowBook({
				  // ... other configuration options
				  , onPlayFlipSound: function(book){
				    // ...
				    // code that makes your player play the flip sound
				    // ...
				    return false; // if this callback returns false, wowBook will not play the flip sound
				  }
				});
			

flipSound

true

boolean

if true, plays a 'page flipping' sound when user flip the page.

flipSoundFile

['page-flip.mp3', 'page-flip.ogg']

array of strings

Array containing the sound files.

flipSoundPath

"./wow_book/sound/"

string

The path to the folder that contains the sound files.

onPlayFlipSound

null

function

Callback called BEFORE play the flip sound. Receives the a wowBook object as parameter. If returns false the flip sound will not be played.

flipSound

true

boolean

if true, plays a 'page flipping' sound when user flip the page.

audio

the audio DOM element created to play the flipping sound.

toggleFlipSound

enabled : a boolean

If no argument is given, toggles the "flipSound" property. Otherwise set the "flipSound" property to the "enabled" argument. If "flipSound" is false, adds the class "wowbook-disabled" to the control "flipSound" if it exists.

playFlipSound

method that plays the 'page flipping' sound.

Miscellaneous

controls

a empty object

a Object

This options allows you easily to turn any element in a book's control. Configure your book like this

						$("#mybook").wowBook({
						  controls : {
						    next : '#next',
						  }
						});
					

And when the element "#next" is clicked will advance a page in the book.

All the controls available are listed in the example below.

						$("#mybook").wowBook({
						  controls : {
						    next      : '#next',     // goto next page
						    back      : '#back',     // back page
						    first     : '#first',    // goto first page
						    last      : '#last',     // goto last page
						    zoomIn    : '#zoomIn',   // zoom in
						    zoomOut   : '#zoomOut',  // zoom out
						    slideShow : '#slideShow' // starts/stop slideshow
						    flipSound : '#flipsound' // enable/disable page flip sound
						  }
						});
					

The control "back" will have the CSS class "wowbook-disabled" when the book is on the first page.
The same applies to the control "next" when the book is on the last page and to the control "slideshow" when slideshow is running.

keyboardNavigation

{ back: 37, advance: 39 }

object or false

use the keyboard to turn pages, set this false to disable it. Default is to use left and right arrow keys. You can customize the keys used by passing a object with the key codes that you want to use, for instance

						// set keys 'a' and 'b' to turn the pages of the book
						$("#mybook").wowBook({
						  keyboardNavigation : { back : 65, advance : 66 }
						});
					

height

300

integer

height of the book, in pixels.

width

500

integer

width of the book, in pixels. The page width will be half of this value.

startPage

0

integer

page index of the page that will be opened after start.

centeredWhenClosed

false

boolean

if true, the book will be centered when closed (showing the first or the last cover).

gutterShadow

true

boolean

When set to true, a shadow will be placed in the middle of the book (the gutter).

bookShadow

true

boolean

When set to true, a shadow will be positioned behind the book.

transparentPages

false

boolean

set it to true if you want to use pages that have a transparent background. wowBook normally hides the not visibles pages for performance reasons.

handleWidth

50

integer

Width of the handle where the user can grab the page edge and start dragging the page. The default value is set on the CSS file, but you can use this option to override it.

handleClickDuration

100

number (in milliseconds)

If user click on a handle and the click has the duration shorter that the value of handleClickDuration, turns a page. Set to 0 to disable this behavior.

curl

true

boolean

Curl the page corner when the user hover the page borders. Set to false disable this behavior.

curlSize

40

integer

How 'much' the page corner will be curled when the option curl is true.

shadows

true

boolean

if set to true, shadows caused by the page fold are visible when the page is folded. You may want disable this for performance reasons.

shadowThreshold

20

number in the rage of 0 and 50

the shadow appears gradually during the page flip. This options sets the threshold where the shadow starts to appear. Normally you don't need to change this, but you can play with this value to see what best fits your taste.

foldGradient

true

boolean

a gradient is put over the page when the page is folded, to give it realistic highlights and shadows. You may want disable this for performance reasons.

foldGradientThreshold

20

number in the range of 0 to 50

the page fold gradient appears gradually during the page flip. This options sets the threshold where the gradient starts to appear. Normally you don't need to change this, but you can play with this value to see what best fits your taste.

mouseWheel

false

boolean or string

can have the following values:

• false : mouse wheel does nothing
• "zoom" : enable zooming using the mouse wheel.
• any other truthy value : enable changing pages using the mouse wheel.

mouseWheel

false

boolean or string

can have the following values:

• false : mouse wheel does nothing
• "zoom" : enable zooming using the mouse wheel.
• any other truthy value : enable changing pages using the mouse wheel.

centeredWhenClosed

false

boolean

if true, the book will be centered when closed (showing the first or the last cover).

corners

object

read-only property, used to translate strings like "tl" into coordinates(x,y) of a page.

startPage

0

integer

page index of the page that will be opened after start.

opts

object

the object with the configuration options passed to the book.

elem

JQuery object

the JQuery object containing the DOM element passed to the plugin

id

string

the id attribute of the elem.

pageHeight

integer

height of the book, in pixels.

pageWidth

integer

width of the page of the book, in pixels

shadows

true

boolean

if set to true, shadows caused by the page fold are visible when the page is folded. You may want disable this for performance reasons.

shadowThreshold

20

number

the shadow appears gradually during the page flip. This options sets the threshold where the shadow starts to appear. Normally you don't need to change this, but you can play with this value to see what best fits your taste.

foldGradient

true

boolean

a gradient is put over the page when the page is folded, to give it realistic highlights and shadows. You may want disable this for performance reasons.

foldGradientThreshold

20

number

the page fold gradient appears gradually during the page flip. This options sets the threshold where the gradient starts to appear. Normally you don't need to change this, but you can play with this value to see what best fits your taste.

bookShadow

jquery Object

the JQuery object that contains the book shadow.

hardPageShadow

jquery Object

the JQuery object that contains the page's shadow.

leftHandle

jquery Object

the JQuery object that contains the handle that allows drag the page's edge on the left side of the book.

rightHandle

jquery Object

the JQuery object that contains the handle that allows drag the page's edge on the right side of the book.

transparentPages

false

boolean

set it to true if you want to use pages that have a transparent background. wowBook normally hides the not visibles pages for performance reasons.

selectorToPage

selector : a jQuery selector

utility function, returns the index of the page that contains the jquery selector.

positionBookShadow

This method puts the book shadow on the right position.

calculateOpacity

calculateOpacity : function(value, max, ThresholdMin, ThresholdMax) {

pageEdgeDragStart

e : jquery mouse event

method called when the user starts to drag a page edge.

pageEdgeDrag

e : jquery mouse event

method called while the user is dragging an edge of the page.

pageEdgeDragStop

e : jquery mouse event

method called when the user stops to drag a page edge.