What files are required for Offline and Online distributions

MegaZine3 ForumCategory: TechnicalWhat files are required for Offline and Online distributions
Don Flinn asked 10 months ago

In response to your comments pertaining to distribution of the “offlinePackage” and “onlinePackage”, let me net-out my understanding and questions regarding distribution of the flipbook packages.

Your Comments:

one important thing you must know and consider is this: The folder named “offlinePackage” is the central folder used to store every data you ernter while working with mz3Tool.

It WAS the Offline folder, until everything needed now is zipped into one handy package.

So for the users, the offlinePackage folder is kind of redundant/not of interest . It collects ALL “books” dealt in the same (root)  _mz3Data folder.

It might still be used if you really intend distributing several books together, but that’s not the recommended way.

Our suggestioN: you best follow the proposed “workflow“:

  • click PUBLISH
  • select either Offline or Online
  • simply care about the content of the folder, that opens automatically.
    In case of “Online” you’ll find all needed files and folders needed for an upload to a server in that folder.
    In case of “Offline” there’s just one single “.mz3z” file. That is a standard ZIP file, which directly can be used with mz3Viewer.
    You even could rename it to the standard extension “.zip” and it will be recognized by mz3Viewer.
  • Ignore the Offline folder; now the new folder “zippedMz3Titles” is your friend 😉
    In that folder all published books can be found in separate zip files, named after your book.

PLEASE:  do not delete the offlinePackage Folder; never ever. Or all (!) your books created in that path will be gone!

Although the folder “offlinePackage” should be renamed now, since it’s intended function changed.
But for backwards compatibility reasons (and to avoid the renaming work and risk) it is kept that way for the time being…

My understanding and questions:

Offline:

  • Users must install mz3Viewer on their system.
  • Only the “.mz3z” file from the “zippedMz3Titles” folder must be saved (anywhere) on the user’s system. No need to unzip.
  • User runs mz3Viewer which finds and displays the flipbook

Online:

  • Only the files in the “onlinePackage” folder, zipped or not for distribution, are given to the webmaster
  • The files are uploaded by FTP to the webpage.

Question:

  • Presumably the “configData” and the “contentData” folders, if needed, are included in the zipped “.mz3z” file for Offline?
    Do they have to be included along with the “onlinePackage” in the Online distribution?
  • It would be convenient to have a zipped Online package provided by the Online PUBLISH option.
    Any reason why not?
  • Do the “_index.html” file and/or the “index_bookname_en.html” have to be renamed to “index.html” for the Online distribution?
  • Saying that “ALL books” can be put in one “_mz3Data” folder seems to be contrary to the recommendation that each version of a book and each different book should occupy a separate folder.
2 Answers
hnuecke answered 10 months ago

Config and Content Data Folders

There is no need to include those in anything related to “final” books. Those are just needed internally to organize all the config data entered and created while you work with mz3Tools.

For “real experts” and those who want to look behind the scene, those config files are accessible and can be opened. There even is a little button for it in the config panels.

You’ll see something like this with the next version:

 

A click gives access to two links:

  • One for the folder with all your “assets” (i.e. images, video files, sound tracks, …)
  • and one for the config folder.

The XML files located in those folders collect everything in preparation for the “CREATE” step, where that content of these files is more or less included “as is” within the final mz3 file.

But you do not have to care about all that. Just in case you need to make any adjustment which is not (yet) supported by mz3Tool, you still have the option to do everything possible and supported by MegaZine3 (as documented in the WIKI).

And btw: Some maintenance jobs might be easier and faster for the experienced users with knowledge of XML structures and XML editors; like substitution of certain parameters over all elements.

As you know: People have different expectations; and we’re trying to help them all 😉

Summary:  You do not need to care about those folders!

Zipped Online Folder

For most people it is easier to just  upload a collection of files to the server as single files, using an FTP program.
They usually want to see what will be uploaded (to double check, for security reasons, …).

If a ZIP (or tar) file would be uploaded to the server, that file had to be unpacked using the server console (e.g. with putty). And most people feel uncomfortable working with a command line utility directly on a server.

Most admins not even would allow doing so 😉

