MapGuide RFC 67 - Common Print Layout and Print Layout Elements

This page contains an change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.

Status

RFC Template Version	1.0
Submission Date	June 18, 2009
Last Modified	Greg Boone Friday Jun 18 10:42:00 2009
Author	Greg Boone
Contributors	Reva Revadigar, Chris Claydon, Steve Dang
RFC Status	Under Construction
Implementation Status
Proposed Milestone	2.x
Assigned PSC guide(s)	Bruce Dechant
Voting History
+1
+0
-0
-1
no vote

Overview

After some analysis on the overall ability to write robust applications using the Print Layout and Print Layout Element definitions as currently defined for MapGuide in the Common Platform API, the current definitions were found to be somewhat limited in their usefulness for developing non-MapGuide applications. In general, it was found to be insufficient to be considered as a robust foundation for a Print Layout Service that would meet the needs of common component development across multiple product lines. The goal of the forthcoming proposal will be the definition of a new print layout schema and service that would replace the current design and provide a foundation for multi-application development moving forward in version 2.x of the Platform API.

Proposed Solution

To support common print layout elements, the general approach will be to develop a set of common definitions representing the schema of various print layout element types, the common components that embody those definitions, and supply the architecture for sharing these definitions and components accross application.

Print Layout and Print Layout Elements

The detailed schema containing the definitions of the print layout, print layout element, and print layout element definition can be found in the attached documents.

The XSD schema definition can be found in the attached ​Print Layout XSD Definition or in its associted documentation files in:

​microsoft word format
​html format

The print layout element design involves defining an entry point for creating print layout and its elements. This entry point is called MgPrintLayoutServiceBase.

This service can be accessed by the familiar entry point for services specific to products using the Common Platform API. For example, it can be accessed as:

MgPrintLayoutServiceBase printLayoutService = ServiceFactory::GetService(MgResourceType::PrintLayout);

MgPrintLayoutServiceBase Class

Here are the principal methods of MgPrintLayoutServiceBase:

CreatePrintLayoutElement

Accepts a resource identifier of the print layout element Xml, and optionally the resource identifier of print layout Xml. It returns the realization of a print layout element in the form of MgPrintLayoutElementBase. The actual realized object depends on the product and the type of print layout element.

For example, if a client wants to create a map viewport, he supplies the resource identifier of map viewport resource Xml. The method returns MgMapViewportBase, which is derived from MgPrintLayoutElementBase. In an application, the method returns XxxMapMapViewport, which inherits from MgMapViewportBase. In MapGuide, the method might return an object of a derived class of MgMapViewportBase similar to XxxMapMapViewport. The caller can use this object to manipulate state on the object.

CreatePrintLayout

Accepts a resource identifier of the print layout Xml and returns MgPrintLayout. It returns the realization of a print layout in the form of MgPrintLayout. The actual realized object depends on the product. For example, it returns XxxMapPrintLayout, which is inherited from MgPrintLayout. In MapGuide, it returns a similar derived object from MgPrintLayout.

CreatePrintLayoutDefinition

Accepts a resource identifier of the print layout element definition. It returns the realization of a print layout element definition in the form of MgPrintLayoutDefinition. The actual realized object depends on the product and the print layout definition. The print layout element definition resources afford reuse of common traits of print layout elements. For example, one or more scale bars might use a common line style, fill color, etc. A print layout element definition affords such reuse. The method returns an MgPrintLayoutElementBaseDefinition. Each type of print layout element that has a need to share a number of traits among multiple instances of the type can define its own print layout definition and reference it from the print layout element resource.

GetPrintLayoutElement

Accepts the identifier of an already existing print layout element resource. It returns the realized print layout element. The actual realized object depends on the product and the type of print layout element.

GetPrintLayoutDefinition

Accepts the identifier of an already existing print layout definition resource. It returns the realized print layout element definition. The actual realized object depends on the product and the type of print layout definition.

PrintLayoutElement Resource Schema

Each print layout element type is defined as a new PrintLayoutElement resource containing definition of the particular type of print layout element. Here’s the schema:

A sample print layout element for map viewport is:

<?xml version="1.0" encoding="UTF-8"?>
<LayoutElement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="Schema\PrintLayoutSchema-1.1.0.xsd">
	<MapViewport>
		<Extents>
		…
		</Extents>
		…
	</MapViewport>
</LayoutElement>

A print layout element gets the data it needs to elaborate its stylized geometry from both Stylization property and Data property. The Data property provides enough information to access all the data necessary to describe the geometry and attributes of the FDO features that are used to represent print layout data.

The Data property includes a resource id that corresponds to the feature source definition defining the feature source for print element layout data. The FeatureClass property within the Data property describes the fully qualified feature class name of the print element layout data.

