<label_value_list>

Abstract

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

Table of Contents

Catalog Configuration Java API reference: LabelValuesProvider

A <label_value_list> configures a list of label/value pairs which represent the possible values of a <column>. <label_value_list>s are used by the Report Creator Filters Tab to display the available values for a filter parameter. The GET Label Value List REST API returns the list of available values for a <column>.

Usage

Usage with `<label_values>`

The most straightforward way to configure the list of labels and values for a column is via a <label_values> element.

In the following example, the possible values for the name column are statically listed as <label_value>s.

Example 1. Via an XML Catalog file

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="http://www.pullreports.com/catalog-1.6.1" id="city" name="Cities of the World"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.pullreports.com/catalog-1.6.1
    https://www.pullreports.com/docs/xsd/pullreports-catalog-1.6.1.xsd">
    <report id="demographic-information" name="Demographics">
        <export_config defaultColumns="name"/>
        <table id="city" displayName="City" name="cities"> 
            <column id="name" name="city_name" displayName="City Name">
                <label_value_list>
                    <label_values>
                        <label_value value="Beijing">Beijing</label_value>
                        <label_value value="Boston">Boston</label_value>
                        <label_value value="Caracas">Caracas</label_value>
                        <label_value value="Hong Kong">Hong Kong</label_value>
                        <label_value value="London">London</label_value>
                        <label_value value="Los Angeles">Los Angeles</label_value>
                        <label_value value="Nairobi">Nairobi</label_value>
                        <label_value value="New Dehli">New Dehli</label_value>
                        <label_value value="New York">New York</label_value>
                        <label_value value="Paris">Paris</label_value>
                        <label_value value="Rio de Janeiro">Rio de Janeiro</label_value>
                        <label_value value="Vancouver">Vancouver</label_value>
                    </label_values>
                </label_value_list>
            </column>
            <column id="last_census" name="last_census_total" displayName="Last Population" 
               paramType="java.lang.Integer"/>
            <column id="sq_miles" name="sq_miles" displayName="Area (Sq. Miles)" 
               paramType="java.lang.Double"/>
        </table>
    </report>
</catalog>

When creating a filter on the name column within the Pull Reports™ Report Creator, users may select from one of the given values instead of typing an exact city name.

Example 2. Via the Catalog Configuration Java API

Here is the identical configuration within the Catalog Configuration Java API.

package com.pullreports.examples.labelvaluelist;

import com.pullreports.model.CatalogId;
import com.pullreports.model.ColumnId;
import com.pullreports.model.LabelValue;
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 javax.servlet.ServletContext;
import javax.servlet.http.HttpServletRequest;
import javax.sql.DataSource;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;

public class SimpleLabelValueListCatalogConfigurationFactory implements CatalogConfigurationFactory {

