class Birdwatcher::KML

KML Document generator

KML is a file format used to display geographic data in an Earth browser such as Google Earth. You can create KML files to pinpoint locations, add image overlays, and expose rich data in new ways. KML is an international standard maintained by the Open Geospatial Consortium, Inc. (OGC).

This class supports generating basic KML documents with Placemarks and Folders.

@note Attribute values ARE NOT automatically escaped. All values will have to be given in an HTML escaped fashion if there is a risk that they might contain unexpected or dangerous HTML. @see developers.google.com/kml/

Constants

KML document footer

DOCUMENT_HEADER

KML document header

Public Class Methods

new(attributes = {}) click to toggle source

Class initializer

@param attributes [Hash] Document attributes @see developers.google.com/kml/documentation/kmlreference#document

# File lib/birdwatcher/kml.rb, line 36
def initialize(attributes = {})
  @attributes = attributes
  @folders    = {}
  @placemarks = []
end

Public Instance Methods

add_folder(id, attributes) click to toggle source

Add a Folder

@param id [String] Folder ID @param attributes [Hash] Folder attributes

@see developers.google.com/kml/documentation/kmlreference#folder

# File lib/birdwatcher/kml.rb, line 56
def add_folder(id, attributes)
  @folders[id] = {
    :placemarks => []
  }.merge(attributes)
end
add_placemark(attributes) click to toggle source

Add a Placemark

@param attributes [Hash] Placemark attributes @see developers.google.com/kml/documentation/kmlreference#placemark

# File lib/birdwatcher/kml.rb, line 46
def add_placemark(attributes)
  @placemarks << attributes
end
add_placemark_to_folder(folder_id, attributes) click to toggle source

Add a Placemark to a Folder

@param folder_id [String] @param attributes [Hash] Placemark attributes

@raise [Birdwatcher::KML::UnknownFolderError] if folder doesn’t exist @see developers.google.com/kml/documentation/kmlreference#placemark

# File lib/birdwatcher/kml.rb, line 69
def add_placemark_to_folder(folder_id, attributes)
  fail(UnknownFolderError, "There is no folder with id: #{folder_id}") unless @folders.key?(folder_id)
  @folders[folder_id][:placemarks] << attributes
end
generate() click to toggle source

Generate the KML document

@return the final KML document

# File lib/birdwatcher/kml.rb, line 77
def generate
  output = generate_document_header
  @folders.each_pair { |id, attributes| output += generate_folder(id, attributes) }
  output += @placemarks.map { |p| generate_placemark(p) }.join
  output += generate_document_footer
end

Private Instance Methods

escape(string) click to toggle source

HTML escape a string @private

# File lib/birdwatcher/kml.rb, line 121
def escape(string)
  CGI.escapeHTML(string.to_s)
end
generate_document_header() click to toggle source

Generate document header @private

# File lib/birdwatcher/kml.rb, line 88
def generate_document_header
  header = DOCUMENT_HEADER
  @attributes.each_pair { |k, v| header += "<#{k}>#{escape(v)}</#{k}>\n" }
  header
end
generate_folder(id, attributes) click to toggle source

Generate Folder element @private

# File lib/birdwatcher/kml.rb, line 111
def generate_folder(id, attributes)
  placemarks = attributes.delete(:placemarks)
  folder = "<Folder id='#{escape(id)}'>"
  attributes.each_pair { |k, v| folder += "<#{k}>#{escape(v)}</#{k}>\n" }
  folder += placemarks.map { |p| generate_placemark(p) }.join
  folder += "</Folder>\n"
end
generate_placemark(attributes) click to toggle source

Generate Placemark element @private

# File lib/birdwatcher/kml.rb, line 102
def generate_placemark(attributes)
  placemark = attributes.key?(:id) ? "<Placemark id='#{escape(attributes[:id])}'>" : "<Placemark>"
  attributes.delete(:id)
  attributes.each_pair { |k, v| placemark += "<#{k}>#{v}</#{k}>\n" }
  placemark += "</Placemark>\n"
end