Magalone

Table of Contents

Demo

Quick Start

  1. Copying files
  2. Preparing your PDF Document
  3. Adding source files to your website
  4. Adding the Magalone Reader to your website
  5. First run and document generation
  6. Changing the default size
  7. Configuration
  8. Adding overlays
  9. Choosing a theme

Advanced Users

  1. CSS Styling
  2. Providing your own HTML Elements
  3. Advanced overlays
  4. Adding your own language

Help

  1. Troubleshooting

Demo

For a demo of Magalone go here.

Quick Start

A) Copying files - top

Copy the contents of the source folder to your webserver.

B) Preparing your PDF Document - top

Copy your PDF Document into the /magalone_folder/documents/doc1/ folder. Your file tree should look something like this:

C) Adding source files to your website - top

Add the following to the head section of your HTML document:

    <script src="/magalone_folder/js/magalone.min.js" type="text/javascript"></script>
    <link href="/magalone_folder/css/magalone.min.css" type="text/css" rel="stylesheet" />
    <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet" />

Here is an example of how this should look in your document:

    <!DOCTYPE html>
    <html xmlns="http://www.w3.org/1999/xhtml">
        <head>
            <title>My Website</title>

            <!-- Magalone -->
            <script src="/magalone_folder/js/magalone.min.js" type="text/javascript"></script>
            <link href="/magalone_folder/css/magalone.min.css" type="text/css" rel="stylesheet" />
            <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet" />

            <!-- Your content here -->
            <link href="my_style.css" type="text/css" rel="stylesheet" />

        </head>

Remember to enter the correct path for these files depending on the Magalone folder location on your server

For advanced users: If you do not plan on showing either the fullscreen or thumbnails button, you do not need to include the Material Icons Font, reducing your network footprint.

D) Adding the Magalone Reader to your Website - top

Add the following to your HTML document where you want the reader to appear:

   <div id="reader-container" data-path="./documents/doc1/"></div>

And here is an example of how this might look in your HTML code:

    <body>
        <header>Page Header</header>
        <article>
            <h1>This is the title</h1>

            <p>This is a paragraph of text above the reader</p>

            <div id="reader-container" data-path="./documents/doc1/"></div>

            <p>This is another paragraph of text below the reader</p>
        </article>
        <footer>Page Footer</footer>
    </body>

By default the reader will be 1024px by 768px in size. It will probably break your website layout, do not worry. This will be fixed later!

E) First run and document generation - top

Upload and open your website now. If you have done everything correctly, Magalone should be able to find your PDF Document and start preparing it.

This process can take a while depending on the size of the document.

After generation the page should refresh automatically, if it does not, refresh the page manually. If everything worked out, you should now see your document loading properly for the first time.

F) Changing the default size - top

In most cases you need to adapt the look and feel of Magalone to fit the style of your page.

CSS Stylesheet

In a CSS Stylesheet document, add the following CSS style and adjust the values as needed:

            #reader-container
            {
                height: 500px;
                width: 100%;
            }

G) Configuration - top

Now that you have successfully set up Magalone, here are some instructions on how to configure it to suit your needs!

Magalone provides a variety of different options which you can handily configure just by adding new attributes to the reader element.

Attributes are additional values added to an HTML element. For example in an <img> element, the src="my_image.jpg" part is an attribute. In the example provided above, data-path="./documents/example_doc/" is an attribute of Magalone. You can add as many as you like, but only the ones listed below will change the behaviour.

ATTENTION: Do not copy and paste the attribute names from this table! Always write them, copying and pasting them will not work!

