LAST REVISED: 05/03/10 14:22
CPC VIEW
AUTHOR'S GUIDE
VERSION 6.0


1. Serving Images

In general, no CPC View-specific changes are required to serve image documents to CPC View. As with any HTTP document, web site developers and content providers need only insure that the image documents are served with an appropriate MIME type. The client web browser (e.g., Internet Explorer; Netscape) will automatically load CPC View to display documents of the appropriate type.


1.1. MIME Type

For remotely served files, the document type is determined from the MIME type returned by the remote server. Hence, it is necessary to configure your web server to serve images with the appropriate MIME type. CPC View supports any of the MIME types listed in the supported formats section of the User's Guide. In particular, you should configure your Web server to serve files with ".cpi" and ".cpc" extensions as "image/cpi" and with ".tif" or ".tiff" extensions as image/tiff. Consult the documentation for your server to determine how to perform this configuration.

Many web servers come pre-configured to serve the appropriate MIME type for TIFF files. If you are simply serving TIFF files, your web server may not need any configuration.


2. URLs

In the simplest case, a top-level URL to an image document would be specified using the <a> tag, in the exact same manner as for HTML documents. For instance,
<a href=document.cpi>Link Label</a>
provides a link to the image document document.cpi. When the user clicks on the link, the client web browser will automatically load CPC View to display the document.


2.1. Parameters

Additional functionality is available by adding to the URLs information about how to configure the viewer when the link is selected. These options are added to the URL following a '?' or '#' and are separated by semicolons.
thumbnail
Start viewer up in thumbnail view. (Default is page view.)
thumbnail=width,height
Start viewer up in thumbnail view. (Default is page view.) The width and height are used to determine the layout of the thumbnails. If both height and width are zero, a layout is used in which all of the cells fit into the view. If height is zero and width is non-zero, the layout is arranged with width cells in each row, and the cells are sized such that width cells fit within the width of the view. If width is zero and height is non-zero, the layout is arranged with height cells in each column, and the cells are sized such that height cells fit within the height of the view. If both width and height are non-zero, the height parameter is treated as zero. If the dimensions are not specified, they default to zero. (This is identical to the current behavior.)
page=n
Initially view page number n. (Pages are numbered starting from page 1; the default is page number 1.)
toolbar=value
Specifies where the toolbar should be located. Possible values are: top, bottom, left, right, none.
foregroundcolor=value
Set the foreground color for the page to the specified value. Possible values are: white, lightgray, darkgray, black, and arbitrary colors specified using the standard RRGGBB hexadecimal notation. (Default is black.)

The named values (white, lightgray, darkgray, black) are the four tones of gray adjusted by the current desktop color scheme. So, depending on the color scheme you have chosen, black may not equal 000000.

backgroundcolor=value
Set the background color similarly.
scale=value
Set the scale according to the specified value, which is one of: fitheight, fitwidth, fit, or a number treated as a scale factor, e.g., .25 for a four-fold reduction.
rotation=value
Set the rotation according to the specified value, which is one of: 0, 90, 180, 270. These are the number of degrees clockwise to rotate the image.
position=left,top
Set the position of the upper left hand corner of the view to the specified coordinates. The values left and top are numbers between 0 and 1, and are interpreted as the fraction of the way across or down the page of the upper-left corner of the image. Thus, position=.25,.5 would put the upper-left corner at one-quarter of the way from the left of the image and one-half of the way down the image.
precisezoom
Allow precise zooming, instead of the quantized zooming that is the default. Precise zooming allows for slightly better use of screen size when fitting the image to the window and greater accuracy when zooming with the mouse, but may introduce artifacts in scaled images. Use with caution.
controls=value
Specifies which controls should appear in the toolbar. The value is a list of the following items separated by commas or plus signs. (The difference between the separators is described below.) Each of these may be preceded by an exclamation mark (!) to specify eliminating the control from the toolbar. For instance, controls=all,!scrollpad puts in all the controls except for the scroll pad control.

Values can be separated by either commas (",") or plus signs ("+"). The "+" separator can be used to control the order of the widgets on the tool bar. The controls are added in groups defined by the "+" separator. All of the controls in a group to the left of a "+" will be to the left (or above) the controls on the right of the "+". The ordering of controls within a comma-separated group is undefined, so if you care about the order, you should separate all of the controls with "+".

For example, the specification

controls=page+scrollpad+zoom+status causes the tool bar to contain (in order) the page, scrollpad, and zoom controls, and to show status information.
hide=value
Specifies standard commands and features that should be hidden from the viewer user interface. The value parameter is a comma-separated list composed from the following items:

For example, the specification hide=save,configTB would hide the save commands and remove the user's ability to re-configure the toolbars.

