How do I create a multi-level xml catalog for mobile devices?
Create a new catalog
First, create catalog file following the guidance in the PDF manuals (Javelin for iOS and Javelin for Android user guides) and/or by copying and editing the test catalog pdfz.org/test.xml, which you can download to your PC or Mac as a zipped copy from here
The xml file should be created using an xml-aware text editor such as Notepad++ . The thing to remember is that if a catalog xml file has another catalog within it, that second catalog is a separate xml file, which also needs to be created and stored on a website somewhere. For example, if you open the test catalog using Notepad++ you will find the following entry which refers to a second level catalog, lasota.xml:
Let us suppose we want to create a catalog for a university, with sub-catalogs/folders for each Faculty and within these, sub-catalogs for each Department and maybe within these Departments, course-related catalogs. To create your xml file, you would need a top level catalog, with entries that refer to (i.e. link to the URLs for) catalogs called faculty1.xml, faculty2.xml etc, and then within the faculty1.xml file you would have a department1.xml etc, and then within department1.xml you would have your department1-100.xml file department1-200.xml etc, and within these catalogs would be the links to the pdf files and drmz files (although such files can be included at higher levels in the ‘tree’, for example to provide information relating to that Faculty or Department). The customer would only need to download the top-level catalog, because having done so, each sub-catalog would automatically download when the catalog item was touched, and then its elements would be available by touching the sub-catalog graphic again once downloaded. New items can be added to such catalogs simply by editing the version of the server where the catalog is held, and then touching the refresh icon (top right corner of each catalog) to re-download the latest version.
Within catalogs there are cover images. The format of these is flexible, but a good rule of thumb is an image about 170×240 (width, height) – i.e. quite small and portrait orientation if possible, but 240×170 will work also or anything close to this arrangement – check you are happy with the results before issuing a catalog. Several points should be noted about cover images (or ‘jackets’):
- cover image files should be in .png format
- catalog files are best with short names and hosted on an http:// website not an https:// website – see also our article on https:// file hosting for mobile device files (basically a catalog file must be hosted on an http:// site not an https:// site but the files themselves can be on an https:// site which includes sites like Dropbox, Google drive etc. – although we do not recommend using Google Drive addresses or similar URLs that are extremely complicated). We can host xml catalogs for you if you wish on our pdfz.org website, so users simply type: pdfz.org/catalogname.xml to download your catalog (the http://www. bit is not required for this to work)
- as with the document files themselves, cover images can be refreshed/downloaded by long-touching the cover of the item of interest, waiting for the pop-up menu to appear, and then asking for the image to be refreshed
- because mobile devices are poor at multi-threading, downloading images and catalog data at the same time is a problem. On Android the Javelin software attempts to retrieve all the cover images for a catalog and these are downloaded as per files using the built-in Android downloader. On iOS, which is not so good at performing this kind of function, cover downloading is manual, as described above, or you can used zipped catalogs (see below)
- bespoke apps, such as Taxbooks (a free Javelin-based app for both iPAD and Android) can have some or all of their catalog images pre-loaded, so no downloading of covers is required
- if no cover image is provided, or is available but not downloaded, the Javelin software will generate a cover using the first page of the document after it is downloaded and opened
- Javelin for mobile devices recognizes zipped xml files, which can contain cover images files, and even document files etc, within the zipped catalog – see the Javelin for Android and Javelin for iOS user guides for details. An example file of this type with 100 covers can be downloaded from http://www.pdfz.org/mpbooks.zip
There is a bespoke app developed by Drumlin Security called “NK institute” on iPAD that has this kind of complex multi-level structure with the top level catalogs pre-loaded – you can download that app for free from the iPAD app store and try it. Each of three separate top level catalogs (English, German and Spanish) have sub-catalogs and within these, lots of documents (100s). The app does not work in quite the same way as the standard versions of Javelin, but is almost the same and provides an indication of the kind of multi-level catalog structures that publishers can create.
Validation and testing
Having created a catalog, then next step is to make sure it works exactly as you expect. The best way to do this is as follows:
(i) give the top level catalog a very short/simple name, using lower case letters, e.g. ucla.xml and then place it on a web server with a short name – if you would like us to host it on our pdfz.org or drmz.net servers then let us know and we can do that for you. All sub-catalogs should also be available online, with their URLs correctly specified as per the lasota.xml example above.
(ii) it is a good idea to check that the structure of your xml file is valid – you can do this using a range of tools, or the free online validator at:
(iii) Then, once you are happy it is correct, download the catalog to Javelin for iOS and to Javelin for Android using the Download icon at the top right of the Javelin mobile app home screen. Then test each level of the catalog, downloading each sub-catalog and opening it to check the next level, including downloading PDF or drmz files contained within the various catalog levels.
Catalogs can be updated at any time, by simply editing the xml file offline and then uploading it to your server in the same location as was previously used. Customers can then see the updated information by refreshing the catalog using the Refresh icon in the top right corner of the catalog, or by downloading the new catalog. This is particularly useful when adding new titles.
If you remove a title from a catalog and the user refreshes it, that title will no longer by visible within it, even if the user has downloaded and authorized the file in question.
Updating of files WITHIN catalogs, e.g. PDF or drmz files, is simply a matter of updating the source files and loading them on to the relevant server from which they are retrieved. Users can then select the cover of the title in question on their mobile device, holding their finger on the cover for a couple of seconds until a pop-up menu appears, and the option Refresh file will appear allowing them automatically to re-download the file in question.
Including Cover Images and Documents
Standard xml catalogs include URL references to cover images and files for downloading. In the case of Android devices Javelin will try and download the cover images automatically, and often these will download OK or if not, a refresh of the catalog will usually complete the process. On iOS devices this is not the case, so for both Android and iOS there is a special facility that supports inclusion of all the bits you might want to download within a single packaged file. This means that a single file is downloaded, which is much more reliable than trying to download many separate files, one for each cover image. The format for these packaged catalog files is quite simple. It must have two parts:
- the xml catalog you have created, as described above, e.g. mycat.xml
- a separate folder/directory called mycat.catdir, containing all the extra files you want – notably cover images as .png files (with names matching those you have specified in the xml file)
Then simply include these two components into a zip file, e.g. mycat.zip, and download this file within the mobile Javelin apps instead of myfile.xml – using this method complete catalogs with cover images and even PDF files will be immediately available. You can even include the zip format catalogs within other catalogs. For example, you might get the customer to download a single top-level catalog file, master.xml, and within this master catalog you can include a series of sub-catalogs which can be zip versions and/or xml catalogs, giving great flexibility for how you configure such files. With this structure the refresh facility within each catalog enables you to update the catalog and contents with no problems, and for the user it is a very quick and simple process to obtain the latest versions of documents and catalogs.