Attribute Name Valid Values Description
data‑path Text (Required) The relative or absolute path to your PDF document directory.
data‑page‑mode auto, single or double Determines the page mode for the reader. auto will automatically choose the best page mode depending on available space whereas single and double will force single page or double page mode respectively.(Default: auto)
data‑language en(English) or de(German) Determines the language of messages (Default: en)
data‑small‑controls true or false When set to true the control buttons will be half-size
data‑show‑download true or false When set to true will enable showing the download button, allowing users to download the PDF file
data‑enable‑keyboard true or false Enable navigating pages by using the left and right arrow keys
data‑enable‑swiping true or false Enable navigating pages by swiping left and right
data‑enable‑arrows true or false Show arrow buttons to the left and right to navigate pages
data‑enable‑pinching true or false Enable pinching gesture on touchscreen devices for zooming
data‑enable‑double‑click true or false Enable double-click/tap gesture to set/reset zoom level
data‑enable‑mouse‑wheel true or false Enable zooming in and out by using the mouse wheel
data‑zoom‑wheel 1 and up The percentage of zoom level that a 'click' of the mouse wheel changes. (Ex.: 10 = 10% of change per mouse wheel 'click') (Default: 10)
data‑zoom‑min auto or 1 and up (but lower than data‑zoom‑max) The minimum zoom percentage (how far you can zoom out, the lower the number the farther you can zoom out). When set to auto the minimum zoom level will be limited to fit content (Default: auto)
data‑zoom‑max 2 and up (but higher than data‑zoom‑min) The maximum zoom percentage allowed. (how far you can zoom in, the higher the number the farther you can zoom in) (Default: 400)
data‑zoom‑doubleclick 1 and up When the double click zoom is activated, it will switch between auto-fit and the zoom percentage defined here. (Default: 100)
data‑show‑fullscreen true or false When set to true will enable showing the fullscreen button, allowing users to enter or exit fullscreen mode
data‑immersive‑fullscreen true or false When set to true will hide all other controls in fullscreen mode
data‑show‑invert true or false When set to true will enable showing the invert button, allowing users to invert the colors for better readability in certain situations
data‑show‑thumbnails true or false When set to true will enable showing the page thumbnails button, allowing users to show and hide the page thumbnails bar which shows clickable thumbnails of all pages
data‑thumbnails‑direction top, left, right or bottom Determines the side on which the page thumbnails bar will appear from. (Default: bottom)
data‑thumbnails‑overlay true or false When set to true the page thumbnails bar will not take up space when it is opened and instead slide over the document. (Default: false)
data‑thumbnails‑size 1 and up The size in pixels of the page thumbnails bar. If the direction is top or bottom then this will determine the height, if the direction is left or right then this will be the width. (Default: 128)
data‑slideshow true or false When set to true will enable slideshow mode. This will force the content into single page mode and automatically advance paging like in a presentation.
data‑slideshow‑time 1 and up The number of seconds that a slide will be shown before advancing to the next slide. (Default: 5)
data‑slideshow‑show‑controls true or false When set to true will show slideshow controls (back, play/pause, next)
data‑slideshow‑use‑pdf true or false When set to true the slideshow mode will use the PDF renderer instead of using only images.
data‑animation none, swipe or flip Determines the paging animation. Swipe will move the pages in parallax when swiping, flip will animate the pages as if you were flipping through a book. (Default: none)
data‑page‑sound 1 to 20 Choose one of twenty different sounds to play when you change the page
data‑page‑sound‑volume 1 to 100 The volume of the page sound in percent
data‑start‑page 1 and up When set, the flipbook will start on the given page (Default: 1)
data‑no‑pdf true or false When set to true Magalone will not load the PDF file for hi-res rendering and instead fall-back on only showing images.

Note that paging animations are only possible if all pages in your document are the same size. If they are not, animations will be disabled automatically.

Here is an example of a reader element with some settings:

        <div 
            id="reader-container" 
            data-path="./documents/doc1/"
            data-show-fullscreen="true"
            data-enable-swiping="true"
            data-enable-pinching="true"
            data-max-zoom="200">
            </div>

H) Adding overlays - top

To add overlays to your content you simply add a div with the class overlay into your reader-container element and specify what it does with a few simple attributes. If your overlay requires a resource you add it by nesting a source element pointing to the resource.

