Book

From MegaZine3
Jump to: navigation, search

'"`UNIQ--css-00000000-QINU`"'

The book tag of an XML book definition is the outermost node, root node to all other nodes. It defines basic behavior of the engine.

Book attributes are in general global settings, such as page turning behavior (speed, area in which a page turn can be triggered, and so on). Some of the attributes are inherited by the chapters the book contains, such as the pages' background color.

All listed attributes titles are prefixed with a small icon. When annotated with Display-related setting, that means the setting is primarily graphics related, i.e. it means the settings changes how something is displayed. Behavior-related setting on the other hand means that the setting is primarily used to control the book's behavior.

Obviously not all settings can be be put into one of these two categories 100%, so there might be some discrepancy in expectance, meaning the icons should only serve as very rough, primary orientation.

Contents

Attributes

Behavior-related setting allowcrossdomaindata

  • Type: Boolean
  • Default: false

When set to true, the engine explicitly tries to load crossdomain.xml files from domains when the first load operation for that domain is performed. The names of the already checked domains are stored, so that the request is only performed once.

Behavior-related setting asulextension

  • Type: String
  • Default: asul

This allows users who's server does not allow custom file extension to set the ASUL documents' extension. When changing this parameter, make sure you also change the actual file extensions accordingly (i.e. change the extension from .asul of the files in the gui folder to whatever you set here, which will in most cases be .xml).

Automatically dragging, left mouse button is not pressed.

Behavior-related setting autodrag

  • Type: Boolean
  • Default: true

Determines whether to automatically drag corners when moving the cursor closer than the set dragrange to them (while the cursor is on top of a page). The idea is to give users a hint that they can drag the corners to turn a page.

Display-related setting bgcolor

  • Type: Integer
  • Default: 0xCCCCCC

The default background color for pages in the book. This refers to the base color a page has, if there are no elements on the page obscuring the actual page itself.

Can be an ARGB or RGB value. While the number may be in any format parseable by ActionScript, it is recommended for readability's sake to use a hexadecimal formatted value. Hexadecimal values are marked by prefixing them with 0x. Note that using many transparent pages next to each other, causing a deep level of transparency and thus many visible pages, can reduce performance significantly (and is therefore not recommended on a book or chapter level).

A value of 0x000000 (or just 0) is transparent, not black. If you want black, use 0xFF000000, i.e. use the ARGB format (alpha-red-green-blue) instead of RGB (red-green-blue).

This attribute is inherited by chapters, from which it is is in turn inherited by pages.

The background gradient and automatically generated book edge.

Display-related setting bggradient

  • Type: Boolean
  • Default: true

Determines whether to show the gradient in the background below the book or not.

Display-related setting bookBgColor

  • Type: Integer
  • Default: 0xFF222222
  • Version: 2.4.0

The background color for the book. This color is used for both the online version (set in the index.html file) and the preview window in mz3Tool. This attribute is not yet supported in mz3Viewer but will be soon.

Can be an ARGB or RGB value. A value of 0x000000 (or just 0) is transparent, NOT BLACK!!


Behavior-related setting cachehandle

  • Type: String
  • Default: Engine Version (in the format x.y.zz, e.g. 2.0.11)
  • Version: 2.0.11

