Documentation
what to do to make the book work...
First things first
What happens when the book loads.
The download package includes several files and folders, the book swf file is: "panoFlipBook.swf"
The book in the package uses an xml file: "panoFlipBook/bookxml/panoFlipBook.xml".
However it is possible to change any folder name, any file path.
When the book is loaded it searches for loderInfo parameters: id and xmlFile, they can be passed to the book using swfobject or directly using ? mark like this: panoFlipBook.swf?xmlFlie=my_xml_file.xml. These parameters are passed to the book and written as variables (no actions taken yet). The book has default parameters. The default id is "PanoFlipBook", the default path to the xml is "panoFlipBook/bookxml/book.xml". Once the book is added to the stage it will look for the loaderInfo url and strip it to get book's swf file name, if it can (it is not possible to get the right url in some application for example krpano) the default parameters are then replaced with the new parameters that are connected to the file name of the book. For example you rename the book file panoFlipBook.swf to mybook.swf. The book replaces id with the name: "mybook" and the default xml path to: "panoFlipBook/bookxml/mybook.xml". Then the book checks if there are id and xmlFlie parameters in loaderInfo parameters and replaces the id and xmlFile with these parameters.
Here is what happens:
You rename the book file name to mybook.swf.
You load the book this way: mybook.swf?id=lovelybook&xmlFlie;=project/lovelybook.xml or this way: so.addVariable("xmlFile","project/lovelybook.xml");
The book loads and writes these parameters as variables.
The book has following parameters as default: id = PanoFlipBook, xmlFlie = panoFlipBook/bookxml/book.xml
When the book is added to stage the book checks the loaderInfo url, if it finds the loaderInfo url, the book will replace id and xmlFile to: id = mybook, xmlFile = panoFlipBook/bookxml/mybook.xml
Then the book checks if there are loaderInfo parameters, if there are any the book will replace id and xmlFile with the once from loaderInfo parameters, so our new parameters are: id=lovelybook and xmlFlie=project/lovelybook.xml.
Then the book processes the xml file and loads.
Why is that?
KRPano can load the book using such link: mybook.swf?id=lovelybook&xmlFlie;=project/lovelybook.xml and it uses an xml "name" to get path to the book plugin - so it is quite simple (but loaderInfo url will not return the name of the book file).
FPP can't have such link stated: mybook.swf?id=lovelybook&xmlFlie;=project/lovelybook.xml, it can only have: layer_26 = panoFlipBook.swf, since we can't pass the book id (that is really needed by FPP not krpano) or the xml file name, we need to play with the names. Changing the book file name will allow us to load several books into FPP player and set up communication between the books and FPP and FPP and the book.
More about it later on, so far I wanted to explain why it works the way it does.
checkVersion
If you want to check what id the book uses or check the licence details you can call the book directly with: panoFlipBook.swf?checkVersion=true.
If the book can't find xml file the book will inform you what file it is looking for.
File / folder paths
In the "Where to start from" chapter I explained how to change the book id and xmlFile. Of course you can change and sometimes you have to change book's file name. Now we come to an important question about paths to other files or folders (especially v.1 users). There is no restrictions at all about changing file names or paths. The book is driven by its xml file, all paths to all files are in the book xml file. If you change a path to a plugin, FPP pano.swf file, to anything - the book will open that file from the new directory. There is only one path you need to remember is the default path of the xml file, but it is not a restriction but a helpful feature rather. The download package has lots of files and folders - the have been set up in the book xml file, if you want to change them, you are welcome to do that, just remember a real file or folder may have a link in the book xml file, don't forget to change both. The really important files are the book itself: "panoFlipBook.swf" file and its xml file: panoFlipBook/bookxml/panoFlipBook.xml.
XML structure
The Pano Flip Book is driven by an xml file. Here is the main structure of this file:
Parametrs
The very main parameters that the book needs is <parameters>, here are all parameters (except plugin nodes) that the book needs, I will now explain one by one what they are used for:
document_width = 900 and document_height = 540
This setting is needed when you use a book plugin that has size. Do you remember my Royal Baths Park presentation? The size of the background with a playing angel was 900px x 540px, but I wanted the book to be in a sort of top right corner of that background. Each object in a bookController* can have resize in something that I called "document mode" (for short: "dm") - this means that if you state document_width and document_height these values will be included in calculation of the resized object. All elements that have document mode resize will be placed according to document_width and document_height, the x of the document will be at -document_width/2 + object.x and the y of the document will be at -document_height/2 + object.y.
*This is the first time I use "bookController" term. I will describe this object in other chapters, for now in short: bookController is an object where everything is located.
external_player_name = none
This setting is needed by a new, in version 2, action called "internal" (I will describe this action in "actions" chapter). If external_player_name = krpano the book will wait for krpano object else the book will remove krpano listeners, if external_player_name = fpp or any other name (this has got to do with the way fpp activates), that name will be used to call a hotspots fpp plugin.
Here is an example:
we write: external_player_name = fpp
then we use an action
action = "internal:fpp.execute(global.hideBook())" - this will call hotspots.execute function
we write: external_player_name = my_player
then we use an action
action = "internal:my_player.execute(global.hideBook())" - this will call hotspots.execute FPP function
we write: external_player_name = krpano
then we use an action
action = "internal:krpano.call(loadPano(null,cubestrip=pano.jpg);)" - this will call krpano.call function
external_player_name setting is because we need to be able to somehow name/find an FPP object and the book needs to know where to turn off KRPano listeners. The best FPP object for calling FPP is hotspots plugin. In KRPano it is different, we have several functions like call, set, get - they all can be used.
Do not use for external_player_name the follwing names:
hotspots
panorama.externals.hotspots
panorama
pano
panorama.pano
they are reserved for the FPP that is loaded into the book.
*A "none" value is just for us to know that we don't use the book as an FPP or KRPano plugin. external_player_name setting is used only when the book is a plugin for KRPano or FPP, it has nothing to do with the fpp player that displays panoramas inside book pages.
center_book = true
If center_book = true the book will Tweenlite (move) to 1/4 th of its width to the right or to the left depending on the page being displayed. Other words the book listens if a page is flipped, if it is the book checks what page it is on, if flipping is between a cover and the inside page the book will correct its position to be always in the center of page_width * 2 width.
scale_book = 0
If scale_book = 0 nothing will happen. If scale_book = 0.8 the book will scale to 80% of smaller stage width or stage height. Of course you may use any value between 0 to 1 to keep the book fully on the stage.
page_width = 400 and page_height = 340
The book has to have size. page_width = 400 state that the left or the right page is 400px long. page_height = 340 state that the book is 340px high. This means that a full page is page_width*2 x page_height. The book uses full page (left and right pages together), if you make a new page jpg it needs to be this size: page_width*2 x page_height. In our example: 800px x 340px.
start_page = 0
After the book loads it can open at any page you want. A start page can start_page = 0 - zero is for a front cover or any other page.
corner_sense = 30 and button_mode = true
The book creates invisible movie clips and places them on each corner. corner_sense = 30 means that the squares the book creates in 4 corners will be 30px in width and 30px in height. If button_mode = true those squares will behave like buttons.
flipping_speed = 15
When the book flips it makes a particular number of function loops. If a book is small you may want to set a different number of those loops to speed up the book flip. If a book has large pages a nice flip may be longer. It is up to you and your taste how long the book will flip a page.
pages_to_preload = 4 and pages_to_preload_after_book = 20
The above 2 settings let you fully control the preload process. When the book loads it first checks if there is a global background*, if there is one, the book will load the background then the book checks how many pages it has and sets and creates page objects then it starts loading the pages* (the code for that looks really funny by the way) from page 0 (cover), when it riches page 3 (in case: pages_to_preload = 4) it starts to load itself and adds to stage page objects for desired start page - now the book appears. Then the book checks if there are any pages_to_preload_after_book, if pages_to_preload_after_book > pages_to_preload the book will load the stated numer of additional pages. If pages_to_preload_after_book > the number of book pages, pages_to_preload_after_book = the number of book pages, so you may have 20 pages in total and pages_to_preload_after_book = 100 - all pages will load.
* global background is background_url in <pages background_url="global_page.jpg"> I will describe this later on
* page is page_url in <page page_url="page.jpg"> I will describe this later on
page_sound = panoFlipBook/booksound/page_sound.mp3
This one is simple - it is a path to a page sound. Page sound is included in Pano Flip Book package.
book_stylesheet = panoFlipBook/css/panoFlipBookStyle.css
This one is also simple - it is a path to the css file the book uses. However it is very important, this file loads first, if the book can't find this file it will inform you. If a plugin needs css file it can be loaded with a simple function without loading additional css file. If you want to see how css file can be included in a plugin please download the preloader plugin sources or gotopage plugi sources.
Plugins
The Pano Flip Book version 2 moved most elements of the book to plugins, a plugin is an external swf file that loads into the book. You set up plugins in parameters node AFTER parameters. Not including a plugin or blocking it by <!-- plugin --> marks will not load the plugin. A plugin can be an image like png or jpg file or swf file. If a plugin is an swf file it can consist some as3 code. If the code is right there can be set up a communication between plugin and the bookController.
Here is a sample code of a plugin:
<plugin layer = "1" path="path/to/plugin.png"/>
The above code is the minimum code you have to write. The book will know what layer the plugin should be on and the book will know what file it should load, however this is not all, when flash loads an external file it always places it at x = 0 and y = 0, also if a plugin is just a simple png or jpg or swf file (without code in it) we are not able to place it in the right position. The solution is some additional settings of a plugin, here is a full code that can be used with a plugin, it is up to you if you use it or not:
<plugin layer = "1" path="path/to/plugin.png" position = "BR" x = "112" y = "80" action = "page:5" button = "true" />
position
The book has a resize handler built in position = "BR" will place the book at bottom right, you may use any settings for TOP, BOTTOM, RIGHT, LEFT, CENTER, two letters need to be used, for example TC - top center , cC - center center, bL - bottom left, there is one additional setting DM - document mode where the book calculates the position of an object including document_width and document_height. You may use small or capital letters and it doesn't matter what goes first T or L.
x, y
This is an additional + px, depending what position is used, if position is top left and x = 20 and y = 50, the plugin will be placed at x=20/y=50, if position is bl for bottom left the object will be placed at x=20/y=stage height - 50.
action
Plugin can have an action attached - just the normal way like the spots (I will describe this at spots chapter).
button
If button = "true" the object will behave like a button.
Once again the above 5 settings can be used and will be of great help but most plugins will not need them or will not need some of them, for example a PageThumb plugin, it loads a small icon for thumbs and it loads thumbs, icon and thumbs need to be controlled separately, they can't have an action as all thumbs would fire the same action, they can't be button = "true" as one of the plugin option is a simple background that we don't want to take any action at all, so in this case we include PageThumbs plugin this way:
<plugin layer = "20" path="panoFlipBook/plugins/PageThumbs.swf" />.
The book IS a plugin
Actually the book is not a plugin but it pretends that it is a plugin - this way the user has full control on what layer the book is, you include the book with this code:
<plugin layer = "16" path="book" position = "CC" x = "0" y = "0"/>
The book uses the built in resize feature, so we rather should use position, x, y, however there might be some applications that you would not want the book to be resized in any way, so just don't include these settings. The resize of the book is in one thing a little different from the resize of other plugins, the book includes in calculations its page_width and page_height, other plugins need to have the width and height added to the x or y parameter.
What happens when a plugin loads
When a plugin loads the book (or maybe I should say bookController - it is an object where everything is located) listens to when the plugin is loaded, then when the loading process is complete the bookController checks if the plugin has a property "init" (if the plugin has a function init ()), if it doesn't (png or jpg plugins can't have as3 code) the book creates a new movie clip, then adds the plugin into that movie clip then adds that movie clip to bookObjects object (that is located in bookController) using a layer parameter. This means that if you are a developer you can get the plugin path this way: bookController.bookObjects.17 (17 is a layer's value of the plugin). Then the bookController loads another plugin. If the plugin is a sort of real plugin - an swf file with proper as3 code and the plugin has an "init" property the book (I will use book for short but really it is the bookController) fires that function and passes bookController object, since then loading a new plugin is DEPENDANT on the loaded plugin. The plugin returns a function addBookObject to the bookController and passes plugin object to the bookController. (This is the first moment when the plugin may let bookController to load another plugin by using a function: bookController.loadAnotherPlugin();.) When the bookController gets a plugin object in return the bookController adds the plugin to bookObjects object using its id in lower case, since then the plugin is accessible with this code:
bookController.bookObjects.plugin_id
for example the preloader plugin can be accessed by another plugin with this as3 code:
bookController.bookObjects.preloader
or you may use an internal action in the book xml file to fire plugin's function like this:
action = "internal:my_plugin_id.myFunction(do_something)"
Then if there are additional xml parameters for that particular plugin and the plugin has a property newParams the bookController fires the newParams function of the plugin and passes the parameters to the plugin. It is up to the plugin developer when another plugin will start to load, there is only one preloader plugin that is used for loading plugins, loading the book and loading panoramas. My advice is: if plugins are on lower layer than the book you may take advantage of the preloader, but if a plugin is on a layer above the book and the book is being displayed just let it load its own way and load another plugin as soon as possible (using function: bookController.loadAnotherPlugin();). Your guest will already be busy watching the book, who cares that a plugin will be visible 2 or 3 seconds later. I will describe as3 plugin structure exactly in other chapters for developers.
Plugin Parameters
Each plugin may have additional parameters (but doesn't have to). The following table marks with bold text the parameters for a plugin "plugin_1". Parameter's node must be the same as plugin id. All default plugins (the once I wrote for the book) are exactly the same swf name as the plugin's id.
Lets take close look at a simple plugin: BottomStrip. I wrote it because version 1 had such strip and I wanted version 2 to look the same as version one. The plugin creates a simple rectangular at the bottom of the stage on witch some other plugins may be located. The plugin is intended to be a sort of strip on the stage and make other plugins more visible. We include the plugin in the book xml using the following code:
<plugin layer = "8" path="panoFlipBook/plugins/BottomStrip.swf" />
The plugin has a built in resize function (I wrote the plugin before I created the resize function in bookController) so we don't include in the xml position, x, y, we also don't want the strip to fire any action and we don't want the strip to be a button, we just want it to display, nothing more, and give other plugins a better contrast. The plugin has additional parameters, here they are:
With these parameters we set strip height, strip color, strip alpha and strip blur - very simple. If you don't want the plugin to be displaying just don't include the plugin in the parameters node or block it with like this:
<!-- <plugin layer = "8" path="panoFlipBook/plugins/BottomStrip.swf" /> -->
I will not describe each plugin and each plugin's parameters as the names of the plugins exactly describe what they do and the parameters of the plugins are quite straight forward, however I need to mention one thing. If a plugin has its position parameter like this: music_player_position = BR they have a bit simpler resize handler than the bookController, the values can be: TL, TR, TC, BL, BR, BC, DM (DM for document mode) and they are case sensitive. If you see a // mark before some plugin parameters like Logo, FullscreenButton or AutoFlip - this means that they had a resize handler built in but I blocked it (the code is not usable any more but still existent in the plugin .as file) , I left the code for developers but these settings are not active and you can delete them from the book xml file - the resize is done by the bookController only. I just wanted to show that the bookController resize is just as gook as the resize of the plugins and if you are going to write your own plugin you are welcome to use the bookController resize. I wrote the plugins before I wrote the resize handler in the bookController.
If you have any questions about a particular plugin you are welcome to post it on the forum. Interface plugins is the best place to do it.
Plugin FPPPlayer - how to activate panorama inside the book
There is one plugin that needs to be explained - it is the FPPPlayer plugin.
The book xml in the book zip package has this plugin blocked with <!-- plugin --> marks.
Why did I do it?
1) I can't distribute FPP files as I don't want to get involved in any licence problems (FPP needs a licence)
2) users expect the book to just start without any errors
3) users may want the book without panoramas inside.
All this made me block this plugin.
To activate the plugin just remove the above marks. So here is the code of the plugin:
<plugin layer = "6" path="panoFlipBook/plugins/FPPPlayer.swf"/>
The FPPPlayer plugin is the main file/class/controller that loads FPP files used for displaying panoramas inside the book, it is a sort of controller that allows resizing panorama, passes values to hotspots plugin, loads panoramas - generally FPP would not work without this file (but it has nothing to do with FPP when the book is a plugin for FPP). Also a plugin structure will let me create a similar plugin but with KRPano control when KRPano can be loaded into another movie clip. Anyway you have to activate this plugin to display panoramas inside the book with FPP interface (the only one at the moment, though I have some plans about this).
This plugin should be loaded before the book loads, so just make sure that the layer value of FPPPlayer plugin is lower than the book layer value. Once it is activated and the bookController completes loading this plugin the plugin activates and looks for pano.swf and sets up the FPP files. If there is a problem, the plugin should inform you that it can't find a file it needs. All settings are in the plugin settings node:
<FPPPlayer action = "" >
if you want a panorama to be loaded on plugin start fill in the action, for example:
action = "loadPano(?panoName=files/panoramas/panorama&panhome=105&tilthome=0&panoType=mov&zoomHome=0.8, 0, none);"
more about actions in the chapter about spot actions.
This setting is called once on plugin start, it has no effect at all later on.
Main settings
The plugin to work needs to know the location of the files it will use:
panorama_player_path = files/theFPPpano/pano.swf - FPP pano.swf
panorama_player_xml = files/theFPPxml/panoFlipBook.xml - FPP xml file
panorama_blank_img = panoFlipBook/blank_img/blank - file that the plugin needs, it is included in the download package
The plugin uses preloader plugin to show the loading process, this will be the text that will show during FPP files preloading:
loading_panorama_files = Preloading Panorama Files
If <FPPPlayer action = "loadPan(....)" > you need to state if this panorama displays inside or outside the book
panorama_inside_book = true
This setting is called once on plugin start, it has no effect at all later on.
Settings:
zoom_button_X = 50
zoom_button_Y = 20
will set the magnifier button that is being displayed on the panorama at top right corner will do a little tuning to the x and y of the magnifier position. In version 2 there is only one corner to witch the magnifier is aligned - top right corner. There is only one setting for the magnifier no matter if it displays inside or outside the book or it is in fullscreen mode or not.
Final settings
panorama_position = TC
panorama_X = 0
panorama_Y = 0
panorama_width = 100%
panorama_height = 200
show_zoom_button = true
show_pano_buttons = true
These settings are quite straight forward, I will not describe what they mean, but I really need to say a few words about some values and the way they work:
1) panorama_position - is exactly the same as in bookController so you can mix the values including capital or small letters TC = tc = Ct = CT (center top), including right center or left center
2) panorama_width or panorama_height can be nymber: 500 (means 500px width) or string: percent, for example: 80% (this will set panorama_width or panorama_height to 80% of the stage width or height if panorama is outside the book, or 80% of total book width or book height if panorama is inside the book)
3) the Final settings (the above settings) - I mean the settings that are in plugin parameters node are DEFAULT settings for a panorama when it is outside the book. What does it mean? If you call a function to place panorama outside the book these settings will be the current panorama settings.
4) You would probably ask now if it is possible to change these settings - NO, these settings are default settings for panorama outside the book, however with an additional action for example: action = "pano:20,40,800,500,TC,true,false" you can change the panorama size and the panorama position no matter where it is located. If you want to know more about this action visit chapter about spot actions.
To book version 1 users: this action changed a little.
To be honest when I placed a panorama outside the book I had a real problem how to manage the panorama, after long thoughts during witch I tried to imagine how users would like to use this feature I came to a conclusion that it might be used most in the way when the book is a little on the right and the panorama a little on the left, guests could turn pages and clicking spots load a panorama, the panorama would be like a movie in a cinema. More less, this is what it is designed for. If there were too many settings you would blame me that there are so many settings that it is not possible to find the right one.
<page> node panorama settings
There are second panorama settings that are placed in the <page> node. Here is an example:
They are exactly the same as the settings in the FPPPlayer plugin setting node but they don't have zoom_button_X nor zoom_button_Y settings. What do they do? They set panorama to new settings. No matter where the panorama is, inside or outside the book, they will change the panorama settings, these parameters are sort of parallel to the default settings (for the outside book panorama display). Once set on any page they will stay unchanged till you change them either by calling an action or by using new panorama settings on a new page, however if the panorama is inside the book after a page flips the panorama will not show if action = "loadPano..." is empty or not existent. The book assumes that if panorama is outside the book you want it display as long as you tell it to disappear, if panorama is inside the book, the book assumes that each page will display a new panorama, another thing is that you are not able to control what panorama is loaded to fpp. I guess you might ask why - because you never know if your guest turns page before or after a panorama loads, if panorama hasn't loaded and a page is flipped you don't want your guest to see what is inside fpp, belive me. So, to display panorama inside the book you need to activate it by an action no matter where it is, it can be in panorama node or in an action. However once panorama is inside the book and you call a function and place it outside the book - the panorama will use the default settings from the plugin node, if you want to change them use an action that sets new settings for panorama together with a loadPano action.
For new users a little explanation: it is possible to call several actions, you do it this way: action = "pano:0,0,200,40|loadPano(...)|page:5" - this action will set new settings of the panorama (and the panorama itself), load a new panorama and turn page to page 5. More about actions in spot action chapter.
And the last thing, setting new settings doesn't have to come with loading new panorama, sometimes it may be wise to just set new settings and prepare the panorama settings for a new size. Anyway you may use the settings, you don't have to, if you don't use new settings on a new page the old settings from previous page will be active. This means that you may set new settings only once on the first page then just load a panorama without passing new settings as the book will use the previout settings as default.
I think this is all about FPPPlayer plugin.
Pages
The book can have pages. Pages are created using xml file, here is the structure:
<pages background_url="global_background.jpg" >
All pages can have one background, I called it once: "global background". If you fill in background_url in <pages > node like this: <pages background_url="global_background.jpg" > the book will load the image global_background.jpg and apply it to every page as background. This way you may create only one page template that will be applied to all pages. However it is possible not to apply this global background to particular pages just by stating: background="false" in the <page > node. Global background can be a jpg, png or swf file. It is advisable to use global background as pages are empty (clear) till they load. If you have lots of pages and you write pages_to_preload = 5 the book will be visible but only 5 pages will be fully loaded, the rest of pages will be clear. Global background is applied to all pages even before loading pages content.
<page page_url="page_background.jpg" page_X="0" page_Y="0" background="false" >
Each <page > can have 4 additional settings:
page_url="page_background.jpg"
page_X="0"
page_Y="0"
background="false"
They may be used but they don't have to be used at all. The page node may look just like this: <page > if you don't need to use the above settings.
page_url="page_background.jpg" - this is actually our page, this page_background can have additional position tuning, for example if you use page_X="20", page_Y="20", page_background will be move right 20px and down 20px - these settings can be helpful especially when you use global background, you may create an image that is 40px smaller, then move it page_X="20" and page_Y="20" and the image will be exactly in the middle, however for spots have some additional settings like alpha, or shadow, sometimes it may be better to use spots instead page_url. page_url is mostly designed to use use with the last setting: background="false" - if this setting is set to false global background will not load. What is it for? Lets assume that you have a great global background that you want to apply to all pages, but you would like one page have a little hole in it (so you can see through that page), you can't have global background as you would see global background through that beautiful hole. So just write background="false" and the global background will not be applied to that particular page.
Spots in the pages
Pages can have spots. Spots are additional elements loaded to pages that can have attached interactive actions. Here is an example of a spot node:
Spot types
There can be 5 different types of spots:
<spot type="area" ... />
Spot type "area" is just a simple rectangle that can be placed over another object for example over some text or an image. It is really useful when you want to add an action to a word or particular area of an image.
<spot type="text" ... > <![CDATA[ your text here ]]> </spot >
Spot type "text" is a html text that is created internaly in the book. To allow html tags the spot has a little different structure, the text has to be placed inside CDATA tag. This type of spot uses book_stylesheet css file. You can also place html tags directly in the text. However to improve performance of the book the text is converted to a bitmap. So it is not possible to add interactivity to a part of the text, but you can add interactivity to whole text spot. If you want one word to be interactive - use area spot over the text spot.
<spot type="image" ... />
Spot type "image" can be jpg, png or swf file. Swf file can be interactive but will not set up any communication with the book.
<spot type="audio" ... />
Spot type "audio" can be an mp3 file. You can attach different music to different pages. Or music can be played on a spot action. Music can start playing automatically on a page flip. If a page is turned all audio spots will close their loaders so the book prepares to load new audio spots on the next page. If you want music to be played permanently use MucicPlayer interface plugin.
<spot type="plugin" ... />
Spot type "plugin" is a special type of spots. It should be an swf file that has as3 code. When the spot is loaded the bookController calls an "init" function in of the spot and passes to the spot bookController object and the page number on witch the spot is located, then if the spot has property "getCurrentPage" the bookController adds a listener "PAGEFLIPPED" and call the plugin each time a page is flipped, then the bookController add the spot to bookObjects object and makes it accessible through that object. All these makes creating page plugins really simple. There is a video.swf file that can load a video to a page - this video needs to be loaded as plugin spot type. The code of this spot plugin is available to download on download page in sources_bookimages.zip package. More about the page plugin interface in the developer chapter.
Spot attributes
There can be several attributes that can be used with a spot.
<spot type="image" id="1" url="panoFlipBook/bookimages/image.jpg" spotX="25" spotY="25" alpha="1" shadow="5" borderColor="#FFFFFF" borderWidth="4"/>
<spot type="text" id="6" spotX="50" spotY="288" spotW="50" spotH="20" alpha="0.7" interactive="true" button="true" shadow="1" action="play:4"> <![CDATA[<b><span class='mute'>mute;</span><b>]]> </spot>
Actions
An "action" is an attribute that every spot or plugin may have. SpotController is the main class that serves spots. The value of an action is passed to a spotController's function called a "pluginAction". This function can accept a single string, then it strips the action string to several actions, it recognizes the type of a single action and passes the values to other functions that do the final call. There can be several actions in one action string, single actions must be separated by: "|" mark. Here is an example:
action = "show:5|play:3|loadPano(...)|pano:20,30,500,600|hide:7"
If you want another spot to do something the spot must have an id attribute. Id is a number. Different pages can have spots with the same id but only spots on a current page will react. Using the id the spot can be found. In the above action the book will show spots with id = 5, play music attached to spots with id = 3, load panorama, set new panorama settings and finally hide spots with id = 7. Several spots can have the same id - this way you sort of group the spots that will react the same.
The book has several actions built in, actions like show, hide, play, pano are sort of short cuts to real functions, the spotController recognizes them and passes the values to the right functions. However, in version 2, there is one special action added to the action list it is an action called "internal" - this action is converted by the spotController to a real as3 action and may call real functions of a real object with real values.
Here is a full list of actions, that the spotController will process:
There are 2 actions that need additional explanation:
pano:100,200,400,500
The full action is: pano:100,200,400,500,TL,true,false - this sets panorama to x=100, y=200, width=400, height=500, align panorama top left, makes magnifier visible, makes buttons invisible, it is possible to use this action this way: pano:100,200,400,500 (the last 3 parameters don't have to be included) - in such way other settings will stay unchanged, or this way: pano:100,200,400,500,,,true - buttons on the panorama will be visible if they were invisible.
action: internal
With version 2 there is a new action that is used to call a book object function directly, it is called "internal" There are 3 versions of that action.
1) passing a string
example - action = "internal:fpp.execute(global.hideBook())":
fpp - is the book object that is added to bookObjects object list (fpp is the FPP to witch the book has been loaded as plugin)
execute - is the function that you want to call
global.hideBook() - is the string value that is passed to execute function
example - action = "internal:krpano.call(set(plugin[panobookbutton].visible, false))":
krpano - is the krpano that is added to bookObjects object list (krpano is the KRPano to witch the book has been loaded as plugin)
call - is the function in the krpano object
set(plugin[panobookbutton].visible, false) - is the string value that is passed to call function
example - action = "internal:book.placePanoramaInBook(true)":
book - is the book object
placePanoramaInBook - is the function that places panorama inside or outside the book
true - is the value, in this case values can be true or false
The above type of the internal action will pass the whole value as string, the value can be long but it will be just one value, if the value is "true" or "false" the value will be converted to a boolean value "true" or "false". This action hast to have brackets () like: internal:object.function(string);.
2) passing an array
example - action = "internal:$bookcontroller.loadPlugin(5, path/to/plugin.swf)":
bookcontroller - is the bookcontroller object that is added to bookObjects object list
loadPlugin - is the function that you want to call
5 - is the layer number you want to load the plugin to
path/to/plugin.swf - is the path to the plugin
By placing the mark: $ before the object name you tell the spotController to treat the values as an array, this means that the string will be split by "," mark. The spotController can pass up to 6 values, if the value is "true" or "false" the value will be converted to a boolean value "true" or "false". This action hast to have brackets () like: internal:object.function(string);.
3) changing settings (for testing)
example - action = "internal:objectName.objectVariable=50":
objectName - is the object you want to call
objectVariable - is the variable you want to change
50 - is the new value of the objectVariable
I never had need to use it, I didn't test it as the book doesn't really have values that need to be changed this way. This could be helpful or useless, I am not sure. Try it and let me know how it works. This action cannot have brackets (), if it does it will be treated like a function.
How to use your key
There is one version of the book for every type of licence. The book can be downloaded at the download page. The main zip file is PanoFlipBook_v.2.0.zip it consists all files and folders including the main book file in version 2.0 and all plugins in swf format in version 1.0. If you are interested in the source code you need to download the plugin zip packages in addition. You are free to edit the sources and make your own plugins, I will be happy to help through the forum.
The book without the key is version STANDARD - free to use by everyone and for every application as long as it is used with the terms.
When you do the payment for the book please allow me up to 24 hours to generate your key, every user has his own key. The key is a small swf file, it consists details about the version of the book, the domain if the required version is DOMAIN and the user. Once you get the key and want to unlock the book (remove logo) open the key. You may open the key with a standalone version of the Flash Player or you may just place the key on an empty browser window. The key has a button: "BROWSE FOR BOOK XML FILE" - click it, an explorer window will pop up, go to your book xml file open it and press "SAVE" on the key. The book will process your xml file and generate a new file as a key that removes the logos. Make sure that the generated file is in the same directory as your book xml file.
If the book is used on a localhost or called directly on a local machine the book will read the generated file then it will process your xml file. You edit only your xml file.
When the book is on a http server the book will read ONLY the generated file. In this case generate a new file with your key and upload an updated file to the directory where the book xml file is located. Each time you change your xml file you need to use your key to update the generated file (once again - this is needed only when the book is on a http server (excluding localhost), if the book is on local machine you need to use your key once at the beginning and second time before you publish the book on a http server).
Book as KRPano plugin
The book is a KRPano plugin. More to come soon.
Book as FPP plugin
The book is an FPP plugin. More to come soon.
Loading the book into another application
The can be loaded into another application. In such case the book may behave like a plugin of an application it is loaded to. It is possible to to set up a both ways communication between the book and the application. More to come soon.
Developer tools
Even though the book is a commercial application it has lots of code open source. Also, the book has been designed in such a way to allow users as much control as possible. I hope this places the book in a position to be a very user friendly application. And even though the book itself is not an open source application it should give you more freedom in using it than any other application of this kind no matter if it is open source or not. Also, partly because I am not a first class as3 programmer (I learn as3 code writing the book), the book has a very simple structure - this allows as3 beginners to create their own book applications or include the book in their own applications like presentations, webpages, galleries (in version 2 of the Pano Flip Book, it is even possible to create a book gallery that would serve several books with all features included). In this chapter I will describe every book object and public function that may be used/called. More to come soon.
More to come soon
Once I finish I will try to make this documentation more usable by adding a list of chapters and anchors or accordion.
what to do to make the book work...
First things first
What happens when the book loads.
The download package includes several files and folders, the book swf file is: "panoFlipBook.swf"
The book in the package uses an xml file: "panoFlipBook/bookxml/panoFlipBook.xml".
However it is possible to change any folder name, any file path.
When the book is loaded it searches for loderInfo parameters: id and xmlFile, they can be passed to the book using swfobject or directly using ? mark like this: panoFlipBook.swf?xmlFlie=my_xml_file.xml. These parameters are passed to the book and written as variables (no actions taken yet). The book has default parameters. The default id is "PanoFlipBook", the default path to the xml is "panoFlipBook/bookxml/book.xml". Once the book is added to the stage it will look for the loaderInfo url and strip it to get book's swf file name, if it can (it is not possible to get the right url in some application for example krpano) the default parameters are then replaced with the new parameters that are connected to the file name of the book. For example you rename the book file panoFlipBook.swf to mybook.swf. The book replaces id with the name: "mybook" and the default xml path to: "panoFlipBook/bookxml/mybook.xml". Then the book checks if there are id and xmlFlie parameters in loaderInfo parameters and replaces the id and xmlFile with these parameters.
Here is what happens:
You rename the book file name to mybook.swf.
You load the book this way: mybook.swf?id=lovelybook&xmlFlie;=project/lovelybook.xml or this way: so.addVariable("xmlFile","project/lovelybook.xml");
The book loads and writes these parameters as variables.
The book has following parameters as default: id = PanoFlipBook, xmlFlie = panoFlipBook/bookxml/book.xml
When the book is added to stage the book checks the loaderInfo url, if it finds the loaderInfo url, the book will replace id and xmlFile to: id = mybook, xmlFile = panoFlipBook/bookxml/mybook.xml
Then the book checks if there are loaderInfo parameters, if there are any the book will replace id and xmlFile with the once from loaderInfo parameters, so our new parameters are: id=lovelybook and xmlFlie=project/lovelybook.xml.
Then the book processes the xml file and loads.
Why is that?
KRPano can load the book using such link: mybook.swf?id=lovelybook&xmlFlie;=project/lovelybook.xml and it uses an xml "name" to get path to the book plugin - so it is quite simple (but loaderInfo url will not return the name of the book file).
FPP can't have such link stated: mybook.swf?id=lovelybook&xmlFlie;=project/lovelybook.xml, it can only have: layer_26 = panoFlipBook.swf, since we can't pass the book id (that is really needed by FPP not krpano) or the xml file name, we need to play with the names. Changing the book file name will allow us to load several books into FPP player and set up communication between the books and FPP and FPP and the book.
More about it later on, so far I wanted to explain why it works the way it does.
checkVersion
If you want to check what id the book uses or check the licence details you can call the book directly with: panoFlipBook.swf?checkVersion=true.
If the book can't find xml file the book will inform you what file it is looking for.
File / folder paths
In the "Where to start from" chapter I explained how to change the book id and xmlFile. Of course you can change and sometimes you have to change book's file name. Now we come to an important question about paths to other files or folders (especially v.1 users). There is no restrictions at all about changing file names or paths. The book is driven by its xml file, all paths to all files are in the book xml file. If you change a path to a plugin, FPP pano.swf file, to anything - the book will open that file from the new directory. There is only one path you need to remember is the default path of the xml file, but it is not a restriction but a helpful feature rather. The download package has lots of files and folders - the have been set up in the book xml file, if you want to change them, you are welcome to do that, just remember a real file or folder may have a link in the book xml file, don't forget to change both. The really important files are the book itself: "panoFlipBook.swf" file and its xml file: panoFlipBook/bookxml/panoFlipBook.xml.
XML structure
The Pano Flip Book is driven by an xml file. Here is the main structure of this file:
|
<?xml version="1.0" encoding="utf-8"?> <book> <parameters> parameter_1 = value parameter_2 = value <plugin layer = "1" path="path/to/plugin_1.swf" /> <plugin layer = "2" path="path/to/plugin_2.swf" /> </parameters> <plugin_1> plugin_parameter_1 = value plugin_parameter_2 = value </plugin_1> <plugin_2> plugin_parameter_1 = value plugin_parameter_2 = value </plugin_2> <pages> <page> <spot type="image" url="spot/url.png" /> </page> </pages> </book> |
Parametrs
The very main parameters that the book needs is <parameters>, here are all parameters (except plugin nodes) that the book needs, I will now explain one by one what they are used for:
|
<parameters> document_width = 900 document_height = 540 external_player_name = none center_book = true scale_book = 0 page_width = 400 page_height = 340 start_page = 0 corner_sense = 30 flipping_speed = 15 pages_to_preload = 4 pages_to_preload_after_book = 20 button_mode = true page_sound = panoFlipBook/booksound/page_sound.mp3 book_stylesheet = panoFlipBook/css/panoFlipBookStyle.css </parameters> |
document_width = 900 and document_height = 540
This setting is needed when you use a book plugin that has size. Do you remember my Royal Baths Park presentation? The size of the background with a playing angel was 900px x 540px, but I wanted the book to be in a sort of top right corner of that background. Each object in a bookController* can have resize in something that I called "document mode" (for short: "dm") - this means that if you state document_width and document_height these values will be included in calculation of the resized object. All elements that have document mode resize will be placed according to document_width and document_height, the x of the document will be at -document_width/2 + object.x and the y of the document will be at -document_height/2 + object.y.
*This is the first time I use "bookController" term. I will describe this object in other chapters, for now in short: bookController is an object where everything is located.
external_player_name = none
This setting is needed by a new, in version 2, action called "internal" (I will describe this action in "actions" chapter). If external_player_name = krpano the book will wait for krpano object else the book will remove krpano listeners, if external_player_name = fpp or any other name (this has got to do with the way fpp activates), that name will be used to call a hotspots fpp plugin.
Here is an example:
we write: external_player_name = fpp
then we use an action
action = "internal:fpp.execute(global.hideBook())" - this will call hotspots.execute function
we write: external_player_name = my_player
then we use an action
action = "internal:my_player.execute(global.hideBook())" - this will call hotspots.execute FPP function
we write: external_player_name = krpano
then we use an action
action = "internal:krpano.call(loadPano(null,cubestrip=pano.jpg);)" - this will call krpano.call function
external_player_name setting is because we need to be able to somehow name/find an FPP object and the book needs to know where to turn off KRPano listeners. The best FPP object for calling FPP is hotspots plugin. In KRPano it is different, we have several functions like call, set, get - they all can be used.
Do not use for external_player_name the follwing names:
hotspots
panorama.externals.hotspots
panorama
pano
panorama.pano
they are reserved for the FPP that is loaded into the book.
*A "none" value is just for us to know that we don't use the book as an FPP or KRPano plugin. external_player_name setting is used only when the book is a plugin for KRPano or FPP, it has nothing to do with the fpp player that displays panoramas inside book pages.
center_book = true
If center_book = true the book will Tweenlite (move) to 1/4 th of its width to the right or to the left depending on the page being displayed. Other words the book listens if a page is flipped, if it is the book checks what page it is on, if flipping is between a cover and the inside page the book will correct its position to be always in the center of page_width * 2 width.
scale_book = 0
If scale_book = 0 nothing will happen. If scale_book = 0.8 the book will scale to 80% of smaller stage width or stage height. Of course you may use any value between 0 to 1 to keep the book fully on the stage.
page_width = 400 and page_height = 340
The book has to have size. page_width = 400 state that the left or the right page is 400px long. page_height = 340 state that the book is 340px high. This means that a full page is page_width*2 x page_height. The book uses full page (left and right pages together), if you make a new page jpg it needs to be this size: page_width*2 x page_height. In our example: 800px x 340px.
start_page = 0
After the book loads it can open at any page you want. A start page can start_page = 0 - zero is for a front cover or any other page.
corner_sense = 30 and button_mode = true
The book creates invisible movie clips and places them on each corner. corner_sense = 30 means that the squares the book creates in 4 corners will be 30px in width and 30px in height. If button_mode = true those squares will behave like buttons.
flipping_speed = 15
When the book flips it makes a particular number of function loops. If a book is small you may want to set a different number of those loops to speed up the book flip. If a book has large pages a nice flip may be longer. It is up to you and your taste how long the book will flip a page.
pages_to_preload = 4 and pages_to_preload_after_book = 20
The above 2 settings let you fully control the preload process. When the book loads it first checks if there is a global background*, if there is one, the book will load the background then the book checks how many pages it has and sets and creates page objects then it starts loading the pages* (the code for that looks really funny by the way) from page 0 (cover), when it riches page 3 (in case: pages_to_preload = 4) it starts to load itself and adds to stage page objects for desired start page - now the book appears. Then the book checks if there are any pages_to_preload_after_book, if pages_to_preload_after_book > pages_to_preload the book will load the stated numer of additional pages. If pages_to_preload_after_book > the number of book pages, pages_to_preload_after_book = the number of book pages, so you may have 20 pages in total and pages_to_preload_after_book = 100 - all pages will load.
* global background is background_url in <pages background_url="global_page.jpg"> I will describe this later on
* page is page_url in <page page_url="page.jpg"> I will describe this later on
page_sound = panoFlipBook/booksound/page_sound.mp3
This one is simple - it is a path to a page sound. Page sound is included in Pano Flip Book package.
book_stylesheet = panoFlipBook/css/panoFlipBookStyle.css
This one is also simple - it is a path to the css file the book uses. However it is very important, this file loads first, if the book can't find this file it will inform you. If a plugin needs css file it can be loaded with a simple function without loading additional css file. If you want to see how css file can be included in a plugin please download the preloader plugin sources or gotopage plugi sources.
Plugins
The Pano Flip Book version 2 moved most elements of the book to plugins, a plugin is an external swf file that loads into the book. You set up plugins in parameters node AFTER parameters. Not including a plugin or blocking it by <!-- plugin --> marks will not load the plugin. A plugin can be an image like png or jpg file or swf file. If a plugin is an swf file it can consist some as3 code. If the code is right there can be set up a communication between plugin and the bookController.
|
<parameters> parameter_1 = value parameter_2 = value <plugin layer = "1" path="path/to/plugin_1.swf" /> <plugin layer = "2" path="path/to/plugin_2.swf" /> </parameters> <plugin_1> plugin_parameter_1 = value plugin_parameter_2 = value </plugin_1> <plugin_2> plugin_parameter_1 = value plugin_parameter_2 = value </plugin_2> |
Here is a sample code of a plugin:
<plugin layer = "1" path="path/to/plugin.png"/>
The above code is the minimum code you have to write. The book will know what layer the plugin should be on and the book will know what file it should load, however this is not all, when flash loads an external file it always places it at x = 0 and y = 0, also if a plugin is just a simple png or jpg or swf file (without code in it) we are not able to place it in the right position. The solution is some additional settings of a plugin, here is a full code that can be used with a plugin, it is up to you if you use it or not:
<plugin layer = "1" path="path/to/plugin.png" position = "BR" x = "112" y = "80" action = "page:5" button = "true" />
position
The book has a resize handler built in position = "BR" will place the book at bottom right, you may use any settings for TOP, BOTTOM, RIGHT, LEFT, CENTER, two letters need to be used, for example TC - top center , cC - center center, bL - bottom left, there is one additional setting DM - document mode where the book calculates the position of an object including document_width and document_height. You may use small or capital letters and it doesn't matter what goes first T or L.
x, y
This is an additional + px, depending what position is used, if position is top left and x = 20 and y = 50, the plugin will be placed at x=20/y=50, if position is bl for bottom left the object will be placed at x=20/y=stage height - 50.
action
Plugin can have an action attached - just the normal way like the spots (I will describe this at spots chapter).
button
If button = "true" the object will behave like a button.
Once again the above 5 settings can be used and will be of great help but most plugins will not need them or will not need some of them, for example a PageThumb plugin, it loads a small icon for thumbs and it loads thumbs, icon and thumbs need to be controlled separately, they can't have an action as all thumbs would fire the same action, they can't be button = "true" as one of the plugin option is a simple background that we don't want to take any action at all, so in this case we include PageThumbs plugin this way:
<plugin layer = "20" path="panoFlipBook/plugins/PageThumbs.swf" />.
The book IS a plugin
Actually the book is not a plugin but it pretends that it is a plugin - this way the user has full control on what layer the book is, you include the book with this code:
<plugin layer = "16" path="book" position = "CC" x = "0" y = "0"/>
The book uses the built in resize feature, so we rather should use position, x, y, however there might be some applications that you would not want the book to be resized in any way, so just don't include these settings. The resize of the book is in one thing a little different from the resize of other plugins, the book includes in calculations its page_width and page_height, other plugins need to have the width and height added to the x or y parameter.
What happens when a plugin loads
When a plugin loads the book (or maybe I should say bookController - it is an object where everything is located) listens to when the plugin is loaded, then when the loading process is complete the bookController checks if the plugin has a property "init" (if the plugin has a function init ()), if it doesn't (png or jpg plugins can't have as3 code) the book creates a new movie clip, then adds the plugin into that movie clip then adds that movie clip to bookObjects object (that is located in bookController) using a layer parameter. This means that if you are a developer you can get the plugin path this way: bookController.bookObjects.17 (17 is a layer's value of the plugin). Then the bookController loads another plugin. If the plugin is a sort of real plugin - an swf file with proper as3 code and the plugin has an "init" property the book (I will use book for short but really it is the bookController) fires that function and passes bookController object, since then loading a new plugin is DEPENDANT on the loaded plugin. The plugin returns a function addBookObject to the bookController and passes plugin object to the bookController. (This is the first moment when the plugin may let bookController to load another plugin by using a function: bookController.loadAnotherPlugin();.) When the bookController gets a plugin object in return the bookController adds the plugin to bookObjects object using its id in lower case, since then the plugin is accessible with this code:
bookController.bookObjects.plugin_id
for example the preloader plugin can be accessed by another plugin with this as3 code:
bookController.bookObjects.preloader
or you may use an internal action in the book xml file to fire plugin's function like this:
action = "internal:my_plugin_id.myFunction(do_something)"
Then if there are additional xml parameters for that particular plugin and the plugin has a property newParams the bookController fires the newParams function of the plugin and passes the parameters to the plugin. It is up to the plugin developer when another plugin will start to load, there is only one preloader plugin that is used for loading plugins, loading the book and loading panoramas. My advice is: if plugins are on lower layer than the book you may take advantage of the preloader, but if a plugin is on a layer above the book and the book is being displayed just let it load its own way and load another plugin as soon as possible (using function: bookController.loadAnotherPlugin();). Your guest will already be busy watching the book, who cares that a plugin will be visible 2 or 3 seconds later. I will describe as3 plugin structure exactly in other chapters for developers.
Plugin Parameters
Each plugin may have additional parameters (but doesn't have to). The following table marks with bold text the parameters for a plugin "plugin_1". Parameter's node must be the same as plugin id. All default plugins (the once I wrote for the book) are exactly the same swf name as the plugin's id.
|
<parameters> parameter_1 = value parameter_2 = value <plugin layer = "1" path="path/to/plugin_1.swf" /> <plugin layer = "2" path="path/to/plugin_2.swf" /> </parameters> <plugin_1> plugin_parameter_1 = value plugin_parameter_2 = value </plugin_1> <plugin_2> plugin_parameter_1 = value plugin_parameter_2 = value </plugin_2> |
Lets take close look at a simple plugin: BottomStrip. I wrote it because version 1 had such strip and I wanted version 2 to look the same as version one. The plugin creates a simple rectangular at the bottom of the stage on witch some other plugins may be located. The plugin is intended to be a sort of strip on the stage and make other plugins more visible. We include the plugin in the book xml using the following code:
<plugin layer = "8" path="panoFlipBook/plugins/BottomStrip.swf" />
The plugin has a built in resize function (I wrote the plugin before I created the resize function in bookController) so we don't include in the xml position, x, y, we also don't want the strip to fire any action and we don't want the strip to be a button, we just want it to display, nothing more, and give other plugins a better contrast. The plugin has additional parameters, here they are:
|
<BottomStrip>
bottom_strip_height = 50 bottom_strip_color = #000000 bottom_strip_alpha = 0.5 bottom_strip_blur = 15 </BottomStrip> |
With these parameters we set strip height, strip color, strip alpha and strip blur - very simple. If you don't want the plugin to be displaying just don't include the plugin in the parameters node or block it with like this:
<!-- <plugin layer = "8" path="panoFlipBook/plugins/BottomStrip.swf" /> -->
I will not describe each plugin and each plugin's parameters as the names of the plugins exactly describe what they do and the parameters of the plugins are quite straight forward, however I need to mention one thing. If a plugin has its position parameter like this: music_player_position = BR they have a bit simpler resize handler than the bookController, the values can be: TL, TR, TC, BL, BR, BC, DM (DM for document mode) and they are case sensitive. If you see a // mark before some plugin parameters like Logo, FullscreenButton or AutoFlip - this means that they had a resize handler built in but I blocked it (the code is not usable any more but still existent in the plugin .as file) , I left the code for developers but these settings are not active and you can delete them from the book xml file - the resize is done by the bookController only. I just wanted to show that the bookController resize is just as gook as the resize of the plugins and if you are going to write your own plugin you are welcome to use the bookController resize. I wrote the plugins before I wrote the resize handler in the bookController.
If you have any questions about a particular plugin you are welcome to post it on the forum. Interface plugins is the best place to do it.
Plugin FPPPlayer - how to activate panorama inside the book
There is one plugin that needs to be explained - it is the FPPPlayer plugin.
The book xml in the book zip package has this plugin blocked with <!-- plugin --> marks.
Why did I do it?
1) I can't distribute FPP files as I don't want to get involved in any licence problems (FPP needs a licence)
2) users expect the book to just start without any errors
3) users may want the book without panoramas inside.
All this made me block this plugin.
To activate the plugin just remove the above marks. So here is the code of the plugin:
<plugin layer = "6" path="panoFlipBook/plugins/FPPPlayer.swf"/>
The FPPPlayer plugin is the main file/class/controller that loads FPP files used for displaying panoramas inside the book, it is a sort of controller that allows resizing panorama, passes values to hotspots plugin, loads panoramas - generally FPP would not work without this file (but it has nothing to do with FPP when the book is a plugin for FPP). Also a plugin structure will let me create a similar plugin but with KRPano control when KRPano can be loaded into another movie clip. Anyway you have to activate this plugin to display panoramas inside the book with FPP interface (the only one at the moment, though I have some plans about this).
This plugin should be loaded before the book loads, so just make sure that the layer value of FPPPlayer plugin is lower than the book layer value. Once it is activated and the bookController completes loading this plugin the plugin activates and looks for pano.swf and sets up the FPP files. If there is a problem, the plugin should inform you that it can't find a file it needs. All settings are in the plugin settings node:
|
<FPPPlayer action = "" >
panorama_player_path = files/theFPPpano/pano.swf panorama_player_xml = files/theFPPxml/panoFlipBook.xml panorama_blank_img = panoFlipBook/blank_img/blank loading_panorama_files = Preloading Panorama Files panorama_inside_book = true zoom_button_X = 50 zoom_button_Y = 20 panorama_position = TC panorama_X = 0 panorama_Y = 0 panorama_width = 100% panorama_height = 200 show_zoom_button = true show_pano_buttons = true </FPPPlayer> |
<FPPPlayer action = "" >
if you want a panorama to be loaded on plugin start fill in the action, for example:
action = "loadPano(?panoName=files/panoramas/panorama&panhome=105&tilthome=0&panoType=mov&zoomHome=0.8, 0, none);"
more about actions in the chapter about spot actions.
This setting is called once on plugin start, it has no effect at all later on.
Main settings
The plugin to work needs to know the location of the files it will use:
panorama_player_path = files/theFPPpano/pano.swf - FPP pano.swf
panorama_player_xml = files/theFPPxml/panoFlipBook.xml - FPP xml file
panorama_blank_img = panoFlipBook/blank_img/blank - file that the plugin needs, it is included in the download package
The plugin uses preloader plugin to show the loading process, this will be the text that will show during FPP files preloading:
loading_panorama_files = Preloading Panorama Files
If <FPPPlayer action = "loadPan(....)" > you need to state if this panorama displays inside or outside the book
panorama_inside_book = true
This setting is called once on plugin start, it has no effect at all later on.
Settings:
zoom_button_X = 50
zoom_button_Y = 20
will set the magnifier button that is being displayed on the panorama at top right corner will do a little tuning to the x and y of the magnifier position. In version 2 there is only one corner to witch the magnifier is aligned - top right corner. There is only one setting for the magnifier no matter if it displays inside or outside the book or it is in fullscreen mode or not.
Final settings
panorama_position = TC
panorama_X = 0
panorama_Y = 0
panorama_width = 100%
panorama_height = 200
show_zoom_button = true
show_pano_buttons = true
These settings are quite straight forward, I will not describe what they mean, but I really need to say a few words about some values and the way they work:
1) panorama_position - is exactly the same as in bookController so you can mix the values including capital or small letters TC = tc = Ct = CT (center top), including right center or left center
2) panorama_width or panorama_height can be nymber: 500 (means 500px width) or string: percent, for example: 80% (this will set panorama_width or panorama_height to 80% of the stage width or height if panorama is outside the book, or 80% of total book width or book height if panorama is inside the book)
3) the Final settings (the above settings) - I mean the settings that are in plugin parameters node are DEFAULT settings for a panorama when it is outside the book. What does it mean? If you call a function to place panorama outside the book these settings will be the current panorama settings.
4) You would probably ask now if it is possible to change these settings - NO, these settings are default settings for panorama outside the book, however with an additional action for example: action = "pano:20,40,800,500,TC,true,false" you can change the panorama size and the panorama position no matter where it is located. If you want to know more about this action visit chapter about spot actions.
To book version 1 users: this action changed a little.
To be honest when I placed a panorama outside the book I had a real problem how to manage the panorama, after long thoughts during witch I tried to imagine how users would like to use this feature I came to a conclusion that it might be used most in the way when the book is a little on the right and the panorama a little on the left, guests could turn pages and clicking spots load a panorama, the panorama would be like a movie in a cinema. More less, this is what it is designed for. If there were too many settings you would blame me that there are so many settings that it is not possible to find the right one.
<page> node panorama settings
There are second panorama settings that are placed in the <page> node. Here is an example:
|
<page page_url="" >
<panorama action = "loadPano(?panoName=files/panoramas/panorama&panoType=mov, 0, none);" panorama_inside_book = "true" panorama_position = TC panorama_X = 0 panorama_Y = 0 panorama_width = 100% panorama_height = 200 show_zoom_button = true show_pano_buttons = true /> <spot type="plugin" url="panoFlipBook/bookimages/play_panorama.swf"/> </page> |
They are exactly the same as the settings in the FPPPlayer plugin setting node but they don't have zoom_button_X nor zoom_button_Y settings. What do they do? They set panorama to new settings. No matter where the panorama is, inside or outside the book, they will change the panorama settings, these parameters are sort of parallel to the default settings (for the outside book panorama display). Once set on any page they will stay unchanged till you change them either by calling an action or by using new panorama settings on a new page, however if the panorama is inside the book after a page flips the panorama will not show if action = "loadPano..." is empty or not existent. The book assumes that if panorama is outside the book you want it display as long as you tell it to disappear, if panorama is inside the book, the book assumes that each page will display a new panorama, another thing is that you are not able to control what panorama is loaded to fpp. I guess you might ask why - because you never know if your guest turns page before or after a panorama loads, if panorama hasn't loaded and a page is flipped you don't want your guest to see what is inside fpp, belive me. So, to display panorama inside the book you need to activate it by an action no matter where it is, it can be in panorama node or in an action. However once panorama is inside the book and you call a function and place it outside the book - the panorama will use the default settings from the plugin node, if you want to change them use an action that sets new settings for panorama together with a loadPano action.
For new users a little explanation: it is possible to call several actions, you do it this way: action = "pano:0,0,200,40|loadPano(...)|page:5" - this action will set new settings of the panorama (and the panorama itself), load a new panorama and turn page to page 5. More about actions in spot action chapter.
And the last thing, setting new settings doesn't have to come with loading new panorama, sometimes it may be wise to just set new settings and prepare the panorama settings for a new size. Anyway you may use the settings, you don't have to, if you don't use new settings on a new page the old settings from previous page will be active. This means that you may set new settings only once on the first page then just load a panorama without passing new settings as the book will use the previout settings as default.
I think this is all about FPPPlayer plugin.
Pages
The book can have pages. Pages are created using xml file, here is the structure:
|
<?xml version="1.0" encoding="utf-8"?> <book> <pages background_url="global_background.jpg" > <page page_url="page_background.jpg" page_X="0" page_Y="0" background="false" > <spot type="image" url="spot/url.png" /> </page> </pages> </book> |
<pages background_url="global_background.jpg" >
All pages can have one background, I called it once: "global background". If you fill in background_url in <pages > node like this: <pages background_url="global_background.jpg" > the book will load the image global_background.jpg and apply it to every page as background. This way you may create only one page template that will be applied to all pages. However it is possible not to apply this global background to particular pages just by stating: background="false" in the <page > node. Global background can be a jpg, png or swf file. It is advisable to use global background as pages are empty (clear) till they load. If you have lots of pages and you write pages_to_preload = 5 the book will be visible but only 5 pages will be fully loaded, the rest of pages will be clear. Global background is applied to all pages even before loading pages content.
<page page_url="page_background.jpg" page_X="0" page_Y="0" background="false" >
Each <page > can have 4 additional settings:
page_url="page_background.jpg"
page_X="0"
page_Y="0"
background="false"
They may be used but they don't have to be used at all. The page node may look just like this: <page > if you don't need to use the above settings.
page_url="page_background.jpg" - this is actually our page, this page_background can have additional position tuning, for example if you use page_X="20", page_Y="20", page_background will be move right 20px and down 20px - these settings can be helpful especially when you use global background, you may create an image that is 40px smaller, then move it page_X="20" and page_Y="20" and the image will be exactly in the middle, however for spots have some additional settings like alpha, or shadow, sometimes it may be better to use spots instead page_url. page_url is mostly designed to use use with the last setting: background="false" - if this setting is set to false global background will not load. What is it for? Lets assume that you have a great global background that you want to apply to all pages, but you would like one page have a little hole in it (so you can see through that page), you can't have global background as you would see global background through that beautiful hole. So just write background="false" and the global background will not be applied to that particular page.
Spots in the pages
Pages can have spots. Spots are additional elements loaded to pages that can have attached interactive actions. Here is an example of a spot node:
|
<?xml version="1.0" encoding="utf-8"?> <book> <pages background_url="global_background.jpg" > <page page_url="page_background.jpg" page_X="0" page_Y="0" background="false" > <spot type="image" url="spot/spot_url.png" /> </page> </pages> </book> |
Spot types
There can be 5 different types of spots:
- area
- image (including jpg, png, swf and gif)
- text
- audio
- plugin
<spot type="area" ... />
Spot type "area" is just a simple rectangle that can be placed over another object for example over some text or an image. It is really useful when you want to add an action to a word or particular area of an image.
<spot type="text" ... > <![CDATA[ your text here ]]> </spot >
Spot type "text" is a html text that is created internaly in the book. To allow html tags the spot has a little different structure, the text has to be placed inside CDATA tag. This type of spot uses book_stylesheet css file. You can also place html tags directly in the text. However to improve performance of the book the text is converted to a bitmap. So it is not possible to add interactivity to a part of the text, but you can add interactivity to whole text spot. If you want one word to be interactive - use area spot over the text spot.
<spot type="image" ... />
Spot type "image" can be jpg, png or swf file. Swf file can be interactive but will not set up any communication with the book.
<spot type="audio" ... />
Spot type "audio" can be an mp3 file. You can attach different music to different pages. Or music can be played on a spot action. Music can start playing automatically on a page flip. If a page is turned all audio spots will close their loaders so the book prepares to load new audio spots on the next page. If you want music to be played permanently use MucicPlayer interface plugin.
<spot type="plugin" ... />
Spot type "plugin" is a special type of spots. It should be an swf file that has as3 code. When the spot is loaded the bookController calls an "init" function in of the spot and passes to the spot bookController object and the page number on witch the spot is located, then if the spot has property "getCurrentPage" the bookController adds a listener "PAGEFLIPPED" and call the plugin each time a page is flipped, then the bookController add the spot to bookObjects object and makes it accessible through that object. All these makes creating page plugins really simple. There is a video.swf file that can load a video to a page - this video needs to be loaded as plugin spot type. The code of this spot plugin is available to download on download page in sources_bookimages.zip package. More about the page plugin interface in the developer chapter.
Spot attributes
There can be several attributes that can be used with a spot.
- type = "image" - just described above
- id = "5" - id is number, a spot needs an id if you want to access this spot through an action
- url = "path/to/image.jpg" - path to an image, swf file
- load = "false" - image and plugin type attribute only, the book assumes: load="true", if false the spot will not load
- visible = "false" - book assumes: visible = "true", if false the spot will load but will not be visible
- spotX = "50" - the x of the spot, the "0" (zero) is in top left corner
- spotY = "90" - the y of the spot, the "0" (zero) is in top left corner
- spotW = "600" - the width of the spot, used with area or text type spots
- spotH = "400" - the height of the spot, used with area or text type spots
- alpha = "0.7" - the alpha of the spot (values: 0-1)
- shadow = "5" - size of shadow, the bigger value the bigger shadow
- interactive = "true" - this will make the spot to move a little on mouse over and out
- button = "true" - this will make a spot to work like a button
- play = "true" - attribute of an audio spot, book assumes: play="false"
- color = "#FFFFFF" - the color of a spot, used with area and text spot (if text spot - used for background)
- borderColor = "#FFFFFF" - this is a text or image spot attribute, used for background border color or image border color
- borderWidth = "4" - this is a text or image spot attribute, used for background border width or image border width
- action = "spot:9|play:8|more actions" - all spots, plugins can have actions, more about actions in action chapter
<spot type="image" id="1" url="panoFlipBook/bookimages/image.jpg" spotX="25" spotY="25" alpha="1" shadow="5" borderColor="#FFFFFF" borderWidth="4"/>
<spot type="text" id="6" spotX="50" spotY="288" spotW="50" spotH="20" alpha="0.7" interactive="true" button="true" shadow="1" action="play:4"> <![CDATA[<b><span class='mute'>mute;</span><b>]]> </spot>
Actions
An "action" is an attribute that every spot or plugin may have. SpotController is the main class that serves spots. The value of an action is passed to a spotController's function called a "pluginAction". This function can accept a single string, then it strips the action string to several actions, it recognizes the type of a single action and passes the values to other functions that do the final call. There can be several actions in one action string, single actions must be separated by: "|" mark. Here is an example:
action = "show:5|play:3|loadPano(...)|pano:20,30,500,600|hide:7"
If you want another spot to do something the spot must have an id attribute. Id is a number. Different pages can have spots with the same id but only spots on a current page will react. Using the id the spot can be found. In the above action the book will show spots with id = 5, play music attached to spots with id = 3, load panorama, set new panorama settings and finally hide spots with id = 7. Several spots can have the same id - this way you sort of group the spots that will react the same.
The book has several actions built in, actions like show, hide, play, pano are sort of short cuts to real functions, the spotController recognizes them and passes the values to the right functions. However, in version 2, there is one special action added to the action list it is an action called "internal" - this action is converted by the spotController to a real as3 action and may call real functions of a real object with real values.
Here is a full list of actions, that the spotController will process:
- http://www.pano-flip-book.com - opens a new browser window
- mail:user@gmail.com - opens a mail program, possible to use string like ?subject etc
- spot:5 - shows,loads or hides a spot - will do the opposite of the current spot state
- show:3,5,8 - shows, loads spot with id 3 and 5 and 8
- hide:7,9,10 - makes spot with id 7 and 9 and 10 visible = false
- move:5,100,200 - moves with tween spot 5 to x = 100 and y = 200, possible to use: move:5,,200 - moves spot 5 to y = 200
- play:6 - starts/stops playing music from spot 6
- page:7 - turns page to page 7
- java:openWindow('index.htm','new title') - calles externalInterface, this is just a sample that is used in the demo package
- pano:100,200,400,500 - sets panorama to x=100, y=200, width=400, height=500
- internal:fpp.execute(global.hideBook()) - calls FPP player the the book is loaded to, more about this function will follow
- ladPano(...) - a shortcut to loadPano function of the FPP player that is displaying panoramas inside the book
There are 2 actions that need additional explanation:
pano:100,200,400,500
The full action is: pano:100,200,400,500,TL,true,false - this sets panorama to x=100, y=200, width=400, height=500, align panorama top left, makes magnifier visible, makes buttons invisible, it is possible to use this action this way: pano:100,200,400,500 (the last 3 parameters don't have to be included) - in such way other settings will stay unchanged, or this way: pano:100,200,400,500,,,true - buttons on the panorama will be visible if they were invisible.
action: internal
With version 2 there is a new action that is used to call a book object function directly, it is called "internal" There are 3 versions of that action.
1) passing a string
example - action = "internal:fpp.execute(global.hideBook())":
fpp - is the book object that is added to bookObjects object list (fpp is the FPP to witch the book has been loaded as plugin)
execute - is the function that you want to call
global.hideBook() - is the string value that is passed to execute function
example - action = "internal:krpano.call(set(plugin[panobookbutton].visible, false))":
krpano - is the krpano that is added to bookObjects object list (krpano is the KRPano to witch the book has been loaded as plugin)
call - is the function in the krpano object
set(plugin[panobookbutton].visible, false) - is the string value that is passed to call function
example - action = "internal:book.placePanoramaInBook(true)":
book - is the book object
placePanoramaInBook - is the function that places panorama inside or outside the book
true - is the value, in this case values can be true or false
The above type of the internal action will pass the whole value as string, the value can be long but it will be just one value, if the value is "true" or "false" the value will be converted to a boolean value "true" or "false". This action hast to have brackets () like: internal:object.function(string);.
2) passing an array
example - action = "internal:$bookcontroller.loadPlugin(5, path/to/plugin.swf)":
bookcontroller - is the bookcontroller object that is added to bookObjects object list
loadPlugin - is the function that you want to call
5 - is the layer number you want to load the plugin to
path/to/plugin.swf - is the path to the plugin
By placing the mark: $ before the object name you tell the spotController to treat the values as an array, this means that the string will be split by "," mark. The spotController can pass up to 6 values, if the value is "true" or "false" the value will be converted to a boolean value "true" or "false". This action hast to have brackets () like: internal:object.function(string);.
3) changing settings (for testing)
example - action = "internal:objectName.objectVariable=50":
objectName - is the object you want to call
objectVariable - is the variable you want to change
50 - is the new value of the objectVariable
I never had need to use it, I didn't test it as the book doesn't really have values that need to be changed this way. This could be helpful or useless, I am not sure. Try it and let me know how it works. This action cannot have brackets (), if it does it will be treated like a function.
How to use your key
There is one version of the book for every type of licence. The book can be downloaded at the download page. The main zip file is PanoFlipBook_v.2.0.zip it consists all files and folders including the main book file in version 2.0 and all plugins in swf format in version 1.0. If you are interested in the source code you need to download the plugin zip packages in addition. You are free to edit the sources and make your own plugins, I will be happy to help through the forum.
The book without the key is version STANDARD - free to use by everyone and for every application as long as it is used with the terms.
When you do the payment for the book please allow me up to 24 hours to generate your key, every user has his own key. The key is a small swf file, it consists details about the version of the book, the domain if the required version is DOMAIN and the user. Once you get the key and want to unlock the book (remove logo) open the key. You may open the key with a standalone version of the Flash Player or you may just place the key on an empty browser window. The key has a button: "BROWSE FOR BOOK XML FILE" - click it, an explorer window will pop up, go to your book xml file open it and press "SAVE" on the key. The book will process your xml file and generate a new file as a key that removes the logos. Make sure that the generated file is in the same directory as your book xml file.
If the book is used on a localhost or called directly on a local machine the book will read the generated file then it will process your xml file. You edit only your xml file.
When the book is on a http server the book will read ONLY the generated file. In this case generate a new file with your key and upload an updated file to the directory where the book xml file is located. Each time you change your xml file you need to use your key to update the generated file (once again - this is needed only when the book is on a http server (excluding localhost), if the book is on local machine you need to use your key once at the beginning and second time before you publish the book on a http server).
Book as KRPano plugin
The book is a KRPano plugin. More to come soon.
Book as FPP plugin
The book is an FPP plugin. More to come soon.
Loading the book into another application
The can be loaded into another application. In such case the book may behave like a plugin of an application it is loaded to. It is possible to to set up a both ways communication between the book and the application. More to come soon.
Developer tools
Even though the book is a commercial application it has lots of code open source. Also, the book has been designed in such a way to allow users as much control as possible. I hope this places the book in a position to be a very user friendly application. And even though the book itself is not an open source application it should give you more freedom in using it than any other application of this kind no matter if it is open source or not. Also, partly because I am not a first class as3 programmer (I learn as3 code writing the book), the book has a very simple structure - this allows as3 beginners to create their own book applications or include the book in their own applications like presentations, webpages, galleries (in version 2 of the Pano Flip Book, it is even possible to create a book gallery that would serve several books with all features included). In this chapter I will describe every book object and public function that may be used/called. More to come soon.
More to come soon
Once I finish I will try to make this documentation more usable by adding a list of chapters and anchors or accordion.