| 1 | package Geo::GoogleEarth::Pluggable; | ||||||||||||
| 2 | 7 | ▶ | use strict; | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 3 | 7 | ▶ | use warnings; | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 4 | 7 | ▶ | use base qw{Geo::GoogleEarth::Pluggable::Folder}; | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 5 | 7 | ▶ | use XML::LibXML::LazyBuilder qw{DOM E}; | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 6 | 7 | ▶ | use Archive::Zip qw{COMPRESSION_DEFLATED}; | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 7 | 7 | ▶ | use IO::Scalar qw{}; | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 8 | |||||||||||||
| 9 | 7 | our $VERSION='0.17'; | |||||||||||
| 10 | |||||||||||||
| 11 | =head1 NAME | ||||||||||||
| 12 | |||||||||||||
| 13 | Geo::GoogleEarth::Pluggable - Generates GoogleEarth Documents | ||||||||||||
| 14 | |||||||||||||
| 15 | =head1 SYNOPSIS | ||||||||||||
| 16 | |||||||||||||
| 17 | use Geo::GoogleEarth::Pluggable; | ||||||||||||
| 18 | my $document=Geo::GoogleEarth::Pluggable->new(%data); #is a special Folder... | ||||||||||||
| 19 | my $folder =$document->Folder(%data); #isa Geo::GoogleEarth::Pluggable::Folder | ||||||||||||
| 20 | my $point =$document->Point(%data); #isa Geo::GoogleEarth::Pluggable::Point | ||||||||||||
| 21 | my $netlink =$document->NetworkLink(%data); #isa Geo::GoogleEarth::Pluggable::NetworkLink | ||||||||||||
| 22 | my $lookat =$document->LookAt(%data); #isa Geo::GoogleEarth::Pluggable::LookAt | ||||||||||||
| 23 | my $style =$document->Style(%data); #isa Geo::GoogleEarth::Pluggable::Style | ||||||||||||
| 24 | print $document->render; | ||||||||||||
| 25 | |||||||||||||
| 26 | KML CGI Example | ||||||||||||
| 27 | |||||||||||||
| 28 | use Geo::GoogleEarth::Pluggable; | ||||||||||||
| 29 | my $document=Geo::GoogleEarth::Pluggable->new(name=>"KML Document"); | ||||||||||||
| 30 | print $document->header, | ||||||||||||
| 31 | $document->render; | ||||||||||||
| 32 | |||||||||||||
| 33 | KMZ CGI Example | ||||||||||||
| 34 | |||||||||||||
| 35 | use Geo::GoogleEarth::Pluggable; | ||||||||||||
| 36 | my $document=Geo::GoogleEarth::Pluggable->new(name=>"KMZ Document"); | ||||||||||||
| 37 | print $document->header_kmz, | ||||||||||||
| 38 | $document->archive; | ||||||||||||
| 39 | |||||||||||||
| 40 | =head1 DESCRIPTION | ||||||||||||
| 41 | |||||||||||||
| 42 | Geo::GoogleEarth::Pluggable is a Perl object oriented interface that allows for the creation of XML documents that can be used with Google Earth. | ||||||||||||
| 43 | |||||||||||||
| 44 | Geo::GoogleEarth::Pluggable (aka Document) is a L<Geo::GoogleEarth::Pluggable::Folder> with a render method. | ||||||||||||
| 45 | |||||||||||||
| 46 | =head2 Object Inheritance Graph | ||||||||||||
| 47 | |||||||||||||
| 48 | --- Constructor -+- Base --- Folder --- Document | ||||||||||||
| 49 | | | | ||||||||||||
| 50 | | +- Placemark -+- Point | ||||||||||||
| 51 | | | +- LineString | ||||||||||||
| 52 | | | +- LinearRing | ||||||||||||
| 53 | | | | ||||||||||||
| 54 | | +- StyleBase -+- Style | ||||||||||||
| 55 | | | +- StyleMap | ||||||||||||
| 56 | | | | ||||||||||||
| 57 | | +- NetworkLink | ||||||||||||
| 58 | | | ||||||||||||
| 59 | +- LookAt | ||||||||||||
| 60 | |||||||||||||
| 61 | =head2 Constructors that append to the parent folder object | ||||||||||||
| 62 | |||||||||||||
| 63 | Folder, NetworkLink, Point, LineString, LinearRing | ||||||||||||
| 64 | |||||||||||||
| 65 | =head2 Constructors that return objects for future use | ||||||||||||
| 66 | |||||||||||||
| 67 | LookAt(), Style(), StyleMap() | ||||||||||||
| 68 | |||||||||||||
| 69 | =head2 Wrappers (what makes it easy) | ||||||||||||
| 70 | |||||||||||||
| 71 | Style => IconStyle, LineStyle, PolyStyle, LabelStyle, ListStyle | ||||||||||||
| 72 | |||||||||||||
| 73 | Point => MultiPoint | ||||||||||||
| 74 | |||||||||||||
| 75 | =head1 USAGE | ||||||||||||
| 76 | |||||||||||||
| 77 | This is all of the code you need to generate a complete Google Earth document. | ||||||||||||
| 78 | |||||||||||||
| 79 | use Geo::GoogleEarth::Pluggable; | ||||||||||||
| 80 | my $document=Geo::GoogleEarth::Pluggable->new; | ||||||||||||
| 81 | $document->Point(name=>"White House", lat=>38.897337, lon=>-77.036503); | ||||||||||||
| 82 | print $document->render; | ||||||||||||
| 83 | |||||||||||||
| 84 | =head1 CONSTRUCTOR | ||||||||||||
| 85 | |||||||||||||
| 86 | =head2 new | ||||||||||||
| 87 | |||||||||||||
| 88 | my $document=Geo::GoogleEarth::Pluggable->new(name=>"My Name"); | ||||||||||||
| 89 | |||||||||||||
| 90 | =head1 METHODS | ||||||||||||
| 91 | |||||||||||||
| 92 | =head2 type | ||||||||||||
| 93 | |||||||||||||
| 94 | Returns the object type. | ||||||||||||
| 95 | |||||||||||||
| 96 | my $type=$folder->type; | ||||||||||||
| 97 | |||||||||||||
| 98 | =cut | ||||||||||||
| 99 | |||||||||||||
| 100 | 7 | ▶ | sub type {"Document"}; | ||||||||||
|
Subroutine
type: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||
| 101 | |||||||||||||
| 102 | =head2 document | ||||||||||||
| 103 | |||||||||||||
| 104 | Returns the document object. | ||||||||||||
| 105 | |||||||||||||
| 106 | All objects know to which document they belong even the document itself! | ||||||||||||
| 107 | |||||||||||||
| 108 | =cut | ||||||||||||
| 109 | |||||||||||||
| 110 | 5 | ▶ | sub document {shift}; | ||||||||||
|
Subroutine
document: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||
| 111 | |||||||||||||
| 112 | =head2 render | ||||||||||||
| 113 | |||||||||||||
| 114 | Returns an XML document with an XML declaration and a root name of "Document" | ||||||||||||
| 115 | |||||||||||||
| 116 | print $document->render; | ||||||||||||
| 117 | |||||||||||||
| 118 | =cut | ||||||||||||
| 119 | |||||||||||||
| 120 | 7 | ▶ | sub render { | ||||||||||
|
Subroutine
render: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||
| 121 | 7 | my $self=shift; | |||||||||||
| 122 | 7 | my $d = DOM(E(kml=>{$self->xmlns}, $self->node)); | |||||||||||
| 123 | 7 | return $d->toString; | |||||||||||
| 124 | } | ||||||||||||
| 125 | |||||||||||||
| 126 | =head2 archive | ||||||||||||
| 127 | |||||||||||||
| 128 | Returns a KMZ formatted Zipped archive of the XML document | ||||||||||||
| 129 | |||||||||||||
| 130 | print $document->archive; | ||||||||||||
| 131 | |||||||||||||
| 132 | =cut | ||||||||||||
| 133 | |||||||||||||
| 134 | 0 | ▶ | sub archive { | ||||||||||
|
Subroutine
archive: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||
| 135 | 0 | my $self=shift; | |||||||||||
| 136 | 0 | my $azip=Archive::Zip->new; | |||||||||||
| 137 | 0 | my $member=$azip->addString($self->render, "doc.kml"); | |||||||||||
| 138 | 0 | $member->desiredCompressionMethod(COMPRESSION_DEFLATED); | |||||||||||
| 139 | #$member->desiredCompressionLevel(9); #RT60563, RT54827 | ||||||||||||
| 140 | |||||||||||||
| 141 | 0 | my $archive=q{}; | |||||||||||
| 142 | 0 | my $iosh=IO::Scalar->new( \$archive ); | |||||||||||
| 143 | 0 | $azip->writeToFileHandle($iosh); | |||||||||||
| 144 | 0 | $iosh->close; | |||||||||||
| 145 | 0 | return $archive; | |||||||||||
| 146 | } | ||||||||||||
| 147 | |||||||||||||
| 148 | =head2 xmlns | ||||||||||||
| 149 | |||||||||||||
| 150 | Add or update a namespace | ||||||||||||
| 151 | |||||||||||||
| 152 | $document->xmlns->{"namespace"}=$url; | ||||||||||||
| 153 | |||||||||||||
| 154 | Delete a namespace | ||||||||||||
| 155 | |||||||||||||
| 156 | delete($document->xmlns->{"xmlns:gx"}); | ||||||||||||
| 157 | |||||||||||||
| 158 | Replace all namespaces | ||||||||||||
| 159 | |||||||||||||
| 160 | $document->{"xmlns"}={namespace=>$url}; | ||||||||||||
| 161 | |||||||||||||
| 162 | Reset to default namespaces | ||||||||||||
| 163 | |||||||||||||
| 164 | delete($document->{"xmlns"}); | ||||||||||||
| 165 | |||||||||||||
| 166 | =cut | ||||||||||||
| 167 | |||||||||||||
| 168 | 7 | ▶ | sub xmlns { | ||||||||||
|
Subroutine
xmlns: called CC=3 SCAR=11.0
Pod
documented
| |||||||||||||
| 169 | 7 | my $self=shift; | |||||||||||
| 170 | 7 | ▶ | unless (defined($self->{'xmlns'})) { | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 171 | 2 | $self->{'xmlns'}={ | |||||||||||
| 172 | 'xmlns' => "http://www.opengis.net/kml/2.2", | ||||||||||||
| 173 | 'xmlns:gx' => "http://www.google.com/kml/ext/2.2", | ||||||||||||
| 174 | 'xmlns:kml' => "http://www.opengis.net/kml/2.2", | ||||||||||||
| 175 | 'xmlns:atom' => "http://www.w3.org/2005/Atom", | ||||||||||||
| 176 | }; | ||||||||||||
| 177 | } | ||||||||||||
| 178 | 7 | ▶ | return wantarray ? %{$self->{'xmlns'}} : $self->{'xmlns'}; | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 179 | } | ||||||||||||
| 180 | |||||||||||||
| 181 | =head2 nextId | ||||||||||||
| 182 | |||||||||||||
| 183 | This method is in the document since all Styles and StyleMaps are in the document not folders. | ||||||||||||
| 184 | |||||||||||||
| 185 | my $id=$document->nextId($type); #$type in "Style" or "StyleMap" | ||||||||||||
| 186 | |||||||||||||
| 187 | =cut | ||||||||||||
| 188 | |||||||||||||
| 189 | 0 | ▶ | sub nextId { | ||||||||||
|
Subroutine
nextId: not called CC=3 SCAR=24.8
Pod
documented
| |||||||||||||
| 190 | 0 | my $self=shift; | |||||||||||
| 191 | 0 | ▶ | my $type=shift || "Unknown"; | ||||||||||
|
Condition0%0/2
shift() || 'Unknown'
MC/DC0%0/1
shift() || 'Unknown'
shift()
Truth table0%0/2
A
A= shift()
| |||||||||||||
| 192 | 0 | ▶ | $self->{"nextId"}=0 unless defined $self->{"nextId"}; | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 193 | 0 | return sprintf("%s-%s-%s", $type, "perl", $self->{"nextId"}++); | |||||||||||
| 194 | } | ||||||||||||
| 195 | |||||||||||||
| 196 | =head2 header, header_kml | ||||||||||||
| 197 | |||||||||||||
| 198 | Returns a header appropriate for a web application | ||||||||||||
| 199 | |||||||||||||
| 200 | Content-type: application/vnd.google-earth.kml+xml | ||||||||||||
| 201 | Content-Disposition: attachment; filename=filename.xls | ||||||||||||
| 202 | |||||||||||||
| 203 | $document->header #embedded in browser | ||||||||||||
| 204 | $document->header(filename=>"filename.xls") #download prompt | ||||||||||||
| 205 | $document->header(content_type=>"application/vnd.google-earth.kml+xml") #default content type | ||||||||||||
| 206 | |||||||||||||
| 207 | =cut | ||||||||||||
| 208 | |||||||||||||
| 209 | 7 | *header_kml=\&header; | |||||||||||
| 210 | |||||||||||||
| 211 | 0 | ▶ | sub header { | ||||||||||
|
Subroutine
header: not called CC=3 SCAR=24.8
Pod
documented
| |||||||||||||
| 212 | 0 | my $self=shift; | |||||||||||
| 213 | 0 | my %data=@_; | |||||||||||
| 214 | $data{"content_type"}="application/vnd.google-earth.kml+xml" | ||||||||||||
| 215 | 0 | ▶ | unless defined $data{"content_type"}; | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 216 | 0 | my $header=sprintf("Content-type: %s\n", $data{"content_type"}); | |||||||||||
| 217 | $header.=sprintf(qq{Content-Disposition: attachment; filename="%s";\n}, | ||||||||||||
| 218 | 0 | ▶ | $data{"filename"}) if defined $data{"filename"}; | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 219 | 0 | $header.="\n"; | |||||||||||
| 220 | 0 | return $header; | |||||||||||
| 221 | } | ||||||||||||
| 222 | |||||||||||||
| 223 | =head2 header_kmz | ||||||||||||
| 224 | |||||||||||||
| 225 | Returns a header appropriate for a web application | ||||||||||||
| 226 | |||||||||||||
| 227 | Content-type: application/vnd.google-earth.kml+xml | ||||||||||||
| 228 | Content-Disposition: attachment; filename=filename.xls | ||||||||||||
| 229 | |||||||||||||
| 230 | $document->header_kmz #embedded in browser | ||||||||||||
| 231 | $document->header_kmz(filename=>"filename.xls") #download prompt | ||||||||||||
| 232 | $document->header_kmz(content_type=>"application/vnd.google-earth.kmz") #default content type | ||||||||||||
| 233 | |||||||||||||
| 234 | =cut | ||||||||||||
| 235 | |||||||||||||
| 236 | 0 | ▶ | sub header_kmz { | ||||||||||
|
Subroutine
header_kmz: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||||
| 237 | 0 | my $self=shift; | |||||||||||
| 238 | 0 | my %data=@_; | |||||||||||
| 239 | 0 | ▶ | $data{"content_type"}||="application/vnd.google-earth.kmz"; | ||||||||||
|
Condition0%0/2
$data{"content_type"} ||= "application/vnd.google-earth.kmz"
MC/DC0%0/1
$data{"content_type"} ||= "application/vnd.google-earth.kmz"
$data{"content_type"}
Truth table0%0/2
A
A= $data{"content_type"}
| |||||||||||||
| 240 | 0 | return $self->header(%data); | |||||||||||
| 241 | } | ||||||||||||
| 242 | |||||||||||||
| 243 | =head1 TODO | ||||||||||||
| 244 | |||||||||||||
| 245 | =over | ||||||||||||
| 246 | |||||||||||||
| 247 | =item Support for default Polygon and Line styles that are nicer than GoogleEarth's | ||||||||||||
| 248 | |||||||||||||
| 249 | =item Support for DateTime object in the constructor that is promoted to the LookAt object. | ||||||||||||
| 250 | |||||||||||||
| 251 | =item Create a L<GPS::Point> plugin (Promote tag as name and datetime to LookAt) | ||||||||||||
| 252 | |||||||||||||
| 253 | =back | ||||||||||||
| 254 | |||||||||||||
| 255 | =head1 BUGS | ||||||||||||
| 256 | |||||||||||||
| 257 | Please log on RT and send to the geo-perl email list. | ||||||||||||
| 258 | |||||||||||||
| 259 | =head1 LIMITATIONS | ||||||||||||
| 260 | |||||||||||||
| 261 | =head2 Not So Pretty XML | ||||||||||||
| 262 | |||||||||||||
| 263 | The XML produced by L<XML::LibXML> is not "pretty". If you need pretty XML you must pass the output through xmllint or a simular product. | ||||||||||||
| 264 | |||||||||||||
| 265 | For example: | ||||||||||||
| 266 | |||||||||||||
| 267 | perl -MGeo::GoogleEarth::Pluggable -e "print Geo::GoogleEarth::Pluggable->new->render" | xmllint --format - | ||||||||||||
| 268 | |||||||||||||
| 269 | =head2 Write Only | ||||||||||||
| 270 | |||||||||||||
| 271 | This package can only write KML and KMZ files. However, if you need to read KML files, please see the L<Geo::KML> package's C<from> method. | ||||||||||||
| 272 | |||||||||||||
| 273 | =head1 SUPPORT | ||||||||||||
| 274 | |||||||||||||
| 275 | DavisNetworks.com supports all Perl applications including this package. | ||||||||||||
| 276 | |||||||||||||
| 277 | =head1 AUTHOR | ||||||||||||
| 278 | |||||||||||||
| 279 | Michael R. Davis (mrdvt92) | ||||||||||||
| 280 | CPAN ID: MRDVT | ||||||||||||
| 281 | |||||||||||||
| 282 | =head1 COPYRIGHT | ||||||||||||
| 283 | |||||||||||||
| 284 | This program is free software licensed under the... | ||||||||||||
| 285 | |||||||||||||
| 286 | The BSD License | ||||||||||||
| 287 | |||||||||||||
| 288 | The full text of the license can be found in the LICENSE file included with this module. | ||||||||||||
| 289 | |||||||||||||
| 290 | =head1 SEE ALSO | ||||||||||||
| 291 | |||||||||||||
| 292 | L<Geo::KML>, L<XML::LibXML>, L<XML::LibXML::LazyBuilder>, L<Archive::Zip>, L<IO::Scalar> | ||||||||||||
| 293 | |||||||||||||
| 294 | =cut | ||||||||||||
| 295 | |||||||||||||
| 296 | 7 | 1; | |||||||||||