Creating KML Folders Through KML IDs

Introduction

In the previous example, we learned how to create folders using a feature type fanout. In this example, we will be focusing on creating folders through the use of KML IDs and KML parent attributes. This approach is best for when you want direct control over folder naming and parent-child relationships for as many levels deep as you want. In other words, this approach is for creating a custom folder hierarchy.

Not sure what folders are? No problem! KML folders are what define the nested tree structure in the Google Earth Places pane. Check out the article Creating KML Folders by Feature Type Fanout for a full definition.
 

KML IDs Approach (kml_parent and kml_id)

Similar to the feature type fanout approach, these methods of creating folders are intended for use in KML rather than the KMZ (which is the zipped KML file).

We can create KML folders through KML IDs in two parts: by creating the folder structure, then by creating folder elements and associating all our features with their appropriate folders using kml_parent attributes.

For this example, we will be using a CSV file of Vancouver’s rapid transit stations. Rather than having a big list of stations in the KML Places legend in Google Earth, we want to organize it into a folder hierarchy. We can do this by separating stations by train lines, and then separating the downtown stops for the Canada Line, like the structure below:

The KML ID approach to folder setup uses three levels of folders. This is the file structure that we will use in our example. The parent level is Train Route. It has three children: Connection, Expo, and CanadaLine. The Canada Line has its own child folder, Downtown.

Step-by-step Instructions

Part 1: Create an Empty Folder Structure

1. Setup Workspace
Open FME Workbench and start a blank workspace. Add a Creator to the canvas, then attach five AttributeCreator transformers to it. Open the Creator parameters and delete the Creation Instance Attribute. 


We will be using one AttributeCreator to create each folder. So in other words, if we want five folders, we’ll need five AttributeCreators. Referring to the image of the file structure above, let’s create the  Parent folder first. 

2. Create Parent Folder
Open the first AttributeCreator parameters and create the following attributes:

This is our parent folder, and we named it Train Route ( kml_name). Notice that the kml_id does not have any spaces. We are doing this to reduce the chance of error later when we need to associate our data to this folder. We will put data into these folders by associating it with the kml_id of the folder that we want. We need to be aware of spaces and case sensitivity because our data won’t go into the right folder if we have the wrong ID!
The last thing to point out here is the kml_document. Normally the kml_document would be set to the fme_basename (the source data file name) by default when reading from a dataset. However, when using a Creator, we need to set the kml_document. It’s really important here that we set all of our subsequent AttributeCreators to the same kml_document name if we want to write it out into the same KML file. The name of the kml_document must also be the same name as the file that you are writing out. Folders and data tagged with a different document name than the file name will not be written out into that file.
 
Note for advanced users: This means that by controlling what you name your kml_document, you can write out different KML files using the same workspace. For example, if I want an offshoot KML file called potatoes, I would name the kml_document ‘potatoes’ in the AttributeCreator, and I would get an empty folder called potatoes.kml in addition to what I’m writing out in my workspace. Just be sure that your data is also being written to the desired folder and kml_document name.
 
3. Create Children Folders of the TrainRoute Parent
We are now creating our next level of folders using another three AttributeCreators. We want to create the folders: Connection, Expo, and Canada Line. Alright, you got me! For those of you who are familiar with Vancouver, there is no line called Connection. It’s just a category I’ve separated for Waterfront station which connects the two train lines in this dataset.
In the next AttributeCreator, create the following attributes:

Notice that we have a new attribute here called kml_parent. This method of assigning parent folders is what creates the hierarchy. 
In the next AttributeCreator, create the following attributes:

