<placemark_name_template>

Abstract

Learn to configure the <placemark_name_template> element for Pull Reports™ Ad Hoc report and data service software.


Table of Contents

Catalog Configuration Java API reference:  KmlConfiguration

KML viewers such as Google Earth label KML <Placemarks> via their child <name> element. Use <placemark_name_template> to customize the Placemark <name> per Export Report REST API result row.

The body of a <placemark_name_template> is a Freemarker template which may reference @ prefixed <column> ids from the report's base table as template variables. When exported via the Export Report REST API, each row's actual column value is substituted for the respective variable to form the KML Placemark name for that row.

Usage

Basic usage

In the following fictional example, the land_ownership table contains information about the land ownership parcels in a suburban neighborhood. The table contains addresses, the owner's name and a geom_kml column with the parcel's KML geometry.

Table 1. land_ownership table
idowner_namestreet_addressstatezipgeom_kml
39Carrie Franklin49 West SheelyVermont98833...
40Marjo Hoff104 JuniperVermont98833...

When exported via the Export Report REST API and viewed within a KML viewer, each record within the land_ownership table should be labeled with a KML Placemark formatted like this:

[Owner Name] - [ZIP] (ID: [ID])

With a ${@oname} - ${@zip} (ID: ${@id}) template, the two rows look like this in a KML viewer:

Figure 1. Two KML Placemarks with a custom name
Two KML Placemarks with a custom name

Example 1. Via an XML Catalog file
<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="http://www.pullreports.com/catalog-1.7.0" id="land-ownership" name="Land Ownership Reports"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.pullreports.com/catalog-1.7.0
    https://www.pullreports.com/docs/xsd/pullreports-catalog-1.7.0.xsd">
    <report id="parcel-information" name="Parcel Information">
        <export_config defaultColumns='id,oname'>
            <kml geometryColumnPath="@parcel-geometry-kml">
                <placemark_name_template>${@oname} - ${@zip} (ID: ${@id})</placemark_name_template>
            </kml>
       </export_config>
        <table id="parcel" displayName="Land Parcel" name="land_ownership"> 
            <column id="id" name="id" displayName="Parcel ID" paramType="java.lang.Integer"/>
            <column id="oname" name="owner_name" displayName="Owner Name"/>
            <column id="street" name="street_address" displayName="Street" />
            <column id="state" name="state" displayName="State" />
            <column id="zip" name="zip" displayName="Zip" />
            <column id="parcel-geometry-kml" name="geom_kml" displayName="KML" />
        </table>
    </report>
</catalog>

Example 2. Via the Catalog Configuration Java API

The following example is an identical Catalog Configuration Java API configuration.

package com.pullreports.examples.placemarknametemplate;

import com.pullreports.model.CatalogId;
import com.pullreports.model.ColumnId;
import com.pullreports.model.ParamType;
import com.pullreports.model.ReportId;
import com.pullreports.model.TableId;
import com.pullreports.model.config.CatalogConfiguration;
import com.pullreports.model.config.CatalogConfigurationFactory;
import com.pullreports.model.config.ColumnConfiguration;
import com.pullreports.model.config.ReportConfiguration;
import com.pullreports.model.config.TableConfiguration;
import com.pullreports.model.exportconfig.ExportConfiguration;
import com.pullreports.model.exportconfig.KmlConfiguration;

import jakarta.servlet.ServletContext;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;

public class PlacemarkNameTemplateCatalogConfigurationFactory implements CatalogConfigurationFactory {

    @Override
    public CatalogConfiguration makeCatalog(ServletContext servletContext) {

        ColumnConfiguration idColumnConfiguration = new ColumnConfiguration.Builder(
            new ColumnId("id"),"id")
            .setParamType(ParamType.INTEGER)
            .setDisplayName("Parcel ID").build();

        ColumnConfiguration onameColumnConfiguration = new ColumnConfiguration.Builder(
            new ColumnId("oname"),"owner_name")
            .setDisplayName("Owner Name")
            .build();

        ColumnConfiguration streetColumnConfiguration = new ColumnConfiguration.Builder(
            new ColumnId("street"),"street_address")
            .setDisplayName("Street")
            .build();

        ColumnConfiguration stateColumnConfiguration = new ColumnConfiguration.Builder(
            new ColumnId("state"),"state")
            .setDisplayName("State")
            .build();

        ColumnConfiguration zipColumnConfiguration = new ColumnConfiguration.Builder(
            new ColumnId("zip"),"zip")
            .setDisplayName("Zip").build();

        ColumnConfiguration kmlColumnConfiguration = new ColumnConfiguration.Builder(
            new ColumnId("parcel-geometry-kml"),"geom_kml")
            .setDisplayName("KML").build();

        List<ColumnConfiguration> columnConfigurations = Arrays.asList(
                idColumnConfiguration
                ,onameColumnConfiguration
                ,streetColumnConfiguration
                ,stateColumnConfiguration
                ,zipColumnConfiguration
                ,kmlColumnConfiguration);

        TableConfiguration parcelTableConfiguration = new TableConfiguration.Builder(
            new TableId("parcel"),"Land Parcel",columnConfigurations)
            .setName("land_ownership").build();

        KmlConfiguration kmlConfiguration = new KmlConfiguration(
            kmlColumnConfiguration.getId(),"${@oname} - ${@zip} (ID: ${@id})");

        ReportConfiguration parcelReportConfiguration = new ReportConfiguration.Builder(
            new ReportId("parcel-information"),"Parcel Information",parcelTableConfiguration)
            .setExportConfiguration(
                new ExportConfiguration.Builder()
                    .setDefaultColumns(Arrays.asList(
                    idColumnConfiguration.getId()
                        ,onameColumnConfiguration.getId()))
                    .setKmlConfiguration(kmlConfiguration)
                .build()).build();
        
        List<ReportConfiguration> reportConfigurations = Collections.singletonList(parcelReportConfiguration);

        return new CatalogConfiguration(new CatalogId("land-ownership"),"Land Ownership Reports",reportConfigurations);
    }
}

                

Default KML <Placemark> name

If the configuration provides no <placemark_name_template> the default Placemark template is:

[Report Name] Geometry

If the prior example lacked a <placemark_name_template>, each Placemark would be:

Parcel Information Geometry

And would look like this in a KML viewer:

Figure 2. Two KML Placemarks with the default name
Two KML Placemarks with the default name

Parents

<kml>