A string that will be attached in the query string of URLs when loading plugins. This allows forcing the engine to reload the plugins when experimenting with nightly builds, e.g. (where the version string doesn't change).

Display-related setting centercovers

  • Type: Boolean
  • Default: true

Determines, whether to center the book, if a cover page is displayed (i.e. the first or last page).

Display-related setting cornerhint

  • Type: Boolean
  • Default: true

Determines whether to initially show the corner hinting, to let users know they can drag the pages. This hint is only shown until a user clicks somewhere, begins a (possibly automatic) drag or turns a page.

Corner hinting looks like an autodrag caused by a user continually moving her cursor in circles. Note that the performance used is equal to that of a normal drag or turn, which might be noticeable. If targeting weaker systems, or notebooks (i.e. systems where power consumption is of importance) it is recommended to disable this feature.

Behavior-related setting cornerhintdelay

  • Type: Integer
  • Default: 4000

The time in milliseconds to wait after the book has been initialized before starting to animate the cornerhint.

Display-related setting cornerhintlocation

  • Type: String
  • Default: bottom

Change to top to start cornerhinting using the top corner of a page instead of the bottom one.

Behavior-related setting dontremove

  • Type: String
  • Default: vid
Warning: this is an advanced attribute, and should only be used when you know what you're doing.

Elements listed in this attribute (as a comma separated list) will stop a page being removed from the stage when it becomes invisible. Pages are normally removed from stage when invisible to improve performance. Some elements (like the video element) will cause problems when removed from the stage, though (in the vid case, because of the FLVPlayback component), so this allows telling the engine to not remove the page when it's invisible.

Behavior-related setting dragarea

  • Type: String
  • Default: top,middle,bottom
  • Version: 2.0.10

A comma separated list of the areas which should be clickable by the user to trigger page turns or drags.

The top and bottom areas are the top and bottom page corners, being squares of the size dragrange x dragrange. The middle is the remaining space between those squares, with a width of dragrange.

This attribute is inherited by chapters, from which it is is in turn inherited by pages.

Edge of the dragged page cannot get closer than dragkeepdist to the book's edge.

Behavior-related setting dragkeepdist

  • Type: Number
  • Default: auto

The distance to keep to the border a drag started from, mainly to avoid glitches. Defaults to page width / 16. When dragging actively (left mouse pressed) the point on the edge being dragged cannot get closer than this value to the actual book edge on that side of the book.

Illustration of the areas influenced by the dragrange attribute.

Behavior-related setting dragrange

  • Type: Number
  • Default: auto

The distance to the border inside which auto dragging starts (when the user moves the cursor near a corner), and clicking triggers a page turn or drag. Defaults to page width / 4.

Behavior-related setting dragspeed

  • Type: Number
  • Default: 0.25

The speed of pages while dragged or turning. Higher values mean faster page movement / turning. 1 means instant, i.e. the page turn animation is skipped and while dragging the page is always next to the cursor.

Behavior-related setting edgeclickable

  • Type: Boolean
  • Default: true

Determines whether the book edge is clickable, and can thus be used to navigate through the book.

Display-related setting edgecolor

  • Type: Integer

The color used when painting the page's edge for the book edges. This defaults to the color of the page itself.

This attribute is inherited by chapters, from which it is is in turn inherited by pages.

Display-related setting elementsfadein

  • Type: Boolean
  • Default: true

Normally, elements are faded in when they finish loading (eyecandy). Although this only applies to visible elements, meaning it will not cause much of a hit on performance, some might prefer to disable this. Makes sense if pages contain heavily vectorized content (e.g. SWFs with lots of text), or you just don't like the effect.

Behavior-related setting errorlevel

  • Type: String
  • Default: NONE

The error levels which are printed in the console (opened by pressing # on the keyboard). Levels are: ERROR, WARNING and NOTICE. Can be combined by using the binary-or operator (|). E.g <book errorlevel="ERROR"> would print out all fatal errors in the console, but suppress notices and warning. ALL is a shortcut for ERROR|WARNING|NOTICE and the default value.

Display-related setting fadein

  • Type: Boolean
  • Default: false

Determines whether to fade in the book once it finishes loading, or to just set it to visible without delay. Enabling this may look nicer, but requires more system resources (causes higher CPU load during the fade in).

Behavior-related setting flashcookies

  • Type: Boolean
  • Default: false
  • Version: 2.0.11 (modified default to false in v2.4.0.8)

Whether to store some settings in a local SharedObject (so-called Flash cookie). This includes muted state, autodrag vs. manual drag, use of reflections, whether the help was opened once before and more.

When testing it can be useful to disable reading and writing these settings. The default was changed, becasue It can be confusing if a change of e.g. reflection='false' does not disable reflections! Reason/background info: 'false' is the default value for reflection, and mz3Tool omits attributes with values that are set to their default value. So with flashcookies set to true a formerly set reflection could not be removed.

Display-related setting flashmenuitems

  • Type: Boolean
  • Default: false

Allows toggling the display of the built-in Flash context-menu items, such as zoom in / out, which might interfere with the book's functionality.

The folding effect in the middle of two pages.

Display-related setting foldfx

  • Type: Number
  • Default: 0.5

The default alpha value of folding effects for pages. If set to 0 folding effects are turned off, 1 means 100% opaque. Folding effects refer to a shadow inbetween two pages, simulating a curvature of the pages.

Behavior-related setting guipath

  • Type: URL
  • Default: gui/

Path relative to the engine to a folder containing ASUL definition files for the GUI, i.e. megazine.asul and gallery.asul.

Left: handcursor="true", right: default.

Display-related setting handcursor

  • Type: Boolean
  • Default: false

Determines whether to use the default hand cursor (that is also used for links, e.g.), instead of the custom arrow cursors defined in the megazine.asul file, when hovering areas that trigger a page drag or turn or images that have gallery entry.

Behavior-related setting htmlFavicon

  • Type: URL
  • Version: 2.4.0

This path is added as

   * "meta property='og:image'"
   * "link rel='icon' type='image/vnd.microsoft.icon'"
   * and as "link rel='image_src'"

to the index.html file. It defines the icon shown in the tab of a browser. The 'og:image' line defines the 'Open Graph' protocol tag "image", used for better integration with facebook. Search for details about supported tags and their definition in the internet

Behavior-related setting htmlJsMissingHint

  • Type: String
  • Default: false
  • Version: 2.4.1

The text entered as value is used as hint in the case Javascript is disabled by the user. The text will 'fly in' after ~2s, i.e. only if MegaZine3 could not take over in time.

Behavior-related setting htmlNoCache

  • Type: Boolean
  • Default: MegaZine3 Title (missing Javascript)
  • Version: 2.4.1

If this attribute is set to true, the following META Tags will be added to the head section of the index file to suppress caching:

   * meta http-equiv='cache-control' content='max-age=0'
   * meta http-equiv='cache-control' content='no-cache'
   * meta http-equiv='expires' content='-1'
   * meta http-equiv='expires' content='Tue, 01 Jan 1980 1:00:00 GMT'
   * meta http-equiv='pragma' content='no-cache' / 

Disabling the cache might be be helpful in case where the content (or parameter settings) change often.


Behavior-related setting htmlTitle

  • Type: String
  • Default: MegaZine3 Title
  • Version: 2.4.0

The text entered as value is used as title in the index file and shows up when the mouse hovers over the browser tab. This is on 'Open Graph' protocol tag, used for better integration with facebook. Google for details about supported tags and their definition.

Behavior-related setting htmlUrl

This link is used as "meta property='og:url'" in the index.html file. You should update this with the canonical URL of your website. This is on 'Open Graph' protocol tag, used for better integration with facebook. Google for details about supported tags and their definition.


Behavior-related setting ignoresides

If set to true, the sides of the book's pages won't be used to trigger page turns on clicks. Only corners will be used.

This will open the side areas for interactivity with the pages' contents, e.g. if you use loaded SWFs with interactivity such as forms you might consider disabling the sides to gain more interactive space for, say, buttons.

Behavior-related setting ignoresyslang

  • Type: Boolean
  • Default: false

If set to true, the system language of the user opening the book will not be regarded when determining the default language, but instead the first entry in the lang attribute will always be used. Normally the user's system language will be used (if available via set localizations, defined in the lang attribute).

Behavior-related setting instantjumpcount

  • Type: Integer
  • Default: 5

The number of pages that can be turned (via navigation or other programmatic means) before the pages are turned instantly, meaning without animation.

Behavior-related setting lang

  • Type: String
  • Default: en

The id of the localizations available to use for the GUI tool tips and texts, as well as book elements.

This can be a list of ids separated by commas (e.g. en,de,it). The first entry in the list will be used as the default language. If the system language (i.e. the language set in the operating system of the user) is in the list it will be used as the default language (unless suppressed using the ignoresyslang attribute).

The engine attempts to load files from the subfolders named with the same language code located in the folder set using the langpath attribute. Inside these language code folders (e.g. langs/de/ the engine will look for one XML used by the engine itself (megazine.xml), and one XML for each loaded plugin which requires localization (where the file is named like the plugin, in the case of the gallery plugin e.g. gallery.xml).

At least one language must be given (if none are specified the engine tries to load English per default).

Behavior-related setting langpath

  • Type: URL
  • Default: langs/

Path to a folder containing localization files (see lang). This can either be an absolute path, or a relative path (in which case the path will be relative to the engine, i.e. the megazine.swf file).

Behavior-related setting langwarn

  • Type: Boolean
  • Default: false

Determines whether to show warning strings if a localization cannot be found. If no warnings are to be shown, the text areas for which no localized string can be found will remain blank.

Behavior-related setting licensekey

  • Type: string

If you are a commercial user and have a license key, that public key goes here.

Example: <book licensekey="8e1b030043ab786f9b77bfb214c7c0da">.

Behavior-related setting loadparallel

  • Type: Integer
  • Default: 2

The number of elements to load at a time. A higher number can result in faster load times (because more elements can be loaded in parallel, thus resulting in a better use of the available bandwidth), but might cause reduced performance while loading. If the user's internet connection is slow, a high number can actually result in longer waiting times.

Display-related setting lowqualitycount

  • Type: Integer
  • Default: 2

The number of pages that can be turned at once before falling back to low quality for performance's sake. When any single page is turned, quality changes to medium. As soon as all page turning animations have finished, quality is restored to best.

Behavior-related setting ltr

  • Type: Boolean
  • Default: true

Determines the reading order of the book.

Left to right reading order (default) means the first page is the leftmost one, right to left reading order the rightmost one. Effectively this inverts the parsing order of the book definition (i.e. the topmost page / chapter element will always be the first page / chapter in the book, regardless of the reading order).

This also effects some other behaviour to stay consistent, e.g. the startpage attribute works "the other way around", i.e. it counts from right to left in ltr="false" mode. If the navigationbar plugin is loaded, the displayed page numbers will also be adjusted accordingly.

Behavior-related setting maxloaded

  • Type: Integer
  • Default: 22

The maximum number of pages that may be present in memory at a time. I.e. only this number of pages will be loaded, and after that new pages will only be loaded after changing the current page. Then the pages left and right to the current one will be loaded until this many pages are present in memory again - pages "further away" than half of this number will be unloaded (removed from memory).

This helps books with a lot of content, such as catalogs, to not use an excessive amount of memory (RAM) at a time. It also reduces bandwidth consumption, because only the necessary pages are loaded - plus some more, so that the user does not have to wait after every page change.

For values greater than 0 books with that many pages or less all pages will be loaded and kept in memory. In case 0 is given, all pages of the book will be loaded to memory, regardless of how many pages there are.

This value represents the number single pages loaded to memory. In case of the default value (22) the current double page (2) and five more double pages to each the left and the right (2*10) will be loaded.

One final remark: Flash caches data once it was loaded on the local drive, which means that once a page has been loaded it will afterward be be loaded from disk, even if it was removed from memory. It will therefore be displayed again almost immediately, and no additional bandwidth will be used.

Display-related setting maxthickness

  • Type: Number
  • Default: 30

The maximum thickness of the book to simulate. This is the screenspace in pixels that may be used to simulate the book's edges.

Note: the actual thickness of the book depends on the number of pages in the book, and the value of the pagethickness attribute. This value only exists to have an easier way of capping the thickness.

Behavior-related setting noasul

  • Type: Boolean
  • Default: false

If activated, this tells the engine to not load any ASUL definitions at all (neither for the engine core, nor for the plugins). This may be useful when wanting to create a very puristic implementation that does not depend on external files.

Behavior-related setting nolangs

  • Type: Boolean
  • Default: false

If activated, this tells the engine to not load any localized strings at all (neither for the engine core, nor for the plugins). This may be useful when wanting to create a very puristic implementation that does not depend on external files.

Display-related setting pagepreview

  • Type: Boolean
  • Default: true

This value determines whether to use thumbnails once rendered for a page as a preview for pages that are currently unloaded. This results in a much better orientation for the user when quickly flipping through the book. The quality of the preview depends on the size of the thumbnails, but should not be a primary concern, as it will be replaced rather quickly as soon as the page actually starts loading.

Display-related setting pagewidth

  • Type: Integer
  • Default: 275

The width of a page in pixels. Content overflowing a page is cut off and not rendered. This is the width a page would have at 100%.

Note: this is the width of a single page, i.e. the book when opened will be twice as wide.

Display-related setting pageheight

  • Type: Integer
  • Default: 400

The height of a page in pixels. Content overflowing a page is cut off and not rendered. This is the height a page would have at 100%.

Behavior-related setting pageoffset

  • Type: Integer
  • Default: 0

Number by which to offset the page numbers. This can be used to sync the page numbers displayed by plugins with page numbers displayed on images used on the pages. For example, the displayed page numbers of the navigationbar plugin will be original number + pageoffset.

Behavior-related setting pagesounds

  • Type: Boolean
  • Default: true

Determines whether to play sounds when dragging / turning pages. Sounds are loaded from the snd/ folder in the engine folder. There are different sounds for dragging, turning, restoring normal pages and for dragging and finishing turns of stiff pages.

Display-related setting pagethickness

  • Type: Number
  • Default: 0.1

The base thickness to use for a single page in the book. This used to calculate the space to use for generating the book edge graphics. The overall thickness of the book edge will be pageCount * pagethickness.

Behavior-related setting pluginpath

  • Type: String
  • Default: plugins/

This allows setting the base path to the directory where plugin SWFs are located. This is basically the same as the book@guipath and book@langpath attributes, just for the plugin folder.

Behavior-related setting plugins

  • Type: String

This attribute allows to define which plugins to load. The given list must be a comma separated list of the names of the plugins to load, e.g. anchors, links, gallery.

Behavior-related setting priorities

  • Type: Definition
  • Default: vid(20); snd(15); area(5); nav(5); txt(5)

This attribute allows to define the base priorities of page elements. The given list must be a mapping of element to priority, e.g. vid(50); img(5); snd(40). The priority of an element controls in which order the elements on a page are loaded. Elements with lower values are loaded first.

Behavior-related setting protocols

  • Type: String

This attribute allows giving a list of other protocols (aside from http, https and file) that are recognized in resolved URLs at various locations in the engine. If an absolute URL with a protocol unknown to the engine is given, it'll not be recognized as such, so make sure to add it here if you use other protocols, such as rtmp.

Display-related setting qualitycontrol

  • Type: Boolean
  • Default: true

If enabled this changes the stage quality as is appropriate for the current turning state to optimize performance. E.g. if at least one page is being turned the quality will be reduced to medium. If a certain number of pages is being turned, the quality will be reduced to low (see lowqualitycount).

Disable this if you do not wish the engine to interfere with the stage quality (note that the previous quality setting will always be restored after all pages have finished turning if enabled).

The reflection of the pages below the book.

Display-related setting reflection

  • Type: Boolean
  • Default: false

Default on/off state of the page reflections. This refers to the reflection of the pages rendered below the actual pages.

If the options plugin is loaded this can be manually enabled by the user.

Warning: requires a lot of performance.

Display-related setting reflectionalpha

  • Type: Number
  • Default: 0.25

This determines the opacity of the reflection, where 0 means completely transparent and 1 means completely opaque.

Display-related setting reflectionfade

  • Type: Boolean
  • Default: false

If set to true the reflection will be faded out towards the bottom, resulting in no immediate cut-off.

Warning: requires even more performance.

Display-related setting reflectionoffset

  • Type: Number
  • Default: 0

An offset used for the vertical position of the reflection. 0 means directly below the pages, a higher value is the gap in pixels between page and reflection (at 100%). For example, reflectionoffset="20" means there will be a 20 pixel gap between the lower edge of the book and the reflection if the zoom is at 100%.

Behavior-related setting reflectionskip

  • Type: Boolean
  • Default: false

If set to true only every second frame will be rendered into the reflection. This improves performance quite a bit, but will result in a slightly jagged animation of the reflection.

Book rotated by 45 degrees.

Display-related setting rotate

  • Type: Number
  • Default: 0

This can be used to set the rotation of the book. An arbitrary value is allowed, but the most common use for this will probably setting the rotation to 90 degrees to produce a vertically flipping book.

Be aware that this might break dynamic text in your pages.

Difference of rendering with or without shadows and highlights.

Display-related setting shadows

  • Type: Number
  • Default: 0.25

The intensity of the shadow and highlight effects while turning or dragging a page. The absolute value is the intensity, higher is stronger. If set to 0 those effects are disabled. If negative the effects are initially disabled, but if enabled have the intensity of the absolute value of the given value. E.g. -0.5 would initially disable the effects, but if enabled later on they'd have the intensity 0.5.

This is what gives pages "depth" when dragging / turning them, so it is not recommended to turn this off.

If the options plugin is loaded this can be manually enabled by the user.

Behavior-related setting slimMz3Version

  • Type: Boolean
  • Default: false
  • Version: 2.4.0

This is an Mz3Tool attribute controlling the creation of an Mz3 Title. If not set (the default setting) the standard version ("fat" version) is built, which includes all plugins, icons and asul files internally of the MegaZine3 program. If set to true, all those assets are NOT bundled which offers the option to only provide those assets really needed. As result you can achieve a smaller footprint of MegaZine3 software. But you really should know what you are doing and what files must be provided where!


Behavior-related setting soundcount

  • Type: String
  • Default: 3,2,5,1,1

This tells the engine how many page turn sounds of each type there are (in the snd/ folder) / how many it should try to load.

The order is as follows:

  • drag
  • restore
  • turn
  • dragstiff
  • endstiff

The files are named accordingly (type.mp3).

Behavior-related setting sndpath

  • Type: URL
  • Default: snd/
  • Version: 2.0.11

Path to a folder containing page turn sounds (see soundcount). This can either be an absolute path, or a relative path (in which case the path will be relative to the engine, i.e. the megazine.swf file).

Display-related setting spinecolor

  • Type: Integer

A small line is painted to hint the spine of the book. This determines the color of that line. Per default the default page background color is used, and painted with a reduced brightness.

Results of different spinecurvature values.

Display-related setting spinecurvature

  • Type: Number
  • Default: -0.5

This determines the curvature of the book's spine. Valid values are in an interval of [-0.5,+0.5].

Hardcover books will more likely look better with a positive curvature, paperbacks will look more realistic with a negative curvature.

Behavior-related setting startpage

  • Type: Integer
  • Default: 1

The default starting page, i.e. which page is displayed when the book is loaded.

Note: this is overridden by a possible number given through the page address if the SWFAddress plugin is loaded.

Display-related setting stiffskew

  • Type: Number
  • Default: 1.0
  • Version: 2.0.12

This controls the tilt of page@stiff pages, where lower values lead to a "flatter" turn, higher values to a "steeper" one.

Behavior-related setting thumbauto

  • Type: Boolean
  • Default: false

When set to true this means thumbnails for all pages will be "generated" once automatically, regardless of whether a thumbnail for a page is requested or not (e.g. on mouseover of a page button in the navigationbar). This does not necessarily mean, however, that the actual page content is loaded once for all pages. If the book@thumbpath attribute is set, thumbnails will be "generated" from the pregenerated thumbnails, by loading those images and storing that graphic. When a page's content is loaded for the first time (because the page comes inside the range of loaded pages) this graphic will be replaced with an automatically generated snapshot.

This attribute has no effect if all pages are stored in memory at the same time (see book@maxloaded attribute), as all thumbnails will be generated from the page content anyway.

This feature is disabled per default for two reasons: it slightly diminishes performance until all thumbnails have been generated, and it is a potential waste of bandwidth. If deactivated only the required thumbnails will be generated, i.e. the thumbnails that should currently be displayed (e.g. when the user hovers a page button in the navigationbar). Generally pages only have to be loaded once to generate a thumbnail. If a page is unloaded (removed from memory) the last known thumbnail will be used.

Display-related setting thumbloadtext

  • Type: String
  • Default: ?

The text to display in thumbnails before they have been generated for the first time.

Display-related setting thumbloadtextsize

  • Type: Number
  • Default: auto

When set, this parameter controls the size of the text in the page thumbnail of not yet loaded/generated thumbnails (see the thumbloadtext attribute). This is especially meant to be used in combination with thumbloadtext, to fit more text into the thumbnail.

Note that the default size is calculated dynamically, based on the size of the thumbnail, to fit in the default text (the question mark, ?), so it is not possible to generally say which font size is required to fit in more text / use the available space better (you will have to experiment).

Behavior-related setting thumbmaxmem

  • Type: Integer
  • Default: 524288

The maximum size a thumbnail for a single page side may have in memory. This is just meant as a 'emergency brake', in case users specify absurdly large pages. In this case it is preferred to control the size of the thumbnails using the book@thumbscale attribute.

Can be disabled by setting it to 0.

Behavior-related setting thumbpath

  • Type: String

A path to a directory containing images which will be used as thumbnails for the pages. This can be used to speed up thumbnail loading, because not the actual page content has to be loaded, but only a small thumbnail graphic.

The images should be sized (book@pagewidth * book@thumbscale)x(book@pageheight * book@thumbscale), i.e. per default a fourth of a page's size.

The images have to be in JPG format, and must be named with numbers according to the page they represent, i.e. 0.jpg, 1.jpg, 2.jpg, ... (numbering starts at 0, so the left cover page is 0). Note that these numbers represent the page indexes meaning they are not reading order aware.

Note: the "0.jpg" to "<pagecount>.jpg" is simply appended to the path given here. I.e. if you set this to thumbs/thumb, the images must be named thumb0.jpg and so on, and be located in the folder thumbs. If you just give thumbs/ (note the trailing slash!) the images must be named 0.jpg and so on.

For a more flexible naming, it is also possible to use a 'variable' in the path, {{num}}, which will be replaced with the page number for which the thumbnail is loaded. In that case it is also possible / necessary to give the file extension. For example, thumbs/th{{num}}.png would load thumbnails thumb/th0.png and so on.

Display-related setting thumbscale

  • Type: Number
  • Default: 0.25

This determines the size of thumbnails relative to the actual page size. Please note that using bigger thumbnails has a heavy impact on used memory, because thumbnails are never unloaded.

Display-related setting thumbstatic

  • Type: Boolean
  • Default: false

Allows to control whether page thumbnails should be dynamic or static. Per default, thumbnails are rerendered each frame, in case the page content changed. This is useful, e.g. when the page contains videos or other animated content.

When set to true, the thumbnail will only be rendered once, when the page content finished loading. If the thumbpath attribute is set, the thumbnail will be generated from the loaded image, and the actual page content will never be rendered into the thumbnail.

This attribute's value may be overwritten on a page side basis, using page@thumbstatic.

Behavior-related setting waitfornoturning

  • Type: Boolean
  • Default: true

Determines whether to wait for all page animations (page turns actually, not drags) are finished before beginning to load new pages. This is only relevant if the book has more pages than may be kept in memory at a time (see maxloaded). When disabling this, the user is less likely to see blank pages when flipping through the pages very fast, but performance will most likely decrease.

Due to the pagepreview functionality it should not be necessary to disable this.

Behavior-related setting zoomdoubleclick

  • Type: Boolean
  • Default: false

Set this to true to allow the user to switch between liquid scaling and the maximum zoom level.

Important: this disables all page interactivity, because of how the double click event in Flash works (does not allow interactivity with child elements of the element using the double click event).

Display-related setting zoominit

  • Type: Number
  • Default: auto

Determines the initial zoom level for the book. If this is not set, liquid scaling kicks in and adjusts the scale accordingly. If set, this is the scaling used for the pages when the book is loaded (will be clamped to the minimum and maximum scaling, though).

Display-related setting zoomliquidscaling

  • Type: Boolean
  • Default: true

This setting can be used to completely disable liquid scaling. Normally, liquid scaling is active initially, i.e. the book size adjusts to the available space. As soon as the user manually zooms in or out, liquid scaling is temporarily disabled, until the user zooms to the zoom level that would currently be used were liquid scaling active (zoom snaps to that value, also see book@zoomsnap). When this is set to false, liquid scaling will never kick in.

Display-related setting zoomliquidsnap

  • Type: Boolean
  • Default: false

Per default, liquid scaling will always scale the book to exactly fit into the available area. In some use-cases this might not be ideal, e.g. if the page content should only be displayed at certain zoom levels, for better visual quality. In these cases, set this attribute to true, which will make liquid scaling use the levels set in the zoomsnap attribute.

Display-related setting zoommaxscale

  • Type: Number
  • Default: 1
  • Aliases: maxscale

Determines the largest size to which to upscale the pages, as a percentage value. E.g. if set to 1.5 the book can get larger to completely fit into the available space until it's at 150% of its original size.
If minscale != maxscale then Liquid Scaling is enabled.

Display-related setting zoomminscale

  • Type: Number
  • Default: 1
  • Aliases: minscale

Determines the smallest size to which to downscale the pages, as a percentage value. E.g. if set to 0.25 the book can get smaller to completely fit into the available space until it's at 25% of its original size.
If minscale != maxscale then Liquid Scaling is enabled.

Display-related setting zoomsnap

  • Type: String
  • Default: 0.25,0.5,1,2,4,8

A comma separated list of numbers, which define the zoom steps to which to "snap". This means that when the zoom level passes one of these values, it will stop at the snap value. For example, if the current zoom level is 0.4 and the user zooms in, and this would normally result in a zoom level of 0.6, with the default settings the new zoom level would be 0.5, because it is given in this list.

The idea is to make it easier for users to reach zoom levels where the book scaling looks better - multiples of two, because in the case interpolation evens out to every second pixel; otherwise there can be interpolation artifacts.

Note on usage: in combination with book@zoomsteps this can lead to unwanted effects. Specifically, the actual number of zoomsteps might differ from the one given, because the snaps will likely result in additional steps. There are two ways to work around this:

  • disable snapping by setting this setting to an empty value (<book zoomsnap="">).
  • only use zoomsnap values as zoomsteps. To do this, set book@zoomsteps to 2 (<book zoomsteps="2">). This way the only "normal" zoom levels would be book@zoomminscale and book@zoommaxscale, but the zooming would snap to each of the given zoom snap levels when zooming, because they will always be "passed".

Liquid Scaling will always count as a "dynamic" snap level. I.e. when allowed (see book@zoomliquidscaling) and passing over the zoomlevel that would currently be set were liquid scaling enabled, the zoom level will snap to that level, and liquid scaling would be enabled again.

Behavior-related setting zoomsteps

  • Type: Integer
  • Default: 5

This defines the number of zoom steps. I.e. when zooming in or out, using either the mouse wheel or the buttons in the navigationbar, or calling the respective functions in the API without a parameter, how many steps there will be.

That is to say if book@zoomminscale is set to 0.5 and book@zoommaxscale is set to 2.5, and this attribute is set to 5, that means that in this case there are 5 steps, being equidistantly distributed: 0.5, 1.0, 1.5, 2.0 and 2.5.

Important: also see book@zoomsnap for possible side effects, causing a different number of actual zoom steps than given here, and how to work around it.

Liquid Scaling has a similar effect, possibly adding another level, increasing the number of steps by one. To disable liquid scaling, see book@zoomliquidscaling.

Note: in version 2.0.6 the behavior is a little different. In this version the attribute is a number, and takes the inverse of the number of steps to use (i.e. 1 / value). This was changed to this approach for 2.0.7+ to be more intuitive to use.

Behavior-related setting zoomwheel

  • Type: Boolean
  • Default: true
  • Aliases: wheelzoom

Determines whether to make use of the mousewheel for zooming in or out the actual pages (when minscale != maxscale). If disabled scaling will only take place via liquid scaling or via the API (or, if loaded, the navigationbar).

Child Nodes

The book may have chapter child nodes, one for each chapter, to define the actual contents of the book.

Two child nodes can be used to define an overall background of the book, background for a static, global background, and pagebackground for a background bound to the page's position and size (i.e. it will also be scaled when zooming in or out). Those two nodes take any number of ASUL elements as their children, which will then be displayed as their actual children on the stage. The variables for the parent size and height (pw, ph) will be the total space available to the engine for background (which is the whole stage size when using the release as it is), and the page width and height for the pagebackground. The origin (top left, coordinates 0,0) is the top left of the overall space available to the engine for the background and the position of the top left corner of the book for the pagebackground.

As of version 2.0.8 it is also possible to define an overall foreground via foreground, which may contain ASUL elements to be shown on top of everything else.

Plugins may use additional nodes to let the user define additional properties, as does the sidebar plugin.

Examples

<book
    pagewidth="400"
    pageheight="600"
    bgcolor="0xffffff"
    plugins="navigationbar, gallery, links, anchors"
    lang="en,de"
    minscale="0.5"
>
    <background>
        <box anchors="0,0,pw,ph" background="image(data/overall_bg.png)"/>
    </background>
    <pagebackground>
        <box width="pagew" height="pageh" background="image(data/prepage.jpg)"/>
    </pagebackground>

    <chapter>
        <page>
            <img src="data/cover.jpg"/>
        </page>
        <!-- ... -->
    </chapter>
    <!-- ... -->
</book>
MegaZine3 Core-related articles
Book elements Book · Chapter · Page · Spreadpage
Page elements Area · GIF · Image · Navigation · Sound · Text · Video