Note: Use of the URL parameters is not a secure method of eliminating viewer capabilities. In most environments, the user can simply re-open the image file without the URL parameter, thereby acquiring the hidden capabilities.

strict
The viewer stores the user's preferences for the view and page number parameters on a URL by URL basis, and for all other parameters on an overall basis. The stored URL by URL preferences override the ones specified with the # specification by default. The strict parameter causes the # specification to override the user's preferences.

A side effect is that user preference changes made to a view of a "strict" url are not saved.



3. Embedding

In addition to using the plug-in to view documents that take up a full frame or window, documents can also be embedded as subimages in an HTML documents using the <embed> tag. For instance, the small image at left was inserted with the following HTML: <embed src="document.cpi" strict width=200 height=260 type="image/cpi" controls="rmousemenu" scale=fitwidth toolbar=none thumbnail align=left> Note the use of the "thumbnail" and "toolbar" parameters to affect the appearance of the embedded image. All parameters listed in the section above can be used in this way.

At the right is another example that puts up a particular page from the document above. The following HTML was used:

<embed src="document.cpi" strict width=156 height=220 scale=fitwidth type="image/cpi" page=3 toolbar=none controls="rmousemenu" align=right>

These embedded images are "live"; all the standard user interface techniques work as usual. (Go ahead. Try it!)


4. Meta-Documents

A meta-document is a composite image document comprising one or more image document fragments. Each fragment consists of a contiguous range of pages from within some underlying image document. The viewer treats a meta-document exactly as if it were a single image document containing the concatenation of all of the pages contained in all of the fragments.

Note: Meta-documents require version 5.6 (or later) of CPC View, CPC Lite, or CPC View ax.


4.1. XML Description

A meta-document is described by an XML file. Currently, there is no DTD. To satisfy the well-formedness requirements for DTD-less XML, the entire meta-document should be enclosed in a <metadoc> block:
<?xml version="1.0" ?>
<metadoc>
    list of meta-document fragments
</metadoc>
Note: The viewer does not check whether the XML is well-formed. That is, the viewer will accept XML files that do not enclose the fragments in a <metadoc> block.

4.1.1. Tag: frag

A fragment is described by the empty <frag> tag. The tag has one required attribute: the URL of the underlying image document (url). The tag has one optional attribute: the number of pages to include from the underlying image document (numpages).
<frag url="http://foobar.com/doc1.cpc" 
    numpages="3" />
The url may be specified as either an absolute or a relative URL. If a relative URL is specified, it is resolved against the base URL of the meta-document.

Note: The use of relative URLs requires version 6.0.5 (or later) of the viewer. Earlier versions of the viewer support only absolute URLs.

The URL can specify any of the following transports: http, https, ftp, and file. The underlying image document pointed to by url can be in any file format supported by the viewer, with the exception that it can not itself be a meta-document or an annotation file that links to its underlying image file.

numpages specifies the number of pages to include from the underlying image document. If numpages is omitted (or zero), the fragment contains all of the pages in the underlying image document. If numpages exceeds the actual number of pages in the underlying image document, the viewer displays the extra pages with errors.

Note: Prior to version 6.5.6, the numpages attribute was required to have a non-zero value.

The order of the <frag> tags is significant; it defines the order that the pages appear in the meta-document.


4.2. Example

Consider the following XML meta-document description:
<?xml version="1.0" ?> 
<metadoc>
    <frag url="file://e:/F300.cpc" 
      numpages="2" />
    <frag url="https://fb.com/G2.tiff" 
      numpages="3" />
    <frag url="http://fb.com/G2.cpc" 
      numpages="1" />
    <frag url="http://fb.com/A1.cals" 
      numpages="8" /> 
</metadoc>

This example describes a 14 page meta-document with the following structure:

Meta-document pages Fragment image document Fragment pages
1-2 e:/F300.cpc (local file) 1-2
3-5 https://fb.com/G2.tiff 1-3
6 http://fb.com/G2.cpc 1
7-14 http://fb.com/A1.tiff 1-8


5. Batch Printing

A batch print job is a list of one or more image documents that are to be printed. When a batch print job is opened, the viewer queries the user for the print parameters to apply to the job. The specified print parameters are applied to each of the documents in the job. Once the user has specified the print parameters, the viewer automatically downloads and prints each document without further user interaction.

As with normal printing operations, while the batch job is printing, a status window displays the current status of the job. The status window also contains a Cancel button that can be used to terminate the batch print job.

If an error occurs during a print job, the user is queried as to whether or not the remaining documents in the job should be printed.

The viewer does not display the documents in the print job. It merely prints them.

Note: Batch print jobs require version 5.7 (or later) of CPC View, CPC Lite, or CPC View ax. To simplify the detection of clients with older versions of the viewer, a new mime-type is supported, application/cpi-job.