Finally, in the fourth AttributeCreator, create the following attributes:

 
4. Create the Child Folder of Canada (Line)
The final AttributeCreator will be our subfolder to the folder Canada (Line), open the parameters, and create the following attributes:

 
5. Write Out Folder Structure
Now we can write out the empty folder structure to confirm that it was set up correctly. Add an OGC/Google KML writer to the canvas, and browse to a location to save the file. Name the file transportation.kml (which is the same as the kml_document we used in the AttributeCreators). Set the Feature Type Definition to Automatic, then click OK. 

 
In the Feature Type dialog, change the Feature Type Name to Folder then click OK. This feature type must be named Folder for Google Earth to recognize your folder structure. 

 
6. Run Workspace and View Output in Google Earth
Connect the Folder reader feature type to all five AttributeCreators. Once it is connected, run the workspace then view the output in Google Earth. 

Part 2: Add Data to Folders

7. Read Source Dataset 
Add a Comma Separated Value (CSV) reader to the canvas and browse to the rapid_transit_stations-categorized.csv dataset. Set the Coordinate System to UTM83-10, then open the Parameters. 

 
In the parameters, change the Attribute Definition to Manual. Now we need to set the attribute types so that FME will create points from our data. Set x to x_coordinate, and y to y_coordinate, then click OK twice to add the reader. 

 
8. Filter Data to Put into Folders
Next, we will use a TestFilter to filter out our data by train line and then our last folder, Downtown stations that belong on the Canada Line. We want to filter our data in the same way that our folders are set up so that we can associate data with the correct folder. Add a TestFilter to the canvas and connect it to the rapid_train_stations reader feature type. In the parameters, create the following tests:
 

Except for Waterfront, which we have categorized as a Connection, there are only two other stations on the Canada Line that we consider a part of downtown: Yaletown-Roundhouse and Vancouver City Centre stations. Using that information, we are filtering out Downtown stations on the condition that the station name contains parts of the stations we are looking for (keywords: Vancouver and Yaletown).
 
9. Set the Parent Folder for the Stations of Each Train Line
Add a new AttributeCreator to the CONNECTION output port of the TestFilter. In this step, we are setting the KML parent folder to the data and giving the station an ID name that will be displayed in Google KML by default.
We will set the kml_parent to the corresponding folder (Connection port has a kml_parent: Connection, Expo has a kml_parent: Expo, Downtown has a kml_parent: Downtown, Canada Line has a kml_parent: Canada). We are using the kml_id of the folder as the kml_parent. Remember that we did not use any spaces in the kml_id’s. Below are the parameters for the AttributeCreator connected to the CONNECTION output port of the TestFilter.

For the kml_id here, we are setting it to the Attribute ‘STATION’ in all four AttributeCreators. This attribute contains the train station name. Do the same for the AttributeCreators connected to Expo and CanadaLine, using their respective kml_parent IDs.


10. Style Outputs 
At this point in our workspace, all of our folders now have data. In this step, we are styling our stations by setting icons and icon colors for visualization. Add four KMLStylers to the workspace and attach one to each AttributeCreator from the previous step. 
In the KMLStyler parameters, expand the Icon section then set the Name to gme/gx_rail and set the Color to magenta. Repeat this step for the other three train lines choosing a different color for each one. 

 
11. Set Station Names to TitleCase
If we ran our workspace now, we would find that all of our stations are written in capital letters. To make this look nicer, we will connect all of our KMLStylers to a single KMLPropertySetter transformer. In the KMLPropertySetter parameters, click on the drop-down next to Name in the Navigation Tree section and open the Text Editor. 


In the Text Editor, double-click the FullTitleCase in the String Functions section, then double-click on STATION in the FME Feature Attributes section. It should look like the following (you can also paste in the following):

@FullTitleCase(@Value(STATION))

This string function will convert our STATION name to title case.


12. Write Out Stations
Finally, we can write out the data. On the top menu bar go to Writers > Add Feature Type. In the Feature Type dialog, change the Name to Placemarks, then click OK. 

 
Connect the Placemarks writer feature type to the KMLPropertySetter.

 
13. Run Workspace and View Output in Google Earth
Run the workspace then view the output in Google Earth. All of the stations should be colored and contained within the appropriate folder. 

 

Data Attribution

The data used here originates from open data made available by the City of Vancouver, British Columbia. It contains information licensed under the Open Government License - Vancouver.