Trip Configuration File

back to index

The data about each trip is stored in a single trip configuration file. All these files are located in a single directory that is specified by the global configuration file. Any XML file that appears in that directory is processed as if it was a trip file. Also, changes made to trip files are reloaded automatically, so there is no need to stop the application at any point in order to perform changes.

The next listing illustrates an example outlined configuration file.

trip_config.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE trip PUBLIC "http://www.ahristov.com/uri/jpblog-trip/1.0" "trip.dtd" >
<trip 
  default-language="es"
  map="/trips/maps/europa.gif"  
  photo="DSC04145.JPG"
  order="43"
  license="http://creativecommons.org/licenses/by-nd/2.5/">
  
  <title lang="es">2006 - Sur de Europa</title>
  <title lang="en">2006 - Southern Europe</title>
  
  <url-alias>2006-Sur de Europa</url-alias>    
  <url-alias lang="en">2006-Southern Europe</url-alias>      

  <trip-leg 
    x="196" 
    y="205" 
    path="/trips/2006/martigues"
    photo="DSC03736.JPG" 
    longitude='5.05484' 
    latitude='43.40738'
    michelin-data="-tyc9poxugg7d0o"
    from="2006-07-22" to="2006-07-22"   >
    
    <title>Martigues</title>
    <title lang="en">Martigues</title>    
    <include-url lang="es" src="/trips/2006/martigues/comment_es.jsp" />
    
    <photo src="DSC03736.JPG" >
      <descr>Puerto de Martigues</descr>
      <descr lang="en">Port of Martigues</descr>
    </photo>
    
    <clip src="MOV04421.MPG">
      <descr lang="es">Monje pintando un nuevo icono</descr>
      <descr lang="en">A monk painting a new icon</descr>
    </clip>
    
  </trip-leg>  
  
  ...
</trip>

The first element of the file is the trip element, which contains the following attributes:

default-language. Specifies the default language to use when a photograph or a clip does not specify a description in the language the user is requesting. This attribute is optional, if omitted, then the global default language (specified in the global configuration file) is used.
map. Specifies the trip map to use. Optional. If not present, no map is displayed. The path is relative to the root of the web site (web application)
photo. Specifies the photo to use as representative of the trip, when displaying the trip index. This attribute must contain the name (not path) of a single photograph.
license. Specifies the license that apply to all photographs and legs that don't have a specific license. The value must be an URL that contains the text of the license.
skin. Specifies the skin name to use for this trip. If this attribute is not present, the globally defined default skin is used.
order. Optional. Specifies the order of this trip within the trip list. Trips with a lower order nunmber are listed before those with a higher order number.

Inside the trip element, we can have a set ot titles and url-aliases. The url-alias element specifies the URL used to access the locations of the trip (see the section about URL handling for more information), whereas the title element simply specifies a descriptive title of the trip. If the url-alias is missing, it is assumed that it is equal to the title.

The lang attribute indicates for which language the description or url applies. If the attribute is missing, the default language is assumed. The lang attribute may also be set to the special literal "any", which means that the description or url is valid for any language.

Trip legs (locations)

Each trip is composed of a series of trip-leg elements. There must be at least one such element per trip. A trip-leg describes a specific location that you visited. It has the following attributes:

x,y - Optional attributes that indicate the coordinates of the location on the trip map. See the section "trip maps" for more information about this.
path - Required attribute that specifies the location where all media items (photographs, movie clips, etc..) are stored. Thumbnails will also be stored there. The path is relative to the root of your web application.
photo - Optional attribute specifying the name (not path) of the photograph to use as a "title photograph" for this trip-leg. This is usually a vey representative photograph of the location. If the attribute is missing, the first photograph of the trip leg is used.
longitude, latitude, altitude - Optional attributes that indicate the position of the location in world coordinates. Used for google maps. Longitude and latitude are expressed in degrees. East longitudes and North lattiudes are considered positive, while West longitudes and South latitudes are considered negative. Altitude is expressed in meters and it is currently not used.
michelin-data - Optional attribute specifying the Id of the michelin map to display. See the FAQ for information about how to get this value..
from,to - Period during which you visited this location. Both attributes are optional, and if present must represent a date in YYYY-MM-DD format.
skin. Optional. Specifies the skin name to use for this location. If this attribute is not present, the skin specified for this trip is used, and if that skin is also unspecified, the globally defined skin is used.

Just as the trip itself, each trip leg has a set of titles and url-aliases, obeying the same rules and conventions as those present in the trip, but applying only to this specific trip leg. In the above example, the only trip-leg of the trip has a title (in english) of "Martigues", and a title (in the default language) of "Martigues". Since no url-alias elements are present, the url aliases are assumed to be equal to the titles.

Media Items

Each trip leg can have as many "media items" as necessary, which are displayed in the same order in which they are present in the file. Currently, two media items are defined : photo - representing a photograph and clip - representing a video clip.

All media items have a required attribute called src that specifies the name of the file containing the media item. That file must be located in the directory pointed to by the path attribute of the corresponding trip leg.

Also, a media item can have (but it is not required to) a set of descriptions using the descr element.

Included and displayed pages

When the user chooses to view the contents of a location or trip leg, three possible things can happen:

In absence of further information, JPBlog will display the standard "trip leg view" (which is by default called leg.jsp, but this can be altered in the global configuration file).This standard page displays a google map and a michelin map (if enough data is given), and a paged album with clickable thumbnails. Under each thumbnail the description of the photograph is shown.

Sometimes, however, you want more information to be displayed about a location. See this example in which I rant about the ancient city of Olympia. It's in spanish, but the language is not important. The important thing is that there is a lot of text with images before the album with thumbnails. This effect can be achieved by adding include-url elements right after the titles and url-aliases of a trip leg. Each include-url element specifies a page to be INCLUDED in the standard view, and two attributes are required : lang, which specifies the language for which this include applies and src, which specifies the location of the included page, relative to the context root of your web application.
Finally, there are times when you want complete control over what's shown - when you wish for example to show only a handful of photographs but intermixed with your own text. You can achieve this effect by adding view-url elements right after the titles and url-aliases. A view-url element (which also has the lang and src attributes) specifies the page that will be shown when the user chooses to view this trip leg. In this case, the standard trip leg view is not used. It is not allowed to have both a view-url and an include-url for the same language, as this would make no sense : either the standard view is used, or it isn't.