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
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 Definition or in its associted documentation files in ​microsoft word or ​html formats.

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.

Implications

Test Plan

Funding/Resources