Overview
Without a MapPrintManager, the default behavior when the "Print" button
is clicked is to call "window.print()" on the current window. With a print manager present, the print manager's default template is used to generate a printable page in a child window and "print()" is called on that window.
Configuration
At design time the print manager can be configured and print templates added. The print manager has properties called PrintDPI and MarginAllowancesInches. These should be set to values typical for a web browser. PrintDPI defaults to 96. MarginAllowancesInches does not have useful default settings but 0.75 for each margin is a typical setting. In addition, you can click the "Configure Print Templates" option to add and configure template pages and print templates.
Template Pages
A print template page is an HTML page with certain conventions to facilitate working with it. The body of a template page will look something like the following (commentary in red):
<body onload="try {window.opener.MapPrintManagerSetup(window);} catch (e) {window.alert('Error formatting print: ' + e)}" style="margin:0px; padding:0px;">
The call to window.opener.MapPrintManagerSetup is necessary to call "window.print()" and any needed alert (reminder to set page size and layout in the user's print dialog).
The margin and padding styles are to avoid printing excess white space.
<div style="width:800px; height:600px; overflow-y:visible; overflow-x:hidden; margin:0px; padding:0px; border:solid 1px black;">
Immediately inside the body there should be a resizable container. No content should be outside the container.
<table border=0 cellpadding=0 cellspacing=3><tr>
<td style="width:194px" valign=top>
Controls that should be resized when the template is scaled for printing should use CSS to define "width", "height", "top", "left", and "font-size" as needed. EXCEPTION: do not provide width or height styles for the <img> tags for the map, overview map, or legend. Use the <img> "width" and "height" attributes.
<span id="title" style="font-size:12pt; font-weight:bold;">Print Map</span>
You can create any number of elements to contain markup. If you want the markup to be configurable these should have unique ids within the page. If you create markup containers you will need to write custom code to replace any initial text they may contain.
<img id="overviewImage" style="border:solid 1px black;" width=192 height=192 />
The <img> tag for an overview map, if desired, needs a unique ID and size specifications.
<img id="legendImage" style="border:solid 1px black;" width=192 height=288 />
The <img> tag for a map legend, if desired, needs a unique ID and size specifications.
<span id="caption" style="font-size:10pt">Caption</span>
Another markup element.
</td><td style="width:597px" valign=top rowspan=2>
<img id="mapImage" width=597 height=592 border=1 />
The <img> tag for the map image needs an ID and size specifications.
</td></tr>
<tr><td valign=bottom>
<span id="disclaimer" style="font-size:8pt">Not to be used for navigation.</span>
Another markup element.
<br /><br />
<span id="date" style="font-size:8pt"></span>
Another markup element.
</td></tr>
</table>
</div>
</body>
Configuring Print Templates
Once you have a MapPrintManager and at least one print template, click "Configure Print Templates" to add and configure the template page.
Click the "Add" button and select "Template Page" on the panel that appears below the button. If you have not added any template pages yet that will be the only choice.
Here is the template page configuration for the markup above, with all expandable properties expanded.
Note that the ids and dimensions for <img> tags for the map image, overview image, and legend image are provided. If you are not using one of these images, leave the settings blank. Note that OuterSize shows the size of the outermost resizable container plus the space taken up by its borders. The OuterSize must be set to allow the template to be scaled.
There is a collection of markup containers to allow text to be configurable.
The ElementID for a markup container is the only property actually used by the MapPrintManager. The Metadata properties are provided for advanced scenarios where you may want to dynamically emit controls that will be used to populate the markup containers used by a template.
Once you have added a template page you can create one or more templates based on that template page. Click "Add" and select "Print Template" on the panel that appears beneath the Add Button. A dropdown appears. Select the template page this print template will be based on and click "OK".
Here is a print template using the template page shown above.
IsDefaultTemplate should be set true if this is the default template that will be used for the default printing behavior described in the overview section above. Setting a template to be the default unsets any other default.
RaisePaperSizeAndLayoutReminder should be set true if you want the user to be prompted to set appropriate printer settings.
HeightInches and WidthInches set the expected paper size for this template. These values are used along with the PrintDPI and MarginAllowancesInches properties of the MapPrintManager and the OuterSize property of the template page to determine how to scale the template page for this print template.
MapLayoutAdjustment can be set to "Fit" or "Fill".
"Fit" modifies the map scale to match the map image size with minimal changes to the map envelope. If the print map image does not have the same aspect ratio as the map image on the main page, then the envelope will still be expanded to fit the new aspect ratio.
"Fill" keeps the map scale the same and modifies the map envelope only to map image size.
Both of these maintain the map center point.
ScaleFonts indicates whether "font-size" style attributes should be scaled when scaling the template page.
Description describes the template. If RaisePaperSizeAndLayoutReminder is set true, the description becomes part of the reminder so the description should make the page size and layout clear.
Title can be used if you are creating menus of available print templates.
TemplatePage is read-only in this dialog. Click the "Change Page" button if you need to change the template page used by an existing print template.
Printing from MDNAjaxPages
As mentioned, the
MDNAjaxPage has the default behavior of printing the default template when the "Print" button is clicked on the map toolset. The page does this by calling the
MapControlBridge's GetPrintScript() method and then returning the script to the client where it is executed in a call to the JavaScript "eval" method. The code for this is little more than
MapClientStateUpdate.EvalJavascript = Mcb.GetPrintScript();
Any time that GetPrintScript() is called, the
MapControlBridge calls its Print event if a handler for the event has been provided.
The following handler sets the current date in the "date" markup container shown above.
/// <summary>
/// Sets the date and time for the print template on the MapControlBridge's Print event.
/// </summary>
/// <param name="sender">object sender</param>
/// <param name="e">ISC.MapDotNetServer.Controls.PrintEventArgs e</param>
protected void MapControlBridge1_Print( object sender, ISC.MapDotNetServer.Controls.PrintEventArgs e )
{
// look for a markup container with ElementID of "date" and assign it a Value.
if ( e.MarkupContainers != null )
{
foreach ( ISC.MapDotNetServer.Controls.PrintSupport.MarkupContainer container in e.MarkupContainers )
{
if ( container.ElementID == "date" )
{
DateTime now = DateTime.Now;
container.Value = "Printed on " + now.ToShortDateString() + " at " + now.ToShortTimeString();
break;
}
}
}
}
Note that you can cancel the print by setting e.PrintTemplate to null. Note also that e.MarkupTemplates is just a convenient way to access e.PrintTemplate.TemplatePage.MarkupContainers.
Advanced Printing
Advanced printing scenarios can include allowing the user to select a template and/or enter values for markup containers. A selection list can be populated by iterating the MapPrintManager's PrintTemplates collection. If differing templates have different sets of markup containers, appropriate text input controls can be emitted by iterating the MarkupContainers for a selected template (PrintTemplate.TemplatePage.MarkupContainers) and applying settings from the markup container metadata properties discussed above. Getting the print script for a selected template is accomplished by calling the overload of the
MapControlBridge's GetPrintScript method that takes a PrintTemplate. MarkupContainer values can be set on the PrintTemplate prior to calling GetPrintScript or in the
MapControlBridge's Print event.