And many cheap offerings for server space (shared servers from any of the big companies in that field) do not allow that neither.

Summary: Who has some knowledge about how to deal with servers, will have no problem with single files. Worst cast those files could be packed on the development system with ease.

index.html and it’s copy with the full book name

What you are using depends on how you want to offer the books.

  • Single book under a specific domain name
    In that case one book is located in a folder; with no other content at that domain level (e.g. no other index.html or index.php files)
    Then the _index.html file should be renamed to index.html, and the book can be accessed via the domain name or any sub path.
    Example: http://www.myDomain.com, or http://www.myDomain.com/books
    Since browsers search by default for an index.html file, that name is optional and does ot have to be entered.
  • If there’s something else already available under that path, the book can be used nevertheless at the same location.
    But then the full index name is needed. That’s why we prepare both: an _index.html and an index_<bookName>.html file; for your convenience.
    To not overwirte a potentially already existing index.html file, the prepared indec file for the book has a leading underscore for differentiation.
    This approach also allows to have several books under the same internet address- But only one book can be the “king” and make use of a standard index.html.
    That one would open if opening just the address of the domain/subdomain.
    All other books are e.g. referenced like: http://www.myDomain.com/books/b1.html,  www.myDomain.com/books/b2.html and http://www.myDomain.com/books/b3.html
    Or whatever name you prefer. You simply rename the book specific index file.
    Advantage: All books share the same MegaZine3 program (and common files), which saves some space. And makes it easier to maintain/update the installation.But as before: Different users have different needs; and we try to offer all options that make life as easy as possible 😉

Recommendation

It is difficult to make a recommendation; because of conflict of interest and different preferences and experiences.

To keep things separate and not getting confused of “what is needed” or “why was my parameter changed”, it is safer to use different folders for different books; at least at the beginning.

If books are combined in the same output folder (the _mz3Data folder), all those books also share some general book parameters.
For some users this is ideal and the expected behaviour, because in that case all books will have the some look & feel.

One use case e.g. is a magazine with e.g. monthly issues. All such issues will be created as different “books”, but should all look alike; i.e. have a common user interface and style.
Then it is best to use a shared output path.

Don Flinn answered 10 months ago

Would it be worthwhile to provide a Distribution Help file in "_mz3Data" so that it is not necessary to refer to the Forum for instructions? Below is my suggestion. Reword as necessary to cover all possible uses.

Distribution Instructions.txt

Offline:

•Users must install mz3Viewer on their system.

•Only the “.mz3z” file from the “zippedMz3Titles” folder must be saved (anywhere) on the user’s system. No need to unzip.

•User runs mz3Viewer which finds and displays the flipbook

Online:

•Only the files in the “onlinePackage” folder are given to the webmaster for FTP uploading to the webpage.

•If the flipbook is to be opened immediately upon accessing the page, http://www.domain.com or http://www.domain.com/page, the file, "_index.html" must be changed to "index.html".

•If the flipbook is to be opened directly from an open webpage, the file, "_index_bookname.html" must be changed to "index_bookname.html". The link to use is http://www.domain.com/page/bookname.html.

hnuecke replied 10 months ago

My experience from the last years is: whatever documentation you offer, it never is used:
– too short
– too long
– wrong place
– confusing …..

We spent a lot of effort for nothing. And such paper must be maintained, what is a big effort especially when things develop/change fast. I think we already wrote and trashed 3+ versions of documentation.
And also included papers with the installation.
We actually attempt to make things so easy and "natural" that no documentation is needed.
What proved to be accepted/helpful is a set of selected videos and examples.
The first videos are available. And once the new version is out, we'll update and/or create new ones.
Then just watching how we use the system will give good and immediate guidance.
And for those who need paper: most videos come with a dedicated blog post.

The complete list of videos can be found in the FAQ, actually as question/answer # 5

But I am open and suggest that we use this thread to collect opinions!

So: **Whoever has an opinion, should either comment or simply "LIKE" your post (or my comment ;-)**

Your Answer

Question Categories: Technical.
Question Tags: Folder structure, Offline, Online, server, and viewer.