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 http://yourserver.com/images/image1.jpg,
http://yourserver.com/images/image2.jpg, etc. In this case the absolute
path would be "http://yourserver.com/images" (without the quotes of course).
Let's assume that you are going to place your resulting viewer in
http://yourserver.com/tools/viewer.html. 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 http://yourserver.com/tools. In that case, your users can access the viewer by going to http://yourserver.com/tools/viewer.html.
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
One-Step Search Application generator.
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