In this topic
Setting the default page size, print quality, and north arrow
When you add a PrintTask to your Web application, the task provides predefined values for the page size, print quality, and north arrow. See the following table:
|
Page size
|
Print quality
|
North arrow
|
|
|
Font name: ESRI North
Font character: 176
|
The Draft quality is appropriate for use with cached services because choosing Normal quality triggers re-sampling and can take longer to generate the output. Normal quality works best with Dynamic services.
If you change the north arrow character that shows on the map—when creating the application in Manager or in Visual Studio—you can use the index character number to set the character number for the PrintTask's north arrow.
In the case of the page size and print quality, the text values shown in the preceding table (that is, small, medium, and large; draft and normal) displays on the Print dialog box that appears when you want to print the map. You can change these values in Visual Studio by editing the appropriate properties on the PrintTask (WidthSettings, QualitySettings, and NorthArrowSettings). However, set these properties for every Web application you create.
The Print Task uses a configuration file to store the predefined values. If you want to replace these values with your values, edit the configuration file in a text editor (new applications will then use the new predefined values).
The configuration (ESRI.ArcGIS.ADF.Tasks.dll.config) file is located in the <install_location>/Dotnet folder. To change the page size or print quality names that display (for example, small, draft, and so on), add a new attribute (referred to as Name). This overrides the current predefined value, which is stored in a resource file for localization purposes. The following code example shows one entry for the page size with the Name attribute added:
[HTML]
<Size ID="PrintTaskSize0" Name=”Small Map” SizeHeight="3.0" SizeWidth="3.0" Unit="Inches" />
When setting the page size and quality, remember that the geographic information system (GIS) server imposes limits on the maximum image size it can return. For example, ArcGIS for Server map services, by default, restrict the image size to a maximum of 2048 by 2048 pixels. This means that a 10 inch square map with a quality of 200 dpi is 2000 by 2000 pixels. If the print task map request exceeds the limits of the GIS server, that service will not print.
Through creating custom print task templates, Web ADF developers have extensive control over the content, arrangement, and appearance of print task output. A print task template is a Web page that manipulates a set of reserved Document Object Model (DOM) element IDs, Cascading Style Sheet (CSS) class names, and JavaScript functions to specify the print page's content.
At design time, you can associate a custom template with a print task by specifying the path to the template in the print task's LayoutTemplateFile property. At run time, when the print task is executed, it does the following:
- Loads the page specified by the LayoutTemplateFile property in a new browser window.
- Populates DOM elements that have IDs that match the print task's reserved IDs with the appropriate content (for example, a map image).
- Fires JavaScript functions with names that match the print task's reserved function names and passes arguments to those functions that contain information about the print task's output.
As a developer, you can create a template from the type of Web page that best meets your requirements. For example, if you just want to position and style the standard print task elements, you can use a simple Hypertext Markup Language (HTML) file. However, if you need to display information that is stored on the Web-tier, you could, for example, use an ASP.NET page.
Print task template DOM elements
When the print task loads its output into the specified template file, it places its output in DOM elements that have a set of reserved IDs. These IDs and the content that is placed in the DOM elements have the properties shown in the following table:
|
DOM Element ID
|
Content
|
| mapTitle | Map title defined by the user on the print task's dialog box. |
| mapImage | Map image. |
| legendSection | Rendered legend table. |
| taskResultsSection | Tables of task results, if selected for output on the print task's dialog box. |
| mapCopyrightTitle | Text of the copyright title. Only applies if a MapCopyrightText control is associated with the map |
| mapCopyrightText | Copyright text for the map's resources. Only applies if a MapCopyrightText control is associated with the map. |
The print task uses the following DOM element IDs in its default template:
<h1 id="mapTitle"></h1>
<img id="mapImage" style="display:none;" src="" alt="" />
<div id="legendSection">
</div>
<div id="taskResultsSection">
</div>
<div id="mapCopyrightTitle">
</div>
<div id="mapCopyrightText">
</div>
The layout of the preceding DOM elements on print pages created from the default print task template is shown in the following illustration:
Print task template CSS classes
The print task also defines a CSS class attribute on many of the DOM elements it creates on the output print page. Along with the reserved DOM element IDs, you can use these class names and the standard CSS, to specify the appearance of the print task's output elements at a fine level of detail. The style classes defined by the print task are shown in the following table:
|
Class Name
|
Element Description
|
| legendSectionTable | Table element containing the legend. |
| legendLabel | Span elements containing the symbol labels in the legend. |
| taskResultHeader | Div element containing the title for the task results section. |
|
taskResultsTable
|
Table elements containing sets of task results.
|
| taskResultsTableCaption | Caption elements containing the titles of task results tables. |
| resultCellHeader | Table cell elements containing task result table column headers. |
| resultCell | Table cell elements containing task result values. |
The default print task template provides a good example of styling the print page based on the class names in the preceding table and the reserved element IDs. See the following code example:
<style type="text/css">
body
{
font-family:Verdana,sans-serif;
}
#mapImage
{
border: 2px solid black;
}
#taskResultsSection
{
padding:0px 5px 5px 5px;
font-size:10px;
}
#legendSection
{
font-size: 10px;
}
.legendLabel
{
font-size: 7.5pt;
}
.taskResultHeader
{
font-size: 12px;
font-weight: bold;
padding-bottom: 10px;
padding-top: 5px;
}
.taskResultsTable
{
border: 1px solid gray;
border-collapse: collapse;
font-size: 8pt;
padding-bottom: 8px;
}
.taskResultsTableCaption
{
text-align: left;
}
.resultCellHeader
{
border: 1px solid gray;
}
.resultCell
{
border: 1px solid gray;
}
#mapCopyrightTitle
{
font-weight: bold;
font-size: 12px;
padding: 0px 5px 5px 0px;
}
#mapCopyrightText
{
padding: 0px;
font-size: 10px;
}
</style>
Print task template JavaScript functions
In addition to offering customization endpoints that allow developers to define print page layout and appearance, the print task template also exposes JavaScript endpoints that allow dynamic manipulation of print task output. This extensibility can be used, for instance, to rearrange the layout based on the map's dimensions or to create advanced visualization of task results. The endpoints provided are reserved function names. To use them, simply declare a function with a reserved name and the print task will execute the function when the print page is loaded. Two arguments are passed to each function. The first is the print task created the print page. The second is an object containing data specific to the particular function. The available functions and the data passed to each is as follows:
|
Function
|
Data Object Contents
|
| setMapImage | Map image uniform resource locator (URL) and dimensions. |
| setTitleHeader | Title text as defined by the user on the print task dialog box. |
| setLegend | Flattened list of legend nodes and settings. |
| setTaskResults | Data tables and node information for task results. |
| setMapCopyrightText | Copyright title and text. |
For examples of print task templates that demonstrate the use of the customization endpoints, see the sample, Common Print task.