    @Override
    public CatalogConfiguration makeCatalog(ServletContext servletContext) {

        ColumnConfiguration nameColumnConfiguration = new ColumnConfiguration.Builder(
            new ColumnId("name"),"city_name")
            .setDisplayName("City Name")
            .setLabelValuesProvider((DataSource ds, HttpServletRequest hsr) ->
                Arrays.asList(
                    new LabelValue("Beijing","Beijing")
                    ,new LabelValue("Boston","Boston")
                    ,new LabelValue("Caracas","Caracas")
                    ,new LabelValue("Hong Kong","Hong Kong")
                    ,new LabelValue("London","London")
                    ,new LabelValue("Los Angeles","Los Angeles")
                    ,new LabelValue("Nairobi","Nairobi")
                    ,new LabelValue("New Dehli","New Dehli")
                    ,new LabelValue("New York","New York")
                    ,new LabelValue("Paris","Paris")
                    ,new LabelValue("Rio de Janeiro","Rio de Janeiro")
                    ,new LabelValue("Vancouver","Vancouver")
                )
            ).build();

        ColumnConfiguration censusColumnConfiguration = new ColumnConfiguration.Builder(
            new ColumnId("last_census"),"last_census_total")
            .setDisplayName("Last Population").setParamType(ParamType.INTEGER)
            .build();

        ColumnConfiguration sqMilesColumnConfiguration = new ColumnConfiguration.Builder(
            new ColumnId("sq_miles"),"sq_miles")
            .setDisplayName("Area (Sq. Miles)").setParamType(ParamType.DOUBLE)
            .build();

        List<ColumnConfiguration> columnConfigurations = Arrays.asList(
                nameColumnConfiguration
                ,censusColumnConfiguration
                ,sqMilesColumnConfiguration);

        TableConfiguration cityTableConfiguration = new TableConfiguration.Builder(
            new TableId("city"),"City",columnConfigurations)
            .setName("cities").build();

        ReportConfiguration demographicReportConfiguration = new ReportConfiguration.Builder(
            new ReportId("demographic-information"),"Demographics",cityTableConfiguration)
            .setExportConfiguration(
                new ExportConfiguration.Builder().setDefaultColumns(Collections.singletonList(
                    nameColumnConfiguration.getId()))
                .build()).build();
        
        List<ReportConfiguration> reportConfigurations = Collections.singletonList(demographicReportConfiguration);

        return new CatalogConfiguration(
            new CatalogId("city"),"Cities of the World",reportConfigurations);
    }
}

Usage with `<label_value_group>`

Use a <label_value_group> to group the label values within the Pull Reports™ Report Creator Filter web form within HTML <optgroup>s.

Note

Note that even when using <label_value_group>s, it is still permitted to use <label_value> elements as direct children of <label_values>. In this example, the <label_value> Future Spaceport on Mars is included outside a <label_value_group>.

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="http://www.pullreports.com/catalog-1.6.1" id="city" name="Cities of the World"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.pullreports.com/catalog-1.6.1
    https://www.pullreports.com/docs/xsd/pullreports-catalog-1.6.1.xsd">
    <report id="demographic-information" name="Demographics">
        <export_config defaultColumns="name"/>
        <table id="city" displayName="City" name="cities"> 
            <column id="name" name="city_name" displayName="City Name">
                <global_label_value_list_ref ref="city_list"/>
            </column>
            <column id="last_census" name="last_census_total" displayName="Last Population" 
               paramType="java.lang.Integer"/>
            <column id="sq_miles" name="sq_miles" displayName="Area (Sq. Miles)" 
               paramType="java.lang.Double"/>
        </table>
    </report>
    <global_label_value_list id="city_list">
        <label_values>
            <label_value_group label="Africa">
                <label_value value="Nairobi">Nairobi</label_value>
            </label_value_group>
            <label_value_group label="Asia">
                <label_value value="Beijing">Beijing</label_value>
                <label_value value="Hong Kong">Hong Kong</label_value>
                <label_value value="New Dehli">New Dehli</label_value>
            </label_value_group>
            <label_value_group label="Europe">
                <label_value value="London">London</label_value>
                <label_value value="Paris">Paris</label_value>
            </label_value_group>
            <label_value_group label="North America">
                <label_value value="Boston">Boston</label_value>
                <label_value value="Los Angeles">Los Angeles</label_value>
                <label_value value="New York">New York</label_value>
                <label_value value="Vancouver">Vancouver</label_value>
            </label_value_group>
            <label_value_group label="South America">
                <label_value value="Caracas">Caracas</label_value>
                <label_value value="Rio de Janeiro">Rio de Janeiro</label_value>
            </label_value_group>
            <label_value value="Future Space Port on Mars">Future Spaceport on Mars</label_value>
        </label_values>
    </global_label_value_list>
</catalog>

Usage with `<label_value_query>`

