|
|
Report widget help page
Content
| Purpose |
| Use case |
| Installation |
| Report structure |
| Embedding images |
| Elevation profiles |
| Usage |
| Presentation of individual tracks |
| Style Sheets |
Purpose
The report widget automatically creates HTML pages from the data stored in GPX files. This way the GPS data itself and the tour description and other metadata are kept together. The effort for publishing GPS data is minimized. The only precondition is that the tour data must be stored on an Internet server in GPX format.
use case
Let us assume that you have created a GPX file and copied it to a folder called
tour folder on your favorite web server. Let us also assume that this
file contains references to images illustrating your tour. (Embedding images in GPX
files is described in section Embedding images.) Then all the
work on the content of your tour presentation is already completed.
All that remains to be done in order to present your tour to visitors of your homepage is to generate a link to the report application and include it somewhere in your homepage. This link must include the URL of your GPX file as a parameter. The link can be easily generated using the dialog on the service page. If a visitor clicks on this link, the html page generated by the widget is displayed. This page especially enables the visitor to download your file.
Figure 1: Usage of the report application
In this example the URL behind the great tour link might be:
http://www.fahrradspass.de/Report/index.jsp?task=report&url=http://www.your-domain.xy/tour-folder/your-file.gpx.
Please note that your data is only temporarily stored on the fahrradspass.de server, and only for the purpose of the report generation. It will never be transmitted to any other party.
If you should have access to a servlet engine you may also consider downloading the report application as a web archive and install it on your own web server. Der URL used to call the widget needs to be adapted accordingly in this case.
Installation
There is no need to install the widget at all. You might just use the link to the newest version as described above.
But you can download the WAR file report widget and install it on your own servlet engine. The installation procedure depends on the servlet engine provided by your internet provider. If tomcat should be used please, proceed as follows:
Figure 2: Start page of the tomcat manager application
Click on Choose file and navigate to the Report.war you have downloaded
before. Afterwards click on Deploy wait until the upload has finished.
Afterwards, the widget should be reachable via the following URL:
http://<your domain>/Report/index.jsp. In order to present an actual GPX file
a few additional parameters need to be provided as described in the next section.
Usage
The report widget is embedded into a HTML page via an anchor (a) element, as shown in the following
example:
<a href="http://localhost:8080/Report/index.jsp
?task=report&url=http://www.fahrradspass.de/Touren/BonnKoeln/BonnKoeln.gpx
&style=http://www.fahrradspass.de/Touren/style/homepage.css"
target="_blank">Bonn - Köln</a>The two URLs which are passed as parameters to the widget are "URL encoded". You can generate such an anchor element for your own file using the form shown on this page.
The widget is called with the following parameters:
| Parameter | Description | Value range | Optional |
task |
Fixed parameter | "report" | No |
url |
URL of the GPX file to be displayed | Any valid URL | No |
style |
URL of the Cascading Style Sheet to be used | Any valid URL | Yes |
Report structure
A GPX file consists of metadata, waypoints, routes, and tracks. (See also the documentation of the GPX standard.) The report structure generated by the widget corresponds to this definition. The report contains a Google map as an additional element. The following figure shows the layout of the GPX file content on the HTML page created by the widget:
)
Figure 3: Structure of the HTML page created by the widget
If the GPX file contains one or more keywords these are copied to the HTML meta element
keywords. This is useful to help search robots like GoogleBot find your file.
Embedding images
The widget interprets the content of every desc element as HTML markup. This way
it is possible to add images to your descriptions. The img element may be used for
this purpose. The URL of the image needs to be specified as src attribute in this
case. Please have a look at the following example of a desc element:
<p>At the end of the tour we arrive at a bird farm …</p>
<p><img src="http://www.fahrradspass.de/Touren/BonnRemagen/155434AA_Thumb.jpg"
alt="A bird" /></p>Relative URLs
In this case the widget will display the image of the bird. In order to avoid long and cumbersome
URLs as attribute values relative URLs can be used as well. Relative URLs always refer to the URL of
the GPX file to be displayed. Let us assume that your images are located in the same folder as the
GPX file itself on the server: http://www.fahrradspass.de/Touren/BonnRemagen/. Then the
following version of a desc element can be used:
<p>At the end of the tour we arrive at a bird farm
…</p><p><img src="/155434AA_Thumb.jpg" alt="A bird" /></p>Important: Every relative URL must either start with a slash ("/") or with two
dots (".."). Otherwise, the widget will interpret it as absolute URL. The slash denotes
the path of the GPX file. Two dots denote the next higher level in the directory structure on your
server.
It should be mentioned that the use of relative URLs also has a disadvantage: In this case the Editor application is not able to display the images.
Large images
For web pages it is important to keep their loading times low. Therefore only small images should be directly embedded into description elements. A typical image size should not exceed about 100 kB. Large images can be displayed using a built-in script which can be invoked as follows:
<p>At the end of the tour we arrive at a bird farm …</p>
<p><a href="javascript:displayPhoto('/155434AA.jpg')"><img
src="/155434AA_Thumb.jpg" alt="A bird" /></a>The text displayed by the widget now contains the small thumb-nail image. Clicking on the thumb nail opens a separate window showing the single higher resolution image.
Elevation profiles
For every track contained in your GPX file the widget generates an elevation profile which is displayed together with the track. If the track should include elevation information this data is used. The elevation data is downloaded from the GoogleMaps server, otherwise:
Figure 4: Example elevation profile. A green marker is shown in the Google map if the mouse hovers the profile.
Presentation of individual tracks
It is also possible to display an individual track contained in a GPX file. For this
purpose page displayTrack.jsp can be called directly as shown below:
<a href="http://www.fahrradspass.de/Report/displayTrack.jsp
?url=URL of your GPX file[&name=track name][&number=track number]" />
link text</a>Both, track name as well as track number are optional corresponding to the GPX standard. If you only specify the track name/the track number the application looks up the track having the specified name/number and no number/name. So, if the track to be presented should have a name as well as a number both parameters need to be specified. If neither a name nor a number are passed the application tries to select the first track having neither a name nor a number.
All parameters should be URL-encoded.
Style Sheets
The appearance of the report is controlled by a Cascading Style Sheet. Here is the Style Sheet used by default. (Right click the link and select something like "Save target…")
/*--------------------------------------------------------------------------*/
/* Cascading style sheet for the Report widget */
/*--------------------------------------------------------------------------*/
body {
background-color:white;
font-family:'Verdana';
font-size:small;
}
a:link {color:#CC0033;}
a:visited {color:#CC0033;}
a:active {color:#CC0033;}
h1 {color: #333399;}
h2 {color: #333399;}
h3 {color: #333399;}
ul {margin-top:5px; margin-bottom:10px;}
ol {margin-top:5px; margin-bottom:10px;}
li {text-align:justify; padding-top: 5px;}
img {border: 0;}
/*--------------------------------------------------------------------------*/
/* Tables */
/*--------------------------------------------------------------------------*/
table {border-collapse:collapse;}
td {
border-bottom:thin solid black;
padding-left:10px;
padding-rigth:10px;
padding-top:5px;
}
td.noFrames {border-style:none; vertical-align:top;}
p.table {margin-top:3pt; margin-bottom:0px;}
/*--------------------------------------------------------------------------*/
/* End of file */
/*--------------------------------------------------------------------------*/
You can make the widget use your own style sheet by setting the style parameter to the
URL of your sheet. Please always use the complete URL (i.e. http://host/directory/sheet.css).