For example:

        <div 
            id="reader-container" 
            data-path="./documents/doc1/"
            data-show-fullscreen="true"
            data-enable-swiping="true"
            data-enable-pinching="true"
            data-max-zoom="200">
            
            <div 
                class="overlay" 
                data-display="pin" 
                data-type="link" 
                data-x="100" 
                data-y="100" 
                data-page="1">
                    <source src="http://www.google.com" />
            </div>

        </div>

ATTENTION: Do not copy and paste the attribute names from this table! Always write them, copying and pasting them will not work!

Attribute Name Valid Values Description
data‑display pin or area (Required) Determines how the overlay is displayed. pin shows a round icon while area display it as a transparent area
data‑type html, image, gallery, video, audio, link, page, embed (Required) Determines the type of overlays content
  • html - An overlay that will display custom HTML content when opened
  • image - An overlay that contains an image
  • gallery - An overlay containing a series of images displayed as a slideshow
  • video - An overlay containing a video. (See Media Formats for more information)
  • audio - An overlay containing an audio file. (See Media Formats for more information)
  • link - An overlay that is a link to another website
  • page - An overlay that links to another page within your document
  • embed - An overlay that displays another website within itself
data‑page 1 to amount of pages (Required) Determines which page this overlay appears on
data‑x 0 to page width (Required) Determines the horizontal position (See Overlays Positions)
data‑y 0 to page height (Required) Determines the vertical position (See Overlays Positions)
data‑width 1 and up (Required for 'area') Determines the overlay area width (See Overlay Positions)
data‑height 1 and up (Required for 'area') Determines the overlay area height (See Overlay Positions)
data‑open‑width 200 and up Determines the width of the overlay when opened
data‑open‑height 80 and up Determines the height of the overlay when opened
data‑icon Material Icon Name Set a different icon for this overlay regardless of type (See Material Icons)

To provide the content for your overlays (with exception of the html type) you must provide a source element within the overlay element itself. Here are some examples for the different types of overlay:

        <div 
            id="reader-container" 
            data-path="./documents/doc1/">
            
            <!-- LINK overlay -->
            <div 
                class="overlay" 
                data-display="pin" 
                data-type="link" 
                data-x="100" 
                data-y="100" 
                data-page="1">
                    <source src="http://www.google.com" />
            </div>
            
            <!-- PAGE overlay -->
            <div 
                class="overlay" 
                data-display="pin" 
                data-type="page" 
                data-x="100" 
                data-y="100" 
                data-page="1">
                    <!-- Link to page 7 -->
                    <source src="7" />
            </div>
            
            <!-- EMBED overlay -->
            <div 
                class="overlay" 
                data-display="pin" 
                data-type="embed" 
                data-x="100" 
                data-y="100" 
                data-page="1">
                    <!-- Show the Lipsum website in an iframe -->
                    <source src="http://www.lipsum.com" />
            </div>
            
            <!-- IMAGE overlay -->
            <div 
                class="overlay" 
                data-display="pin" 
                data-type="image" 
                data-x="100" 
                data-y="100" 
                data-page="1">
                    <source src="/images/picture.jpg" />
            </div>
            
            <!-- GALLERY overlay -->
            <div 
                class="overlay" 
                data-display="pin" 
                data-type="gallery" 
                data-x="100" 
                data-y="100" 
                data-page="1">
                    <source src="/images/picture1.jpg" />
                    <source src="/images/picture2.jpg" />
                    <source src="/images/picture3.jpg" />
                    <source src="/images/picture4.jpg" />
                    <source src="/images/picture5.jpg" />
            </div>
            
            <!-- AUDIO overlay -->
            <div 
                class="overlay" 
                data-display="pin" 
                data-type="audio" 
                data-x="100" 
                data-y="100" 
                data-page="1">
                    <!-- Add multiple sources in different file formats for -->
                    <!-- cross-browser compatibility -->
                    <source src="soundfile.mp3" type="audio/mp3" />
                    <source src="soundfile.ogg" type="audio/ogg" />
                    <source src="soundfile.webm" type="audio/webm" />
            </div>
            
            <!-- VIDEO overlay -->
            <div 
                class="overlay" 
                data-display="pin" 
                data-type="video" 
                data-x="100" 
                data-y="100" 
                data-page="1">
                    <!-- Add multiple sources in different file formats for -->
                    <!-- cross-browser compatibility -->
                    <source src="videofile.mp4" type="video/mp4" />
                    <source src="videofile.ogv" type="video/ogg" />
                    <source src="videofile.webm" type="video/webm" />
            </div>

        </div>