5.1. XML Description

A batch print job is described by an XML file. Currently, there is no DTD.

5.1.1. Tag: batchprint

The entire batch print job must be enclosed in a <batchprint> block:
<?xml version="1.0" ?>
<batchprint oncomplete="javascript:close()">
    list of documents to print
 </batchprint>
The tag accepts an optional oncomplete attribute. If specified, it is the URL to open in the browser on completion of the batch print operation. Note that the oncomplete can be a javascript url, to allow for the execution of completion scripts on the page that embeds the print job.

5.1.2. Tag: doc

Each document in the job is described by the empty <doc> tag. The order of the <doc> tags is significant; it defines the order in which the documents are printed.
<doc url="http://foobar.com/doc1.cpc" 
  title="Hello, World"
  annServer="as.cgi?ID=foobar"
 />
The tag requires one attribute: the URL of the underlying image document (url). The url must be specified as an absolute url; relative urls are not accepted. The url can specify any of the following transports: http, https, ftp, and file. The underlying image document pointed to by url can be in any file format supported by the viewer, with the exception that it can not itself be a batch print job or an annotation file that links to its underlying image file.

The tag accepts an optional title attribute. If specified, it is used as the title for the document. If not specified, the url of the document is used as the title.

Requires version 6.0.4 or later: The tag accepts an optional annServer attribute, specifying the URL of the annotation server for this document. Annotations for this document will be loaded from the specified URL. If a relative URL is specified, it is resolved against the URL of this document (as specified in the url attribute of the tag).


5.2. Example

Consider the following XML batch print job description:
<?xml version="1.0" ?>
<batchprint 
 oncomplete="http://fb.com/done.cgi">
  <doc url="file://e:/F300.tiff" 
   title="Local Test" />
  <doc url="http://fb.com/G2.cpc" /> 
  <doc url="https://fb.com/G2.tiff" 
   title="Gilman (https)" />
</batchprint>

This example describes a 3 document batch print job. The following actions occur when the job is opened:



6. Batch Downloading

A batch download job is a list of one or more documents that are to be downloaded. When a batch download job is opened, the viewer queries the user for the folder in which to save the downloaded documents. The viewer then automatically downloads each of the listed documents into the specified folder without further user interaction.

If any of the listed documents already exist in the specified folder, the user is queried as to whether the existing documents should be skipped.

While the batch job is downloading, a status window displays the current status of the job. The status window also contains a Cancel button that can be used to terminate the batch download job.

If an error occurs during a download job, the user is queried as to whether or not the remaining documents in the job should be downloaded.

The viewer does not display the documents in the download job. It merely downloads them.

Note: Batch print jobs require version 5.8 (or later) of CPC View, CPC Lite, or CPC View ax. To simplify the detection of clients with older versions of the viewer, a new mime-type is supported, application/cpi-download.

The documents to download need not be image documents. The viewer downloads exact copies of the listed documents and is ignorant of the underlying file format.


6.1. XML Description

A batch download job is described by an XML file. Currently, there is no DTD.

6.1.1. Tag: batchdownload

The entire batch download job must be enclosed in a <batchdownload> block:
<?xml version="1.0" ?>
<batchdownload oncomplete="javascript:close()">
    list of documents to download
</batchdownload>
The tag accepts an optional oncomplete attribute. If specified, it is the URL to open in the browser on completion of the batch download operation. Note that the oncomplete can be a javascript url, to allow for the execution of completion scripts on the page that embeds the download job.

6.1.2. Tag: doc

Each document in the job is described by the empty <doc> tag. The order of the <doc> tags is significant; it defines the order in which the documents are downloaded.
<doc url="http://foobar.com/doc1.cpc" 
  title="Hello, World" 
  filename="file1.download" />
The tag requires one attribute: the URL of the underlying document (url). The url must be specified as an absolute url; relative urls are not accepted. The url can specify any of the following transports: http, https, ftp, and file.

The tag accepts an optional filename attribute. If specified, it is used as the filename for the downloaded document. If not specified, the last component of the url is used as the filename.

The tag accepts an optional title attribute. If specified, it is used as the title for the document. If not specified, the url of the document is used as the title. The title of the current document is displayed in the download status window.


6.2. Example

Consider the following XML batch download job description:
<?xml version="1.0" ?>
<batchdownload 
 oncomplete="http://fb.com/done.cgi">
  <doc url="file://e:/F300.tiff" />
  <doc url="http://fb.com/G2.cpc" />
  <doc url="https://fb.com/G2.txt" 
    title="Gilman (text)" filename="foo.txt"/>
</batchdownload>

This example describes a 3 document batch download job. The following actions occur when the job is opened:


1998-2003 Cartesian Products, Inc. Contact Cartesian