[Tutorial] Quickstart Guide (EN)

[Florian Nücke]

MegaZine 3 - A Quickstart Guide

Although this guide tries to be as basic as possible, a certain knowledge about HTML and/or XML will prove to be very helpful.
Please note that all references to files will assume you have extracted the contents of the bin folder in the package somewhere, and that this directory you extracted the contents to represents the root directory for your MegaZine project. E.g. you extracted the contents of the bin folder to C:\MyMegaZine\, then that is your root directory, and should contain the index.html and three folders named swfobject, swfaddress and megazine.

Note: this guide is explicitly for version 1.x, not the new version 2.x. For version 2.x, please see the project wiki for tutorials and documentation.

1 - Setting It Up

1.1 - Page Size
If you wish not to use the default page size there are two adjustments to make.

1.1.1 - XML
First comes the XML adjustment. Open the file megazine.xml in the megazine subfolder. You will see a tag named book. To it's attributes, add the following:
pagewidth and pageheight, and enter the values of the desired page size.
An example: say you want your pages to be 300 pixels wide and 200 pixels high, then it would look like this:

Code: (xml)

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book SYSTEM "http://megazine.mightypirates.de/megazine.dtd">
<book pagewidth="300" pageheight="200">
    <chapter>
        <page>
        </page>
    </chapter>
</book>

And that's it for the XML.


1.1.2 - HTML

Update: This section is deprecated now, as the size is dynamically defined in the CSS, so you most likely don't have to change the sizes in the HTML any more. If you do, make sure to give a fixed size in the CSS class #megazine, otherwise the settings in the script section won't have any effect.

Next a little change to the HTML is necessary, to give Flash enough space on the webpage. Open the file index.html in the root directory.
Look for the  <script> Block in the head of the file.
Here you need to change the width (default 750, marked (1)) and the  height (default 700, marked (2)). As a general rule of thumb for minimum sizes, use
width = pagewidth * 2 + 200
and
height = pageheight * 2
although the height calculation only works for pages higher than wide. The actual formula for the minimum height, so that pages cannot be cut off at the top or bottom while turning is
height = sqrt(pagewidth * pagewidth + pageheight * pageheight) * 2 - pageheight
i.e. the page diagonale times two minus the page height. But using a value a bit bigger never hurts, as it allows more of the reflection to be seen. Also, if you have a lot of pages, making the movie higher gives more room to the page navigation.
Alternatively you can just try some values until it fits.
Although this was a bit on the mathematical end, now you're done with setting up the page size.


1.2 - Background Color

If you wish to change the webpage's background, here is how: if you have closed it, open the file index.html again.

In the same place you changed earlier to adjust the size (see previous section) now change the value #333333 (marked (3)) to a color of your choice (in HTML/CSS format, meaning the hexadecimal representation with a leading #. See Wikipedia). Look for the the style block in the head, and in it for the text background: #333333; (marked (5)). Modify the value right to background to the same value.

Alternatively you can use a background image. In that case remove the two slashes (//) at the line marked (4) and in the CSS section write  url('path/to/some/image.jpg'); next to background: instead of a color value.
And that's that.


2 - Creating the Pages

2.1 - Creating the Page Elements

After all the basic obstacles have been cleared, you are now ready to create your pages. For this purpose, open the file megazine.xml in the megazine subdirectory.
To start with, copy the <page></page> block until there is one page element for every page you want. Please note that a page element represents a <strong>single</strong> page, not a double page. A double page (representing a physical page) is made up from two page elements. This also means there has to be an even number of pages. If there is not, a blank one will be automatically inserted as the very last page.


2.2 - Setting Page Properties

There are some very basic settings you should now about: the bgcolor, foldfx and stiff attributes for pages.

• bgcolor
  Lets you set an individual page background color. This is only relevant if any part of the actual page shows, though. This does not have to be a hexadecimal value, but it is recommended for readabilities sake. Unlike the webpage background color a hexadecimal value has to be prefixed with 0x instead of the # character.
• foldfx
  This controls the visibility of the "folding effect" for the page. Folding effects are the shadow and highlight in the middle of the book, creating the visual effect of the pages to bulge (making them appear more three dimensionl). Although you can normally leave this setting untouched, you might wish to disable the effect for double pages displaying one big image.
• stiff
  Tells the page, if set to true, that it is a stiff page, such as the cover of a hardcover. Although it can be used anywhere in the book, it is recommended to use this only for the first and last page. It is sufficient to supply this argument only for one page element of one "physical" page.

A page with some attributes set would look like this:

Code: (xml)

<page bgcolor="0xFF0000" stiff="true"></page>

and would produce a stiff, red page. Also, no folding effects will be used, because stiff pages never use them.
Another example:

Code: (xml)

<page bgcolor="0x0000FF" foldfx="0"></page>

would produce a blue page, without folding effects.


2.3 - Inserting Page Content

Let's go with the easiest case, and assume you have an image of every page, you just want the images to be displayed as pages in the MegaZine. Create an img element in every page, referencing to the image to display. The syntax for this is:

Code: (xml)

<img src="path/to/my/image.jpg">

Do this for every page, until your XML looks something like this:

Code: (xml)

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book SYSTEM "http://megazine.mightypirates.de/megazine.dtd">
<book>
    <chapter>
        <page>
            <img src="src/cover_outside.jpg"/>
        </page>
        <page>
            <img src="src/cover_inside_and_inprint.jpg"/>
        </page>
        <page>
            <img src="src/content.jpg"/>
        </page>
        <page>
            <img src="src/some_picture.jpg"/>
        </page>
        <page>
            <img src="src/cover_back_blank.jpg"/>
        </page>
        <page>
            <img src="src/cover_back_outside.jpg"/>
        </page>
    </chapter>
</book>

In this case the images are in the folder megazine/src, with the names as seen above. This is very synonymous to using the img element in HTML.

That is all of the basics, enough to create a simple book. For more features see the documentation, which holds a complete listing of all elements and their attributes.
Lastly, you might want to validate your megazine.xml, to avoid typos and other syntactical errors. A nice validator can be found here.