I) Choosing a theme - top

If you don't like the default look, you can try making your own or choose one of the included themes!

All available themes are inside the css folder and start with theme_. To include a theme on your website, simply include the file in your head after the magalone.min.css. Here is an example on how to load the theme_fenster theme:

    <!DOCTYPE html>
    <html xmlns="http://www.w3.org/1999/xhtml">
        <head>
            <title>My Website</title>

            <!-- Magalone -->
            <script src="/magalone_folder/js/magalone.min.js" type="text/javascript"></script>
            <link href="/magalone_folder/css/magalone.min.css" type="text/css" rel="stylesheet" />
            <link href="/magalone_folder/css/theme_fenster.css" type="text/css" rel="stylesheet" />
            <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet" />

            <!-- Your content here -->
            <link href="my_style.css" type="text/css" rel="stylesheet" />

        </head>

Advanced Users

A) CSS Styling - top

You can style Magalone by overriding the CSS styles provided. In order to have your CSS Stylsheet take precedence over the CSS provided by Magalone, remember to add it in your head section after the magalone.min.css file

To get you started, here are a few pointers on where to begin:

B) Providing your own HTML Elements - top

When Magalone initializes it creates all HTML elements needed on the fly. Any elements that already exist will be used instead of creating new ones.

This behaviour enables you to populate the #reader-container element with other elements of your choice and they will be used instead, as long as the class names are identical.

In the following example, the left and right navigation buttons have been replaced by classic input buttons instead:

        <div 
            id="reader-container" 
            data-path="./documents/doc1/">
            
            <div class="controls">
                <div class="left">
                    <input class="ctrl btn go-back" type="button" value="BACK" />
                </div>
                <div class="right">
                    <input class="ctrl btn go-fwd" type="button" value="NEXT" />
                </div>
            </div>
            
        </div>

IMPORTANT: Do not modify or change the .ehe-resize-event-dummy element unless you know exactly what you are doing. Changing anything about that element can break Magalone functionality.

C) Advanced overlays - top

Overlay Positions

In order to properly position elements on your page, you should take the image file of the page as reference. You can find the image files for the pages inside the /documents/doc1/images/ folder. Open this image in a photo editing program of your choice and use the pixel coordinates as a reference for positioning overlays.

Keep in mind that overlays are positioned relative to the zoom level, so you do not need to worry about overlays being out of place when zooming in or out and they will stay in the correct position under all circumstances.

The data-width and data-height for area type overlays are also scaled with the zooming level, the data-open-width and data-open-height however is absolute.

Custom Overlays

By using html type elements together with the data-icon attribute, you can create any kind of overlay that is not provided by Magalone itself.

In contrast with other types of overlays, HTML overlays do not take source elements as content, but instead displays the inner HTML content verbatim, which enables you to provide any kind of HTML you require (like for example embedding a Youtube video).

Here is an example of a simple HTML overlay:

        <div 
            class="overlay" 
            data-display="pin" 
            data-type="html" 
            data-icon="text_format" 
            data-x="200" 
            data-y="700" 
            data-open-width="500" 
            data-open-height="300" 
            data-page="1">

            <h1>Title</h1>
            <p>Lorem ipsum dolorem sit amet.</p>

        </div>

Media Formats

Here is a list of supported media formats by browser, as of 9th August 2016:

Audio
Format Chrome Firefox IE Safari Android Stock Chrome Mobile Firefox Mobile IE Mobile Safari Mobile
PCM Wave (.wav) YES YES NO YES MAYBE2 MAYBE2 YES NO YES
Vorbis in WebM (.webm) YES YES NO YES MAYBE2 MAYBE2 YES NO NO
Vorbis in OGG (.ogg) YES YES NO NO MAYBE2 MAYBE2 YES NO NO
MP3 (.mp3) YES YES3 YES YES MAYBE2 MAYBE2 YES3 YES YES
MP3 in MP4 (.mp4) MAYBE MAYBE3 MAYBE YES MAYBE2 MAYBE2 MAYBE3 MAYBE YES
AAC in MP4 (.mp4) YES YES3 YES YES MAYBE2 MAYBE2 YES3 YES YES
Opus in OGG (.ogg) YES YES MAYBE MAYBE NO NO YES NO NO
Video
Format Chrome Firefox IE Safari Android Stock Chrome Mobile Firefox Mobile IE Mobile Safari Mobile
VP8/Vorbis in WebM (.webm) YES YES YES3 YES3 YES YES YES NO NO
VP9/Vorbis in WebM (.webm) YES YES MAYBE MAYBE MAYBE2 MAYBE2 MAYBE MAYBE MAYBE
Theora/Vorbis in Ogg (.ogg) YES YES NO NO NO NO YES NO NO
H.264/MP3 in MP4 (.mp4) YES YES3 YES YES YES YES YES3 YES YES
H.264/AAC in MP4 (.mp4) YES YES3 YES YES YES YES YES3 YES YES

2 Depends on phone vendor/distributor/manufacturer.
3 Only if supported by operating system

D) Material Icons - top

All icons used in Magalone are provided by the Google Material Icons WebFont in order to provide a scalable, unified and versatile icon experience across all kinds of devices.

While it is possible to set your own icons by providing your own HTML elements and changing CSS Stylesheets, it is recommended you use Material Icons when possible.

To see an overview of all available icons go to https://design.google.com/icons/

When making a choice of an icon you want to use (for example as an alternative overlay icon), click the icon on the page and then select ICON FONT in the top right corner of the popup on the bottom of the page. Inside the second step of the instructions you can see something akin to this:

            STEP 2: Use Icon in Your Site
            <!-- For modern browsers. -->
            <i class="material-icons">done</i>
            <!-- For IE9 or below. -->
            <i class="material-icons">&#xE876;</i>

To get the correct icon value, use the content of the first example element, in the example above, the value to use would be done

Thus, if you want to provide a custom icon for an overlay - following the above example - you would provide it as such:

        <div 
            id="reader-container" 
            data-path="./documents/doc1/"
            data-show-fullscreen="true"
            data-enable-swiping="true"
            data-enable-pinching="true"
            data-max-zoom="200">
            
            <div 
                class="overlay" 
                data-display="pin" 
                data-type="link" 
                data-icon="done"
                data-x="100" 
                data-y="100" 
                data-page="1">
                    <source src="http://www.google.com" />
            </div>

        </div>

E) Adding your own language - top

Messages are far and few between, but in case you want to provide a translation for your own language you can use the following template:

        (function InitLocale(window)
        {
            if (window['exHelp'] == void 0 || window['exHelpExtend'] == void 0)
            {
                return setTimeout(InitLocale, 100, window);
            }

            // Create shorthand
            var p = exHelp;

            var locale = p.storage("locale");
            locale["en"] =
                {
                    ERROR_TITLE: "ERROR",
                    ERROR_UPLOAD_PHP: "No upload.php file found or incorrect file",
                    ERROR_NO_FILES: "No files found",

                    LOADING: "Loading...",
                    LOADING_FINISHED: "Finished",
                    LOADING_ERROR: "Error",

                    PROCESSING_TITLE: "Content preparation",
                    PROCESSING_TEXT: "Please wait while your content is being prepared for the first time",
                    PROCESSING_INIT: "Initializing...",
                    PROCESSING_PREP: "Preparing...",
                    PROCESSING_PREPARING: "Preparing {0} pages...",
                    PROCESSING_FINISHED: "Finished. Please reload the page.",
                    PROCESSING_WORKING: "Processing page {0} of {1}...",
                    PROCESSING_UPLOADING: "Uploading page {0} of {1}...",
                    PROCESSING_PDF: "Loading PDF Document... ({0}%)",

                    UNSUPPORTED_AUDIO: "Your Browser doesn't support this type of audio.",
                    UNSUPPORTED_VIDEO: "Your Browser doesn't support this type of video."
                };

        })(window);

