Creating An Image Viewer in One Step
Frequently Asked Questions

Stephen P. Morse , San Francisco

1. What is the purpose of this tool and who is it intended for?

This tool is intended for anyone who has a collection of sequential images and wants to make the images viewable from the web.  It enables you to easily generate a viewer for the images.

There are no fees or licensing involved.  It is all being offered free of charge.  You can use it and modify it in any way you like.  At the bottom of the viewer that it generates is a reference to this tool.  You are free to remove that reference if you desire.

I am not offering a service to host your viewer for you.  You'll need to have your own access to a server on which to place the generated viewer files.  There are some free and many low-cost (around $5/mo) servers out there for you to chose from

2. Must the viewer be run from a website?

If you want to allow other people to view the images, you will need to put the images as well as the viewer on a website.  But if you just want it for your private use, you can put the images on your own computer along with the viewer.  All features of the viewer will work in this local environment except for the DOWNLOAD button (see question 8).

3. What files does the viewer consist of and how are they generated?

The viewer consists of the following files, all of which you must place in a common folder:

viewer.js -- This is a table consisting of the values specific to your particular set of images.  After you fill in all the fields on the form, you click on the button that says "Create viewer.js file."  That will display the contents of viewer.js in the box below it.

viewer.html, viewerframe.html, downloadimage.php -- These files contain the code for the viewer.  The code is the same for all viewers and not specific to your particular images.  You can obtain the contents of these files by clicking on appropriate "Show" button ("Show viewer.html", "Show viewerframe.html", or "Show downloadimage.php").

As the contents of each of the above files are displayed, it is up to you to create a file of the indicated name and to upload that file to your website.

Note that downloadimage.php cannot be executed from your computer but must be placed on a website.  If you do not have a website and wish to run the viewer directly from your hard drive, you can put the other three viewer files on your drive and simply not bother with the downloadimage.php file.  In that case the only feature you will lose is the DOWNLOAD button (see question 8).

4. I thought this tool displayed a set of images.  So why is there a field asking for the number of books?

If all you have is one set of images, you can consider those images to be the pages of one book.  So you would enter "1" in the "number of books" field.  But if you have several image collections, you might want those to be treated as separate books and displayed separately.  The viewer that this tool generates will give your user the choice to select which "book" he wants to display.

5. What is the meaning of the different fields that are presented for each book?

Book Name:

This is an arbitrary name that you pick for each book.  The book names that you choose will appear in a dropdown list in the viewer, allowing your user to select which book he wants to view.

Book Path:

The path is the location of the folder that contains the set of images (pages) for the book.  It can be an absolute address or an address relative to where your viewer is located.

For example, suppose your images are located at,, etc.  In this case the absolute path would be "" (without the quotes of course).  Let's assume that you are going to place your resulting viewer in  In that case you can use a relative path, namely "../images" where ".." means one-level-up.

If your images and your viewer are on different website, you have no choice but to use an absolute address for the path.  If they are on the same website, you can use either.  But in that case a relative address is preferable because it allows you to have a DOWNLOAD button (see question 8).

Page Padding:

The viewer needs to be able to figure out the name of the image file from the image number.  To do so, it needs to know how the image number is included in the image name.

You might have image names like image8.jpg, image9.jpg, image10.jpg, etc.  In that case there is no padding -- the image number is included in the image name as is.  This means that some names are longer than others because they have more digits in the number part of the name.

Alternatively, you might have decided to keep all image names the same length by padding the image number with the appropriate number of zeroes on the left.  For example, you might have image names like image08.jpg, image09.jpg, image10.jpg, etc.  This allows for up to 99 images.  In this case you would select "Padded to 2 digits" in the Page Padding field.  If you have more than 99 images, you will need to pad it with more digits.

Page Prefix, Page Suffix:

In order for the viewer to figure out the name of the image, it needs to know if anything goes before or after the image number.  If the images have names like image35.jpg, the Page Prefix is "image" (without the quotes) and the Page Suffix is ".jpg".

Lowest Main Page, Highest Main Page:

