When you export your photos for viewing in Google Earth or Google Maps, HoudahGeo creates a KML file from one of two templates: “Default” or “Extended Track Info”. The later includes more details and thus produces larger files. This makes the “Default” template the better choice for use with Google Maps.
There are occasions where you may want to customize these templates:
- Modify the appearance or contents of the photo “balloons”
- Modify the appearance of the track logs or photo pins
- Change the Places folder structure within the KML file
- Add your own branding or contact information
Please note that KML template customization is not an official feature of HoudahGeo 5. It is very much a work in progress and still has rough edges. Moreover, the template system is subject to changes. The intrepid may read on and learn how to create custom templates for KML output in HoudahGeo.
You will need a basic understanding of HTML, XML, the Google Earth Keyhole Markup Language as well as the Mustache template system.
Please let us know if you use custom KML templates. But do understand that we cannot provide support for template customization. Malformed templates may produce unexpected results or cause HoudahGeo or Google Earth to crash.
Start by copying the default templates:
- In Finder, right-click or control-click the HoudahGeo application icon. From the context menu, select “Show Package Contents”
- Within the application package, navigate to “Contents” / “Resources” and locate the “KML Templates” folder
- Open a second Finder window
- Press and hold the Option key. Select “Library” from the “Go” menu
- Within the Library folder, navigate to “Application Support” / “HoudahGeo”
- Copy the “KML Templates” folder to this location
You are now ready to edit your copies of the templates or create new ones.
The template system uses a subset of the Mustache syntax.
Use a text editor (e.g. BBEdit) to open one of the doc.mustache files within the KML templates.
You will find the following Mustache tag types:
- Variables. Example: {{caption}}. These will be replaced by a value HoudahGeo provides. All variables are HTML escaped by default. If you want to return unescaped HTML, use the triple mustache: {{{identifier}}}.
- Sections. Example: {{#images}} … {{/images}}. The block of text between the section start and end tags will be repeated for each element in the value provided. The default template creates a Placemark for each image. Within the section, variables can refer to attributes of the current iteration item. The {{label}} variable is replaced by the name of the current image.
- Conditionals. These share the same syntax as sections. The block between the text is rendered only if there is a non-empty value available for the attribute. Example: {{#localizedAltitude}} <tr><td><b>{{localizedAltitudeLabel}}</b>:</td><td>{{.}}</td> </tr> {{/localizedAltitude}}. The table row with image altitude information is shown only if localizedAltitude is set. Within the context of the conditional, {{.}} refers to the conditional value.
- Inverted conditionals. Example: {{^thumbnailImageHref}} … {{/thumbnailImageHref}}. The block between the text is rendered only if the conditional value is missing or empty.
HoudahGeo provides the following values to the KML template system:
- altitudeMode (clampToGround or absolute)
- caption (as entered in export options)
- pathPrefix (as entered in export options)
- images (see below)
- tracks (see below)
- tracks? (flag set if track export was enabled)
- localizedLatitudeLabel (label for use in the photo balloons)
- localizedLongitudeLabel
- localizedAltitudeLabel
- localizedViewingDirectionLabel
- localizedSpeedLabel
- localizedLocationLabel
- localizedCityLabel
- localizedProvinceLabel
- localizedCountryLabel
- localizedTimestampLabel
- minTimestampValue (date and time of the first photo)
- localizedMinTimestamp (same as text expressed using the display time zone)
- w3cMinTimestamp (same in W3C format: yyyy-MM-dd’T’HH:mm:ss’Z’)
- gmtMinTimestamp (same expressed in GMT time: yyyy-MM-dd’ ‘HH:mm:ss’Z’)
- maxTimestampValue (date and time of the last photo)
- localizedMaxTimestamp (date and time of the last photo)
- w3cMaxTimestamp
- gmtMaxTimestamp
- nowTimestampValue (current date and time)
- localizedNowTimestamp
- w3cNowTimestamp
- gmtNowTimestamp
- initialLatitudeValue (latitude of the first photo as number value)
- initialLocalizedLatitude (as text using local number formatting)
- initialLatitude (as text using US-POSIX number formatting)
- initialLongitudeValue (longitude of the first photo as number value)
- initialLocalizedLongitude
- initialLongitude
- initialAltitudeValue (in meters)
- initialLocalizedAltitude (as text using the selected altitude unit)
- initialAltitude (in meters)
- userFirstName
- userLastName
- userFullName
- houdahGeoLogoSrc (path or URL to the HoudahGeo app icon)
- houdahGeoVersion
For each entry in images, HoudahGeo provides:
- timestampValue (date and time of the photo as date value)
- localizedTimestamp (same as text expressed using the display time zone)
- w3cTimestamp (same in W3C format: yyyy-MM-dd’T’HH:mm:ss’Z’)
- gmtTimestamp (same expressed in GMT time: yyyy-MM-dd’ ‘HH:mm:ss’Z’)
- latitudeValue (as number value)
- localizedLatitude (as text using local number formatting)
- latitude (as text using US-POSIX number formatting)
- longitudeValue
- localizedLongitude
- longitude
- altitudeValue
- localizedAltitude
- altitude
- viewingDirectionValue
- localizedViewingDirection
- viewingDirection
- headingValue
- localizedHeading
- heading
- speedValue
- localizedSpeed
- speed
- iconHeadingValue (value for IconStyle > Heading)
- iconHeading
- name
- label (title entered in HoudahGeo)
- longLabel (description entered in HoudahGeo)
- location
- city
- province
- country
- identifier (value for Placemark id)
- scaledImageHref (path or URL to the scaled image)
- scaledImageSrc (same with URL escapes)
- scaledImageWidthValue
- scaledImageWidth
- scaledImageHeight
- scaledImageHeightValue
- thumbnailImageHref (only if thumbnails are enabled)
- thumbnailImageSrc
For each entry in tracks, HoudahGeo provides:
- name
- points (see below)
- beginTimestampValue
- endTimestampValue
- minLongitudeValue
- minLongitude
- maxLongitudeValue
- maxLongitude
- minLatitudeValue
- minLatitude
- maxLatitudeValue
- maxLatitude
For each entry in points, HoudahGeo provides:
- latitudeValue
- latitude
- longitudeValue
- longitude
- altitudeValue
- altitude
- timestampValue
- localizedTimestamp
- w3cTimestamp
- gmtTimestamp