Translate the highlighted parts, and don't forget to change the "en" in line 12 to the ISO Code of your language.

Then save the file in the /js/locale/ directory using the same ISO code you provided in line 12 and appending .min.js to the file name. For example: Your French translation file would be called fr.min.js

Then you simply have to set the data-language attribute to load your language file as described in Configuration.

If you feel confident that you translation is accurate, feel free to shoot us a copy so we can include it with the next version!

Troubleshooting

Why is my sound/video not playing?

First you should check if your browser is capable of playing your media file, not all files are supported on all browsers and operating systems.

Generally it is a good idea to provide your media in a multitude of formats to ensure that it can work across as many systems as possible, you can do that by providing multiple sources in your overlay definition. For example:

                <div class="overlay" data-display="pin" data-type="video" data-x="690" data-y="380" data-page="3">
                    <source src="video/small.webm" type="video/webm">
                    <source src="video/small.ogv" type="video/ogg">
                    <source src="video/small.mp4" type="video/mp4">
                    <source src="video/small.3gp" type="video/3gp">
                </div>
I already did all that, but it is not working!

Here are some points to check for:

How can I have more than one document?

In the Quick Start section we gave the example of using the /magalone_folder/documents/doc1/ folder for your initial document. You can simply make a copy of that folder from the .zip file and rename it to doc2, doc3 and so on. Just make sure it contains the upload.php file, this is necessary in order to generate your content. Afterwards don't forget to point the #reader-container element data-path attribute to the correct path.

In fact, these folders can be anywhere you desire as long as you point the #reader-container to the correct path. Just don't forget that you will need a copy of the upload.php file together with a copy of your PDF document renamed as full.php in the same folder.

Why is it not showing any progress when the PDF is still loading?

Make sure your web server supports chunked transfer, accepts the Content-Range header, sends the correct file size in the Content-Length header and - if the PDF is sent GZipped if the Content-Length is sent properly to adjust for the file size difference.

Why are my changes to the options not applying?

Make sure you are on the right page and clear your browser chache or even your server cache if your server supports caching. Magalone reads settings from the HTML, if the old website is still being delivered it cannot see any changes.

When I click the fullscreen button nothing happens!

Some browsers require you to allow websites to go fullscreen. If nothing happens after you click the fullscreen button, you should see if there is a message at the bottom or the top of the screen asking you to allow fullscreen mode. In some browsers that message can also appear on the left or right of the address bar, so keep an eye out for any new or unusual icons.

Why is the reader tiny/weird when I go fullscreen?

Some other CSS rule might be interfering with the fullscreen styling. If you have any other modules or addons on your website that have the ability to go fullscreen, try removing them first to see if any of them have conflicts.

Why does it keep "Preparing..." the content every time I load the page?

There can be mutiple causes:

I cannot get write permissions for my folder

If you cannot get writing permissions for PHP scripts for one reason or another, you can always install a local webserver using a software like XAMPP or WAMP. Install Magalone there on a simple HTML page and let the preparing process finish. Once it has finished preparing and you can confirm that it has done so successfully, you can simply upload the finished processed folder from your local computer to your webserver via FTP or your preferred method of transfer.

Why is my embed type overlay blank even though the URL is correct?

Some pages disallow embedding in an iframe from another website - for example: google.com. Unfortunately there is no way to change that without contacting the website owner. Consider changing the overlay from embed to link.