Quickstart: Printing from your app (HTML)

Article
08/31/2015

This Quickstart shows the simplest way to add print functionality to your Windows Store app.

Watch this brief video for an overview of the process.

The simplest way to print from your Windows Store app is for it to use Windows printing. To do that, your app must:

Register for the Print contract in each display of the app from which you want users to be able to print.

Registering for the Print contract means obtaining a PrintManager object, creating a PrintTask object, and handling the printing events.
Provide formatted content to print.

The default print experience shown in this Quickstart is for Windows to print your app's screen display.

Note Customized printing features like printing specific pages or custom print settings can only be added to Windows Store apps using C++, C#, or Visual Basic and XAML. For more info about adding custom printing features to your app, see Printing (XAML).

Prerequisites

You must be familiar with HTML, JavaScript, Windows events, and event handling.
You must have Microsoft Visual Studio installed.
You must have a printer installed.
You must have an app to which you want to add printing. If you don't have your own app, you can download the Print Sample sample app and use that app.Note The examples in this Quickstart are found in the Print Sample sample app.

Instructions

1. Open the app's source code for editing

This procedure describes how to open the PrintSampleJS app from the Print Sample sample app. If you are using your own app, open it in Visual Studio and skip to the next step.

Open the Print Sample sample app and download the JavaScript example to your computer.
In Visual Studio, click File > Open Project and navigate to the folder that contains the solution file of the sample app that you downloaded in the previous step.
Select the PrintSampleJS solution file, and click Open.

2. Build and test the app

Click Build > Build Solution to build the app you are working on. Make sure that there are no error messages in the Output pane at the bottom of the screen.
Click Debug > Start Without Debugging.
Verify that, after a few seconds, the screen displays the Print JS Sample app.
If the app runs without error, return to Visual Studio and click Debug > Stop Debugging.

3. Register for Windows printing

At this point, you should have an app that displays a screen with some content.

The first step to add printing to your app is to register for the Print contract. Your app must do this on every screen from which you want your customer to be able to print.

Note Only the screen that is displayed to the user can be registered for printing. If one screen of your app has registered for printing, it must unregister for printing when it exits. If it is replaced by another screen, the next screen must register for a new Print contract when it opens.

Registering for the Print contract means obtaining a PrintManager object and defining the handler for the PrintTaskRequested event.

To each screen in your app from which you want to print, add the following code so that it runs when the screen is opened. In the PrintSampleJS sample app, this is done in the ready member of the members parameter to the WinJS.UI.Pages.define function that is called to create the screen.
```
var printManager = Windows.Graphics.Printing.PrintManager.getForCurrentView();
printManager.onprinttaskrequested = onPrintTaskRequested;
```
Note You could include this code in a separate function, as the PrintSampleJS sample app does.

Add the print-task event handler for that screen. Each screen in your app might need a different function if, for example, the content of each needs to be formatted differently for printing.

This PrintSampleJS app includes a completion handler, which is shown here. It's a good idea to handle completion events because then your app can let the user know if an error occurred and provide possible solutions. Likewise, your app could use the completion event to indicate subsequent steps for the user to take after the print job is successful.

function onPrintTaskRequested(printEvent) {
    var printTask = printEvent.request.createPrintTask("Print Sample", function (args) {
        args.setSource(MSApp.getHtmlPrintDocumentSource(document));

        // Register the handler for print task completion event
        printTask.oncompleted = onPrintTaskCompleted;
    });
}

function onPrintTaskCompleted(printTaskCompletionEvent) {
    // Notify the user about the failure
    if (printTaskCompletionEvent.completion === Windows.Graphics.Printing.PrintTaskCompletion.failed) {
        WinJS.log && WinJS.log("Failed to print.", "sample", "error");
    }
}

Build and test the app as previously described.

4. Printing from your app

After you modify and build your app, test the new functionality in the debugger.

Click Debug > Start Debugging.
Verify that, after a few seconds, the screen displays the Print JS Sample app.
Swipe from the right side of the screen to display the charms.
Select the Devices charm.
Select a printer. The Print window should appear.
Click the Print button on the print window to print the content from the current screen.
Review the printed result.

Summary and next steps

In this Quickstart, you added Windows printing to your app, without modifying how users interact with your app or how your app formats its content for printing.

From here, you can explore some more advanced printing functions. In How to print using an in-app print button, you'll add a print button that the user can click to print from your Windows Store app.

Note

You can use the JavaScript function window.print() to print your app’s content, but window.print() is intended for printing the content that is displayed on the screen by using the default print experience. Because a Windows Store app screen doesn’t always produce good printed output, calling window.print() might not be the best approach. For the best customer experience, we recommend that you use the Windows Runtime functions and register for the Print contract as these topics demonstrate.

And to see more printing scenarios that are available in Windows Store apps, see the Print Sample sample app.

Print Sample sample app

Best Practices for developing print-capable Windows Store apps

Developing Windows Store device apps for printers