How to package an HPub

Pieter Claerhout edited this page Apr 16, 2015 · 11 revisions

Preparing the Publication

First of all, a HPub publication is like a HTML5 microsite. You should be able to see it in a standard browser and test it in Mobile Safari (it will miss the pagination and Baker features of course, but it should work). This is important because it means that if your application shows and works correctly in Mobile Safari, then it's almost sure it will work in Baker.

To prepare a publication just write it like a microsite, having a HTML file for each page inside Baker and have them ordered sequentially. Prepare also an index.html file, that will be visualized inside Baker when you double-tap the screen. Ideally, it should be just a small stripe (horizontal or vertical) in order to not cover the entire screen when it shows up.

 

Package

When your publication is ready and tested in Mobile Safari, you have to wrap it up into a nice package to include it in Baker.

  1. Create a folder (e.g. a-study-in-scarlet) and copy all your publication files into that. All the HTML files and book assets must be in the folder, no file outside the folder will be seen by Baker. Subdirectories are ok, as in any microsite.
  2. Create a file called book.json, with all the parameters required for Baker to display your book correctly. This file is known as a manifest and it must conform to the HPub standard. To know how to write a manifest and see some examples, [read here](hpub specification).
  3. Validate the book.json file with JSONLint to make sure it's correct.
  4. (Optional) If you need a more advanced customization, there are also some extra parameters specific for Baker that you can find [here](Book.json Baker extension parameters).

After these simple steps are completed, your publication folder will contain an upacked HPub. Now there are two alternatives, depending on the kind of app you are building. See Newsstand vs Standalone publications in Baker 4.0 if you're not sure which one applies to you.

Newsstand App

Compress all the files inside the folder to a zip file. Be careful: you have to select all the files inside the folder and zip them, you should not zip the folder.

You can easily check the contents of your archive on the command line with the unzip tool and the -l flag. Here is an example:

$ unzip -l a-study-in-scarlet.hpub
Archive:  a-study-in-scarlet.hpub
  Length     Date   Time    Name
 --------    ----   ----    ----
    89822  11-22-12 18:21   a-study-in-scarlet.png
      998  11-20-12 00:14   Book Cover.html
     2199  11-20-12 00:14   Book Index.html
     1081  12-10-12 22:08   book.json
 ...

If you see a list of files, everything is ok. If you see that all files are inside the same folder, you need to regenerate the zip file and to make sure you're not compressing the parent folder.

Note that, if you try to unpack the file with tools such as the Mac OS X Archive Utility, a parent folder will always be created for you, whether it was originally in the hpub or not. This means you can't trust these tools to tell you whether your hpub is correct or not.

Standalone App

Just copy the folder you created to the books/ folder in Baker. Make sure you have a folder containing all your files. The structure should look similar to the on in the following example:

books
└── a-study-in-scarlet
    ├── Book Cover.html
    ├── Book Index.html
    ├── a-study-in-scarlet.png
    ├── book.json
    ...

... and one more thing

As you may have noticed, the HPub package is just a list of HTML pages. This means that, once you make sure all the pages are linked to each other, you can publish it on the web without any additional work and your users will be able to view it in a standard browser.