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 the following predefined values for the page size, print quality, and north arrow:
|
Page size
|
Print quality
|
North arrow
|
|
|
Font name: ESRI North
Font character: 176
|
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 in 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 Server map services, by default, restrict the image size to a maximum of 2048 x 2048 pixels. This means that a 10 inch square map with a quality of 200 dpi is 2000 x 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 simply a web page that manipulates a set of reserved DOM element IDs, 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 will:
- Load the page specified by the LayoutTemplateFile property in a new browser window
- Populate DOM elements that have IDs that match the print task's reserved IDs with the appropriate content (e.g. a map image)
- Fire JavaScript functions with names that match the print task's reserved function names and pass arguments to those functions that contain information about the print task's output
You as a developer can create a template from the type of web page that best suits your needs. For instance, if you just want to position and style the standard print task elements, you can use a simple HTML file. If, however, you need to display information that is stored in 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 having them are as follows:
|
DOM Element ID
|
Content
|
| mapTitle | Map title as defined by the user on the print task's dialog. |
| mapImage | Map image |
| legendSection | Rendered legend table |
| taskResultsSection | Tables of task results, if selected for output on the print task's dialog |
| 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 these 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 these DOM elements on print pages created from the default print task template is shown in the figure below:
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 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 as follows:
|
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 these class names and the reserved element IDs:
<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 url and dimensions |
| setTitleHeader | title text as defined by the user on the print task dialog |
| setLegend | flattened list of legend nodes and settings |
| setTaskResults | data tables and node info for task results |
| setMapCopyrightText | copyright title and text |
For examples of print task templates that demonstrate the use of the customization endpoints, refer to the Common_PrintTask sample.