Use a <label_value_query> to dynamically create label values from a SQL query. In this example, the cities table contains rows representing all possible cities. Also in this example, the label values will be <optgroup>'ed by the value of the continent column within the Pull Reports™ Report Creator Filter web form.

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="http://www.pullreports.com/catalog-1.6.1" id="city" name="Cities of the World"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.pullreports.com/catalog-1.6.1
    https://www.pullreports.com/docs/xsd/pullreports-catalog-1.6.1.xsd">
    <report id="demographic-information" name="Demographics">
        <export_config defaultColumns="name"/>
        <table id="city" displayName="City" name="cities"> 
            <column id="name" name="city_name" displayName="City Name">
                <label_value_list>
                    <label_value_query groupColumn="continent">
                        select city_name as label, city_name as value, continent 
                        from cities order by continent
                    </label_value_query>
                </label_value_list>
            </column>
            <column id="state" name="state_abbrev" displayName="State"/>
            <column id="last_census" name="last_census_total" displayName="Last Population" 
               paramType="java.lang.Integer"/>
            <column id="sq_miles" name="sq_miles" displayName="Area (Sq. Miles)" 
               paramType="java.lang.Double"/>
        </table>
    </report>
</catalog>

Usage with `<label_value_query>` and a Groovy template

<label_value_query>s may contain constructs supported by Groovy's SimpleTemplateEngine such as Groovy or Java math, logic, or String operators and invoke static method calls such as System.getProperty(String). Additionally, the HttpServletRequest associated with the GET Label Value List REST API request is available as the request template attribute.

The following example uses the request template attribute to configure a label value list contextualized to the user making the API request. In the example, the current.continent attribute must be set into the user's HttpSession via a mechanism external to Pull Reports™ such as via a HttpSessionListener.

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="http://www.pullreports.com/catalog-1.6.1" id="city" name="Cities of the World"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.pullreports.com/catalog-1.6.1
    https://www.pullreports.com/docs/xsd/pullreports-catalog-1.6.1.xsd">
    <report id="demographic-information" name="Demographics">
        <export_config defaultColumns="name"/>
        <table id="city" displayName="City" name="cities"> 
            <column id="name" name="city_name" displayName="City Name">
                <label_value_list>
                    <label_value_query>
                        select city_name as label, city_name as value
                        from cities 
                        where
                        continent = '${(request.session.getAttribute('current.continent')}'
                    </label_value_query>
                </label_value_list>
            </column>
            <column id="state" name="state_abbrev" displayName="State"/>
            <column id="last_census" name="last_census_total" displayName="Last Population" 
               paramType="java.lang.Integer"/>
            <column id="sq_miles" name="sq_miles" displayName="Area (Sq. Miles)" 
               paramType="java.lang.Double"/>
        </table>
    </report>
</catalog>

Usage with `<label_value_query_default>`

Use a <label_value_query_default> to configure a label value list from the distinct set of values within the parent <column>. In this example, the Pull Reports™ Report Creator Filters Tab, value field will display a select list of the alphabetically ordered distinct values of the city_name column.

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="http://www.pullreports.com/catalog-1.6.1" id="city" name="Cities of the World"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.pullreports.com/catalog-1.6.1
    https://www.pullreports.com/docs/xsd/pullreports-catalog-1.6.1.xsd">
    <report id="demographic-information" name="Demographics">
        <export_config defaultColumns="name"/>
        <table id="city" displayName="City" name="cities"> 
            <column id="name" name="city_name" displayName="City Name">
                <label_value_list>
                    <label_value_query_default/>
                </label_value_list>
            </column>
            <column id="state" name="state_abbrev" displayName="State"/>
            <column id="last_census" name="last_census_total" displayName="Last Population" 
               paramType="java.lang.Integer"/>
            <column id="sq_miles" name="sq_miles" displayName="Area (Sq. Miles)" 
               paramType="java.lang.Double"/>
        </table>
    </report>
</catalog>

Children

( <label_value_query> | <label_value_query_default> | <label_values> )

Parents

<column>

Prev		Next
<label_value_group>	Home	<label_value_query>

<label_value_list>

Usage

Usage with <label_values>

Usage with <label_value_group>