Parameters for document printing, viewing and conversion


NOTE: XXX marker is used to generalize document formats such as PDF, TIF, DOC, RTF etc. Replacing XXX marker with a document type such as "PDF" will provide a real presentation for the examples.

Here is the list of parameters and details about where and how to use them.

DOCUMENT

Used for viewing a document in the viewer. A string pointing to an existing document or an URL that can dynamically generate a document for viewing.

Examples
  • Static URL
    [http://www.activetree.com/silent_print_XXX_from_browser/demo/sample_XXX/sample1.XXX]
  • Local file URL (Windows)
    [file:/c:/demo/sample_XXX/sample1.XXX]
  • Dynamic URL
    [http://www.activetree.com/silent_print_report_from_browser/doc_generator.jsp]
  • If the document is generated dynamically from a server program may require parameters. This is how one can add the parameters and values using the standard URL systax.

    [http://www.myhost.com/silent_print_report_from_browser/dynamic_XXX.jsp?param1=value1&param2=value2...&paramN=valueN]

    DOC_LIST

  • This is either a String or java.util.List containing byte[] elements.
  • Typically used for printing and converting documents.
  • Format: [doc1-][doc-2][doc-3]...[doc-N]
  • DOC_LIST examples

  • Two existing documents
    [file:/c:/test/docs/sample1.XXX][http://www.activetree.com/silent_print_XXX_from_browser/demo/sample_XXX/sample4.XXX]
  • Dynamically generated documents
    [http://www.activetree.com/demo/sjreport/doc_generator.jsp][http://www.activetree.com/demo/sjreport/ReportGenerationDemo1.jsp]
  • Mix of dynamic and existing documents
    [file:/c:/test/docs/sample1.XXX][http://www.activetree.com/demo/sjreport/PdfJSPDemo1.jsp]
  • DOC_LIST examples for document byte[] content

    For byte[] contents this argument has to be an object of java.util.List containing byte[] elements. For complete code sample, look for examples in the downloaded server archive.

    PASSWORD

    Only applicable for those password protected documents. You may or may not pass a value for this parameter. If the document is NOT a password protected a value passed for it will be ignored.

    NOTE: While processing multiple documents using DOC_LIST only one password may be set. Password for each document if different, you may set one document to the DOC_LIST and therefore process one document at a time.

    URL_AUTH_ID

    The document URL (or the URL dynamically producing the document) might be password protected in the web server. Web server therefore requires a access USER NAME and PASSWORD (Note: this is different from document PASSWORD).

    Following parameters are used for accessing the password protected URL:
    URL_AUTH_ID - user name (or ID) for the protected URL along with the URL_AUTH_PASSWORD parameter.

    URL_AUTH_PASSWORD

    URL_AUTH_PASSWORD - user password for the protected URL, used when a URL_AUTH_ID is required for accessing an URL.

    JOB_NAME

    Job name is controlled using JOB_NAME name parameter value of which is a string.

    PAGE_SCALING

    This is controlled by PAGE_SCALING parameter. Document page area may be different than the media printable area. Therefore it is important to set this flag in order to get the desired output. Following are the accepted values:
    - NONE if applied page content is not scaled to fit to the media size and orientation.
    - FIT_TO_PRINTABLE_AREA is used for page content to always get scaled to fit to the media printable area. If the printable area is smaller than the page content it will shrink the page content to fit to the printable area. On the other hand if the media printable area is larger than the page content it will expand the contet to fit to the printable area.
    - SHRINK_TO_PRINTABLE_AREA is same as FIT_TO_PRINTABLE_AREA except that if the media printable area is larger than the page content it will not expand the page content to fit to the printable area. It can be used only for larger content to the output media by shrinking it.

    Default value is set to FIT_TO_PRINTABLE_AREA.

    AUTO_ROTATE_AND_CENTER

    This is a boolean "true" or "false" flag used to indicate whether or not to automatically rotate and center the document page content to the media printable area. A media printable area may not be of exact match with the document page size. Even if the size of the media is same the orientation may be different. This flag therefore ensures you to automatically re-orient and center the content to the media printable area if this flag is set to "true". This flag works with the PAGE_SCALING parameter. Value "false" for this flag only effective if the value of PAGE_SCALING parameter is NONE. All other value of page scaling will have no effect on this flag and a value "true" will be used (even if you have set it to "false").

    Default value is set to true.

    PAPER

    This parameter is used for setting a media size of format "(widthInPixel, heightInPixel)" for no margins are required for output. For an NA_LETTER paper it will be PAPER=(612,792) where paper width is 612 pixels and height is 792 pixels.

    If margins are required around the pages it will be of this format "(top, left, bottom, right, width, height)" and all are in pixels. An example media size "(72, 72, 72, 72, 612, 792)" - where top, left, bottom and right margins each is of 72 pixels and last two values is the total width and heigh of the media.

    AUTO_MATCH_PAPER

    AUTO_MATCH_PAPER can be set to "true" or "false". If set to true it will take each page size and find a matched paper size looking into ISO paper size list. If found it will use that paper size, otherwise, it will use the paper size you specify with the PAPER flag. If page size is not matched for auto-paper size match and you have not specified a PAPER size it will use a default paper size. We suggest you provide a default paper size using the PAPER parameter.

    PRINTER_NAME

    There are no flag to print to a default printer. Not setting this parameter results documents to be printed to the default printer. However, if you want to print to a named printer set PRINTER_NAME to a string value and optionally set PRINTER_NAME_SUBSTRING_MATCH parameter to either true or false.

    PRINTER_NAME

    PRINTER_NAME and PRINTER_NAME_SUBSTRING_MATCH parameters are used in combination to print to a particular printer identified by a name. PRINTER_NAME value is either full name of the printer or a substring of it. On the other hand PRINTER_NAME_SUBSTRING_MATCH tells whether or not API should look for a printer that is of exact match (value if false) with the string in PRINTER_NAME or API should try to find a printer taking the PRINTER_NAME value and do a substring match (value if true) with all the available printers. If it do not find a matched printer using these two parameters it will print to default printer.

    PRINTER_NAME_SUBSTRING_MATCH

    Whether or not to do a substring match for finding a printer during printer search based on printer name.

    In this example PRINTER_NAME=HP LaserJet 4200 PCL&PRINTER_NAME_SUBSTRING_MATCH=false used to indicate that an exact match should be performed for finding a printer named "HP LaserJet 4200 PCL". When PRINTER_NAME_SUBSTRING_MATCH=true the first printer found using a substring match will be used even there are other printer name might match this substring.

    PRINT_QUALITY

    This parameter is used for setting the printout quality. Possible values are High, Normal and Draft. For laser printers this parameter may not make any difference in output quality. It is important for other kinds of printer such as a thermal printer.

    SIDE_TO_PRINT

    This parameter is used for this purpose. Possible values are ONE_SIDED, DUPLEX, TUMBLE, TWO_SIDED_LONG_EDGE, or TWO_SIDED_SHORT_EDGE. Actual outcome for this parameter will depend on whether or not the printer supports it. In this example a value of DUPLEX is used with the expectation that the output be printed on both sides of the pages. Duplex mode saves paper and is recommended if your printer support it.

    IS_USE_PRINTER_MARGINS

    This parameter is used for validating the paper size with the printer. A printer might be configured to keep certain amount of margins around the page. Document content if printed ignoring this margins it might produce the content near the boundary of the paper is cut off. Set this flag to true if you want to use the printer margins, otherwise, set this flag to false. Default value is true.

    COPIES

    COPIES parameter takes an integer number as the number of copies to be printed. Default value is 1 copy. This example is using COPIES=2 for printing 2 copies.

    COLLATE_COPIES

    This parameter takes boolean true if you want the copies to be collated false otherwise. This is used when printing multiple copies. Default value for this parameter is true.

    SINGLE_PRINT_JOB

    Use boolean true if you want all the DOC_LIST documents be printed as one print job, false otherwise. This is used when printing multiple documents. One print job will cause the API to put together pages from all of the documents and print them together as one document. If this flag it set to false it will print each document as one print job post fixed with a number.

    SHOW_PRINT_DIALOG

    This can be set to true if you want to select all of these printing parameters from a dialog window, false otherwise. This flag makes the printing non-silent since it will wait for user input before printing. Moreover it will ignore all the parameter values and will use what user select from this dialog. Only parameter API will use from the URL parameters is the PASSWORD value.

    SHOW_PRINT_ERROR_DIALOG

    NOTE: This parameter typically used for browser based applications.

    This parameter if true shows a dialog displaying any kind of printing error if any, false otherwise. Error dialog is shown only if there are printing errors. Default value is true. This example set this flag to false so no dialogs are shown. (See DEBUG parameter later in this tutorial to trace the printing debug messages).

    STATUS_UPDATE_ENABLED

    NOTE: This parameter typically used for browser based applications.

    It is used for silent printing from browser based applications and may be ignored when used for standalone applications.

    This parameter if true it shows messages in the browser window while job is being processed. Messages such as docs to print, total number of pages, printer it is printing to etc. are displayed when printing is in progress. Default value is true. When you run without this parameter it will display messages in the browser window. Set this to false if do not want to see any messages in the browser window.

    DEBUG

    This parameter if true it shows API debug messages in the browser Java Console or in application console while printing is in progress. This is helpful for the end user as well as developers when trying to print and report a problem if any. This example is using a value false for not recording any debug messages. Default value is set to true.

    SERVER_CALL_BACK_URL

    NOTE: This parameter typically used for browser based applications.

    SERVER_CALL_BACK_URL - A HREF value (i.e. URL) may be provided for this parameter that will be called at run time. All parameters is going to be made available to the server URL for knowing the document and allow access to it by way of providing all security and other information it might need for its opening. Callback program may simply deny access to this program by not providing the access information or simply setting an empty DOCUMENT or DOC_LIST content to the attribute map it replies back for client.

    Examples:
    SERVER_CALL_BACK_URL=http://www.activetree.com/silent_print_XXX_from_browser/demo/server.jsp

    ON_SUCCESS_SHOW_PAGE

    NOTE: This parameter typically used for browser based applications.

    An web URL may be set using this parameter for showing a page after completion of the job.

    Examples:
    ON_SUCCESS_SHOW_PAGE=http://www.activetree.com/silent_print_XXX_from_browser/demo/success.jsp

    ON_SUCCESS_PAGE_TARGET

    NOTE: This parameter typically used for browser based applications.

    Possible values are "_blank", "self" and a named window; e.g. "myWindow"

    Examples (show success page in new window; "_blank"):
    ON_SUCCESS_SHOW_PAGE=http://www.activetree.com/silent_print_XXX_from_browser/demo/success.jsp&ON_SUCCESS_PAGE_TARGET=_blank

    ON_FAILURE_SHOW_PAGE

    NOTE: This parameter typically used for browser based applications.

    Similar to the ON_SUCCESS_SHOW_PAGE parameter except that this parameter is used for showing a page if job failed.

    Examples:
    ON_FAILURE_SHOW_PAGE=http://www.activetree.com/silent_print_XXX_from_browser/demo/failure.jsp

    ON_SUCCESS_PAGE_TARGET

    NOTE: This parameter typically used for browser based applications.

    This target value used with ON_FAILURE_SHOW_PAGE disussed above.

    Examples (show failure page in new window; "_blank"):
    ON_FAILURE_SHOW_PAGE=http://www.activetree.com/silent_print_XXX_from_browser/demo/failure.jsp&ON_FAILURE_PAGE_TARGET=_blank

    IS_SHOW_PRINT_PREVIEW

    NOTE: This parameter typically used for browser based applications.

    When silent printiong from browser it may be necessary to preview the document pages before submitting the job for printing or conversion. This parameter is set to true for showing the pages in the viewer.

    This parameter is used along with VIEWER_PAGE and VIEWER_CONTROLS parameters.

    VIEWER_PAGE

    NOTE: This parameter typically used for browser based applications.

    If IS_SHOW_PRINT_PREVIEW is set to true VIEWER_PAGE is used for identifying the document viewer URL so that the document may be opened in the viewer.

    VIEWER_CONTROLS

    NOTE: This parameter typically used for browser based applications.

    This parameter has direct relationship with the VIEWER_PAGE parameter. If VIEWER_PAGE is set along with IS_SHOW_PRINT_PREVIEW to true this parameter tells what are preview controls may be shown in the viewer for user to comfortably browse the pages.

    Examples:

    IS_SHOW_PRINT_PREVIEW=true&VIEWER_PAGE=view_XXX.jsp&VIEWER_CONTROLS=SILENT_PRINT_BUTTON, SILENT_PRINT_BUTTON, FIRST_PAGE_BUTTON, NEXT_PAGE_BUTTON, PREVIOUS_PAGE_BUTTON, LAST_PAGE_BUTTON, GO_TO_A_PAGE_FIELD, TOTAL_PAGE_LABEL


    Contact Us

    Copyright © Activetree, Inc. All rights reserved.
    Web: http://www.activetree.com
    Email: sales@activetree.com
    Tel: +1 408-791-8036 Fax: +1 408-716-8450