Implementer training - alternate output formats

Decide what fields you want to return as the columns of your CSV. Any of the fields with the search result part of the data model can be returned. For the airport finder results page we decide to return only the following fields, which are all sourced from the indexed metadata: "Name","City","Country","IATA/FAA","ICAO","Altitude"

A URL will need to be constructed that defines the fields that are required. Several parameters will be required to set the fields and field names to use:

Decide what fields need to be returned. For the airport finder results page we will return six columns: Name, City, Country, IATA/FAA, ICAO and Altitude. Open the search dashboard, change to the airports data data source and view the metadata mappings. Make a note of the metadata class names for these fields.

Define the query string parameters. To return the six fields will require the following parameters:

Construct a URL from this information and view the response from the all results JSON endpoint. Note that you need to URL encode your parameter values. This illustrates the custom JSON that can be returned using the all results endpoint:

Access the corresponding all results CSV endpoint. When you click the link a CSV file should be downloaded to your computer. Open this file after you’ve downloaded it.

The file will have been saved with a file name similar to all-results.csv. The file name can be defined by adding an additional parameter, fileName, to the URL. Modify the previous URL and add &fileName=airports.csv to the URL then press enter. The file should download and this time be saved as airports.csv.

Open the search dashboard and change to the airport finder results page.

Edit the default template (select the simple.ftl from the edit results page templates listing on the template panel). Add a button above the search results that allows the results to be downloaded as CSV. Add the following code immediately before the <ol> tag with an ID of search-results (approx. line 505):

<p><a class="btn btn-success" href="/s/all-results.csv?collection=${question.collection.id}&query=${question.query}&profile=${question.profile}&fields=listMetadata/name,listMetadata/city,listMetadata/country,listMetadata/iataFaa,listMetadata/icao,listMetadata/altitude&fieldnames=Name,City,Country,IATA/FAA,ICAO,Altitude&SF=[name,city,country,iataFaa,icao,altitude]&SM=meta&fileName=airports.csv">Download results as CSV</a></p>

Run a search for denmark and observe that a download results as CSV button appears above the 28 search results.

Click the download as csv button and the csv file will download. Open the CSV file and confirm that all the results matching the query are included in the CSV data (matching the 28 results specified by the results summary).

Log in to the search dashboard where you are doing your training.

Change to the airport finder results page.

Create a new custom template. Click the edit results page templates item on the template panel, then click the add new button.

Enter geojson.ftl as the name of the file once the new file editor loads.

Create template code to format the results as GeoJSON. Copy the code below into your template editor and hit save.

<#ftl encoding="utf-8" output_format="JSON"/>
<#import "/web/templates/modernui/funnelback_classic.ftl" as s/>
<#import "/web/templates/modernui/funnelback.ftl" as fb/>
<#compress>
<#-- geojson.ftl
Outputs Funnelback response in GeoJSON format.
-->
<#-- Read the metadata field to source the latLong value from from the map.geospatialClass collection.cfg option -->
<#--<#assign latLong=question.currentProfileConfig.get("map.geospatialClass")/>-->
<#-- Hard code using the latLong metadata field for this example -->
<#assign latLong="latlong"/>
<@s.AfterSearchOnly>
<#-- NO RESULTS -->
<@s.IfDefCGI name="callback">${question.inputParameters["callback"]?first!}(</@s.IfDefCGI>
{
<#if response.resultPacket.resultsSummary.totalMatching != 0>
<#-- RESULTS -->
"type": "FeatureCollection",
"features": [
<@s.Results>
<#if s.result.class.simpleName != "TierBar">
<#if s.result.listMetadata[latLong]?? && s.result.listMetadata[latLong]?first!?matches("-?\\d+\\.\\d+;-?\\d+\\.\\d+")> <#-- has geo-coord and it's formatted correctly - update to the meta class containing the geospatial coordinate -->
<#-- EACH RESULT -->
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [${s.result.listMetadata[latLong]?first!?replace(".*\\;","","r")},${s.result.listMetadata[latLong]?first!?replace("\\;.*","","r")}]
},
"properties": { <#-- Fill out with all the custom metadata you wish to expose (e.g. for use in the map display -->
"rank": "${s.result.rank?string}",
"title": "${s.result.title!"No title"}",
<#if s.result.date??>"date": "${s.result.date?string["dd MMM YYYY"]}",</#if>
"summary": "${s.result.summary!}",
"fileSize": "${s.result.fileSize!}",
"fileType": "${s.result.fileType!}",
"exploreLink": "${s.result.exploreLink!}",
<#if s.result.kmFromOrigin?? && question.inputParameters["origin"]??>"kmFromOrigin": "${s.result.kmFromOrigin?string("0.###")}",</#if>
<#-- MORE METADATA FIELDS... -->
"listMetadata": {
<#list s.result.listMetadata?keys as metaDataKey>
"${metaDataKey}": "${s.result.listMetadata[metaDataKey]?join(",")}"<#if metaDataKey_has_next>,</#if>
</#list>
},
"displayUrl": "${s.result.liveUrl!}",
"cacheUrl": "${s.result.cacheUrl!}",
"clickTrackingUrl": "${s.result.clickTrackingUrl!}"
}
}<#if s.result.rank &lt; response.resultPacket.resultsSummary.currEnd>,</#if>
</#if> <#-- has geo-coord -->
</#if>
</@s.Results>
]
</#if>
}<@s.IfDefCGI name="callback">)</@s.IfDefCGI>
</@s.AfterSearchOnly>
</#compress>

Run a search using the geojson template - click on the search icon (eye icon third from the right) that appears in the available actions within the file listing.

A blank screen will display - Funnelback has loaded with the template by no query is supplied. Specify a query by adding &query=!showall to the end of the URL. A fairly empty JSON response is returned to the screen. The response may look like unformatted text, depending on the JSON plugin you have installed. The response is quite empty because the template requires the latlong metadata field to be returned in the response and the collection isn’t currently configured to return this.

Return to the search dashboard and add latlong to the list of summary fields set in the results page configuration. (Update the -SF parameter to include latlong). Refresh the results and observe that you are now seeing data points returned

The template is now configured to return the text in the GeoJSON format. To ensure that your browser correctly detects the JSON we should also configure the GeoJSON template to return the correct MIME type in the HTTP headers. The correct MIME type to return for JSON is application/json - Funnelback templates are returned as text/html by default (which is why the browser renders the text). Return to the administration interface and edit the profile configuration (customize panel, edit results page configuration).

Add the following setting to the profile configuration then save and then publish. This option configures Funnelback to return the text/javascript content type header when using the geojson.ftl template. We are doing this because the template is configured to support a callback function to enable JSONP.

Rerun the search using the geojson template. This time the browser correctly detect and format the response as JSON in the browser window.

Observe that the GeoJSON response only contains 10 results - this is because it is templating what is returned by Funnelback, and that defaults to the first 10 results. In order to return more results an additional parameter needs to be supplied that tells Funnelback how many results to return. E.g. try adding &num_ranks=30 to the URL and observe that 30 results are now returned. If you wish to return all the results when accessing the template you will need to set the num_ranks value either to a number equivalent to the number of documents in your index, or link it from another template where you can read the number of results.