TemplatePrinter

Provides a print template with access to page setup and printer settings and control over print jobs initiated from the template.

Remarks

The methods of TEMPLATEPRINTER give a print template control over the start and end of print jobs (startDoc and stopDoc), control over the printing of each individual page in a print job (printPage), and control over the display of printing dialog boxes (showPageSetupDialog and showPrintDialog). The properties of TEMPLATEPRINTER enable a print template to set or retrieve the page setup settings and current print job settings. For instance, a print template might set or retrieve pageWidth and pageHeight for page setup, or pageTo and pageFrom to determine the page range to print.

A TEMPLATEPRINTER element is intended for use when building a print template. Its functionality is disabled when it is used outside a print template.

This element must occur once and only once in a print template if the template is to support printing.

For security reasons, the TEMPLATEPRINTER element is enabled only when embedded in a print template; otherwise, this element is disabled. For more information, please review Beyond Print Preview: Print Customization for Internet Explorer 5.5.

When using the TEMPLATEPRINTER element, you must prefix it with an XML namespace. Declare the namespace by using the IMPORT processing instruction. For example, the namespace "IE" can be declared using the following statement:

<?import implementation="#default" namespace="IE">

The TEMPLATEPRINTER element syntax to use with this namespace is <IE:TEMPLATEPRINTER ... />.

The TEMPLATEPRINTER element is an unscoped element; that is, it does not have a closing tag. It must have a forward slash (/) before its closing bracket.

In some cases—usually when the print or print preview dialog box is displayed—the content source document has time to load before printing starts. In other cases, usually when there is no user prompt prior to printing, a print template must be designed to wait for the document to load before beginning a print job. Accomplish this by setting an onreadystatechange event handler on the contentDocument that checks the document's readyState property to see when it equals "complete." This handler is not always necessary, so a template should only set it when the property is not "complete" at the start of a print job.

**Security Warning:  **Writing an Microsoft ActiveX control, binary behavior, or other binary object for use on a Web page that can load an unspecified print template can compromise the security of your application. Such a control could be appropriated to load insecure or malicious print templates. Write your control to load only specific, pre-defined templates. For more information, please review Beyond Print Preview: Print Customization for Internet Explorer 5.5 and Designing Secure ActiveX Controls.

Examples

Click below to download a sample application that demonstrates the print and print preview features of Internet Explorer. The application includes eight templates that increase in complexity from minimal functionality to those that include user interface elements. You can also use the application to test templates of your own design. You must download the sample application to your own computer to run it.

Download Print and Preview Template Test Application

The following script block and the opening lines of the BODY element are taken from a print template. They show the minimum features necessary to provide printing support in a print template. The Init function is an event handler attached to the print template's body element for the onload event. "Layout1" is the id for the first LAYOUTRECT of the print template. "PageX," where X is a positive integer, is the id format for the DEVICERECTs in the print template.

<SCRIPT language="JScript">
<?import implementation="#default" namespace="IE">
function Init()
{
    switch (dialogArguments.__IE_PrintType)
    {
        case "Prompt":
            if (Printer.showPrintDialog()) 
                DoPrint();
            break;
        case "NoPrompt":
            DoPrint();
            break;
        case "Preview":
        default:
            break;
    }
}

function DoPrint()
{
    if (Layout1.contentDocument.readyState == "complete")
    {
        // This block is called when printing with user prompt
        // because the Print and Preview dialog boxes give time for
        // the content document to complete loading
        PrintNow();
    }
    else
    {
        // This block is usually called when printing without a user prompt.
        // It sets an event handler that listens for the loading of the content
        // document before printing. Sometimes, however, even without a user prompt,
        // the content document is loaded in time for the previous
        // block to execute.
        Layout1.contentDocument.onreadystatechange = PrintWhenContentDocComplete;
    }
}

function PrintWhenContentDocComplete()
{
    if (Layout1.contentDocument.readyState == "complete")
    {
        Layout1.contentDocument.onreadystatechange = null;
        PrintNow();
    }
}

function PrintNow()
{
    firstPage = Printer.pageFrom;
    lastPage = Printer.pageTo;
    
    Printer.startDoc("A print job");
    
    for (i = firstPage; i <= lastPage; i++)
    {
        if (document.all("Page" + i))
            Printer.printPage("Page" + i);
        else
            alert("Print Error");
    }
            
    Printer.stopDoc();
}
</SCRIPT>
</HEAD>

<BODY onload="Init()">
<IE:TEMPLATEPRINTER id="Printer"/>
.
.
.

Requirements

See also

Reference

LayoutRect

DeviceRect

HeaderFooter

dialogArguments

IDM_PRINT

IDM_PRINTPREVIEW

Other Resources

Beyond Print Preview: Print Customization for Internet Explorer 5.5

Print Preview 2: The Continuing Adventures of Internet Explorer 5.5 Print Customization