Your image names need to have sequential numbers, but those numbers need not start with 1.  The "Lowest Main Page" field specifies that number of the first image and the "Highest Main Page" field specifies the number of the last image.  For example, if your image names go from image11.jpg to image 25.jpg, you would enter 11 in the "Lowest Main Page" field and 25 in the "Highest Main Page" field.

Origin for Main Page:  This is the first page number that you would like shown in the list of pages in the viewer.  For example, your images might have names going from image11.jpg to image25.jpg, but you want these to appear in the viewer's list of pages as going from 1 to 15.  In that case you would enter a 1 in the "Origin for Main Page" field.  On the other hand, if you do want the list of pages to go from 11 to 25, you would enter 11 in the "Origin for Main Page" field.

Lowest Preface Page, Highest Preface Page, Origin for Preface Page:

If your images do indeed correspond to pages in a book, the book might have some front-matter (preface pages) preceding page 1.  For example, it might have a cover page, a title page, a table-of-contents page, etc.  These pages are often numbered with Roman numerals.  If you identify these preface pages using these three fields, the viewer can handle them separately and will  present them as Roman numerals in the list of pages.

6. How can I make changes to a viewer that I developed previously?

Copy the viewer.js file that you previously created into the box that says "viewer.js" and then press the "Restore from viewer.js file" button.  That will cause the all the fields to be pre-filled with the values that they had when you last created the viewer.

7. The resulting viewer has a PRINTER FRIENDLY button.  What is that for?

The viewer fetches each image and displays it, but it does it in such a way that the browser's normal print facility cannot print the image.  The users of your viewer will probably want some way to print the images.  They can accomplish that by clicking on the PRINTER FRIENDLY  button.  Doing so will open a new window that contains only the image and no other parts of the viewer.  From that window the users can use the browser's normal print facility to print the image.  They can also use the browser's normal save facility to save the image to their hard disk.

8. The resulting viewer has a DOWNLOAD button.  What is that for?

The users of your viewer might want to download the image being viewed to their own hard disk.  They could be accomplished using the PRINTER FRIENDLY button as described in question 6.  But the pop-up blockers in some mis-guided browsers might be set to prevent the viewer from opening a new window.  The DOWNLOAD button allows the users to download the image directly from the viewer without having to first open the image in a separate window.

There are two limitations to this download facility.  One is that it will not work if your user is running the viewer from his hard disk instead of from a website.  The other is that it can download images only if they are on the same website as the viewer and the book path has been specified as a relative address (see question 5).  If the book path has been specified as an absolute address, the DOWNLOAD button will not even appear in the viewer.

9. How do you link to the viewer that this tool creates?

Let's assume that you upload the files of the viewer into  In that case, your users can access the viewer by going to

10. Can the viewer be forced to start at a particular page in a particular book?

Yes.  Suppose that the name of the book you want to start with (as specified in the Book Name field of this tool) is "Smiths in America" and that the page you want to start with (as shown in the list of pages in the viewer) is 25.  In this case you would access the viewer by going to http://yourserver/tools/viewer.html?bookname=Smiths in America&pagenumber=25.  If the name of the book contains an ampersand character ("&"), you'll need to replace that with %26 in the link.  For example, if the book name is Spain & Portugal, the link would be http://yourserver/tools/viewer.html?bookname="Spain %26 Portugal&pagenumber=25.

You might want to make use of this when you have a search application and the results it generates correspond to entries in the book.  For example, when searching for John Smith, your search application might report that he is found on page 25 in "Smiths in America".  That search application could display more than just the book name and page number -- it could also give the link to the viewer starting at the appropriate page and book.

For a tool that helps you generate a search application, see my <a href="../create/create.html">One-Step Search Application generator</a>.

11. Can you show an example?

Click on the button that says "Sample Values".  That will fill some actual values into the boxes.  Then click on the button that says "Create viewer.js file".   That will display the viewer.js file corresponding to the values that were entered into the boxes.  Finally click on the button that says "Sample Viewer".  That will bring up a working viewer that was generated from these sample values.

-- Steve Morse