The Stylization property refers to a resource id that corresponds to the layer definition containing stylization information for the print layout element data (described by Data property). Typically, this will include the composite type style but in general can include any capability we have today in a LayerDefinition schema. The composite type style can include composite symbolization comprising simple or compound symbol definitions.

A particular type of print layout element has a couple of choices when it comes to how it wants to describe its stylized geometry. The first choice is that it can use feature geometry as the main geometry of the element and use the layer definition symbology to further enhance the stylization aspects of the geometry. The second choice is that it can use the layer definition symbology as the primary means to describe its stylized geometry. A classic example for the second choice is a north arrow where the underlying feature would be a point feature with its insertion point coinciding with the north arrow insertion point and using an AutoCAD block defining the north arrow graphics as a symbol that would appear at the insertion point. For Grids and graticules, on the other hand, the better choice might be the first choice where the geometry might tend to be complicated enough to warrant needing actual features (one or more) of different types with simple or complex symbology.

The main reason for this seemingly unnecessary complex mechanism to draw stylized geometry has to do with the sharing of components and language already built into the Common Platform API. We currently use the Platform stylization engine that renders stylized geometry of any FDO feature set using a custom renderer and a layer definition at a particular scale. This pipeline is common to multiple applications. The Data and Stylization properties are just an artifact of the need to have FDO features for geometry of data to be drawn and Layer Definition for stylization of that data.

All the print layout elements can leverage the existing enhanced vector symbolization so we can ensure 100% visual and data fidelity across products. While there are attractive and native solutions, the print layout architecture refrains from using those solutions mainly for interoperable definitions and visual fidelity of print layouts.

A print layout element can reference one or more data sources. These data sources provide information that the print layout element needs. For example, a grid print layout element always needs to know which viewport it is drawing the grid on. The resource identifier for the map viewport will thus be contained within the References property. Another example is a viewport needs to know which map it needs to display in the viewport. Currently, we have an explicit property called MapName on the MapViewport resource, but the References property can point to the id of a Map Definition resource.

A print layout element can also reference a print layout element definition. As was alluded earlier, a print layout element definition contains values of common properties that multiple instances of a print layout element type can share.

The !ExtendedData1 property is added to preserve data added in a later version of the resource in a round-trip scenario.

A print layout element can consist of any one of the several supported types as shown in the diagram below:

The list is not limited to just the types shown above. We would add more in the future.

The Print Layout architecture also allows for creation of print layout elements that are used as adornments and decorations on other print layout elements. The decorators are elements that might alter the stylized geometry of their target print layout element and adorners simply draw their own stylized geometry around their target print layout elements. An example of an adorner is a Border print layout element type that can draw a fancy border with symbols around a map viewport print layout element. These aspects allow for powerful composition of print layout elements.

MgPrintLayoutElementBase class

This class represents the base class for all print layout elements. This is what is returned when a platform client realizes a print layout element using a product-specific print layout service object.

This class has properties that are separated out of the actual print layout element schema. For example, Visibility property is externalized from the print layout element itself so that it is controlled at runtime as opposed to hard-coding it. This class and its resource are very analogous to MgLayerBase and its associated layer definition resource. The MapDefinition resource actually defines the visibility of each layer and as such LayerDefinition itself does not contain a Visiblity property. Name is another such property.

The GetResourceId() method returns the resource identifier of the print layout element itself. Typically, this will be supplied at the construction time of MgPrintLayoutElementBase. This again is very similar to MgLayerBase.

The ForceRefresh() method exists to allow for products that can’t automatically respond to associated resource changes. Such a product is MapGuide where there can be no event support (this is not possible even internally since the site server and web server could be separated). In such products, a client that modifies a resource must invoke a method on the object that is affected by the resource change directly. In Layer API of Geospatial Platform, the ForceRefresh on MgLayerBase helps refresh the layer after its layer definition was modified.

PrintLayout Resource schema

This class represents a runtime print layout just as MgLayerBase represents a runtime MapLayer. It is the container of all print layout elements. It is constructed using the resource identifier of a print layout resource that has information about the paper size, media name, etc. The diagram below shows a preliminary schema for the print layout.

The Elements collection contains the resource identifiers of the print layout elements that are contained within the print layout.

MgPrintLayout class

The realization of a print layout is an instance of MgPrintLayout class. In a 3rd Party application, it will be actually an instance of XxxMapPrintLayout, which derives from MgPrintLayout. In MapGuide, it’ll be an instance of MapGuide-specific print layout realization class.

The GetElements() method returns a collection of actual runtime print layout element instances that are created for the Elements resource id collection. This is all very similar to MgMapBase having GetLayers() returning MgLayerCollection. Whenever a print layout element is added to or removed from the elements collection, a notification is sent out for listeners interested in the change. Those notifications are obviously on the XxxMapPrintLayout class since the Common Platform API does not handle events.

Implications

Test Plan

Funding/Resources