Mapplet Requirements

As is typical with software requirements, the mapplet requirements are a mixture of high- and low-level functional requirements and ad-hoc implementation details.

Normally, you try to keep design and implementation details out of the requirements. However, with this example, the project is extending an existing website using an existing technology (ArcGIS Server). Therefore, the design is constrained by the website that the project must fit into, and some of the requirements are about how the product should leverage ArcGIS’ out-of-the-box functionality. So (within reason) it’s important to include some of these design details in the requirements.

The complete set of mapplet requirements is shown in the “Mapplet Requirements” sidebar. We’ve presented these requirements exactly as they were written for the project; there’s been a small amount of tidying up and reformatting, but the essence is basically the same.

MAPPLET REQUIREMENTS

1. ArcGIS Server will be used to create a set of one or more Java applets that may be hosted on web pages within VResorts.com.

2. The applet(s) will provide map-based capability to locate and reserve hotels online within the US.

   2.1  

   Within the US, hotels will be displayed on the ??? base map.

   2.2  

   When loaded on a web page, the applet will read in its initial Region Of Interest (ROI) coordinates from an external source, which may be specified on the HTML of that web page or from the web page itself. The applet will access a hotel database that contains geocoding/location information for hotels, and use this information to locate and display hotels on the map.

   2.2.1  

   Hotel database format. The hotel database is provided as a comma-separated flat file with the following fields:

    id, brand, name, address1, address2, city, state, country, zip, latitude,  longitude, phone, online_bookings, hotrates, video, brochure, overview, map,  price_band, star_rating, amenities 

   An example record (4-star hotel in Luxury price band) follows:

    10204567,HY,Park Hyatt Washington,24th & M Street NW 1201 24th  Street,,Washington,DC,US,20037,38.897500,-77.050700,202-789-1234,Y,N,N,N,Y,Y,L  ,4,128 106 100 104 107 113 125 134 115 126 108 114 132 121 123 117 120 111 129  135 109 130 118 124 

   2.3  

   Users will have the option to modify the active ROI by panning and zooming in or out.

   2.4  

   The applet will provide a variety of display options to the user, which will result in icons that represent hotels within the active ROI being displayed on the map.

   2.4.1	Display any combination of price band searches from the sets “Luxury,” “Upscale,” “Midrange,” and “Economy.” Different icons will be used to represent each price band.
   2.4.2	Display the “Star Rating” of the hotels next to the hotel icons, either based on the zoom level or upon mouse rollover.
   2.4.3	Display the Names of the hotels next to the hotel icons, either based on the zoom level or upon mouse rollover.
   2.4.4	[Optional] The applet will access the reservations database dynamically using an XML interface to determine rates and availability for a given date range, and display this information on the map. 2.4.4.1   [Optional] “Specify date range using calendar”: The applet will provide a visual calendar-based interface for specifying date ranges.

   2.5  

   “Find hotels near address”: The applet shall provide the ability for the user to type in an address and display hotels on a map within some distance of that address. The default distance will be a 5 mile radius.

   2.5.1  

   The applet will provide the user the ability to change the distance for “nearby hotel” display.

   2.6  

   “Find hotels by zip code”: The applet will provide the ability for a user to enter a zip code, and will display hotels within that zip code and all immediately adjoining zip codes on a map.

   2.7  

   “Search by city”: If the user clicks on the name of a city on the map, the applet will set the active ROI appropriately to that city’s boundary and display a map showing all hotels within the price bands specified in 2.4.1.

   2.8  

   “Search by state”: If the user clicks on the name of a state on the map, the applet will set the active ROI appropriately to that state’s boundary and display a map showing all hotels within the price bands specified in 2.4.1.

   2.9  

   “View hotel information”: If the user clicks a hotel icon on the map display, the applet will display a new browser window containing the hotel’s detailed information.

   2.9.1  

   Syntax for accessing hotel information: The applet will construct a URL to access hotel information according to the following rules. The applet will display a brochure page if one is available, otherwise display a property overview page.

   2.9.1.1	Prefix: The URL shall begin with the string “http://reservations.vresorts.com/hotel/10004663-”.
   2.9.1.2	Property ID: The applet shall look up the hotel’s property ID in the database. An example property ID is “10215820”. The property ID is concatenated to the prefix.
   2.9.1.3	Suffix: “O”, “B”, “V”, or “M” .html. The string “O.html” results in the display of a property overview page when concatenated to the prefix and property ID. The string “B.html” results in the display of a property brochure page when concatenated to the prefix and property ID. The string “V.html” results in the display of a hotel video when concatenated to the prefix and property ID. The string “M.html” results in the display of a hotel map page when concatenated to the prefix and property ID.
   2.9.1.4	[Optional] Right-click options. The user may right-click on a hotel icon and get a popup menu that provides options to display Overview, Brochure, Video, and Map pages if available for a given property. The user may also choose to check rates and availability from this menu, using the XML interface.

   2.10  

   Filter hotels displayed by available amenities: The applet shall provide the capability to filter hotel searches via the selection of a set of amenities from a set of check boxes on a dialog box. For example, the user may choose to show only hotels with spas and pools. These filter selections will apply to all hotel/map displays above.

3. The applet(s) will provide map-based capability to locate and reserve hotels online outside of the US. Most hotels outside of the US are not geocoded, and therefore the applet will behave differently outside the US.

   3.1  

   Outside the US, the data used should be vendor neutral.

   3.2  

   When loaded on a web page, the applet will read in its initial Region Of Interest (ROI) coordinates from an external source, which may be specified on the HTML of that web page or from the web page itself.

   3.3  

   Users will have the option to modify the active ROI by panning and zooming in or out. This will cause country and city names to appear on the map.

   3.4  

   Search by country/city: When the user clicks on the name of a country or city on the map, a database query is generated in the form of a URL. The result set of the query is displayed in a new window.

   3.4.1  

   Database query syntax: The query URL is a string composed of the following elements: Prefix, Country, City, and Sort Order.

   3.4.1.1	Example: The following URL returns a list of hotels in Mazatlan, Mexico, sorted by star rating: http://reservations.vresorts.com/nexres/search/power_results.cgi?src=10004663&la ng=ENG&country=MX&city=MAZATLAN&sort_order=Stars
   3.4.1.2	Prefix: All search URLs will begin with the prefix http://reservations.vresorts.com/nexres/search/power_results.cgi?src=10004663&la ng=ENG

   3.4.2.2	Country Codes. A list of 2-character country codes will be provided in a separate document. In the example above, MX is the code for Mexico.
   3.4.2.3	City name: The city name is read from the base map and added to the search query. For cities with names separated by spaces, the names are concatenated together using a “+”. For example: “&city=PUERTO+VALLARTA” will return hotels in the city of Puerto Vallarta.
   3.4.2.4	Sort Order: If left blank, the hotel database returns an alphabetic sort by hotel name. This applet will use the “sort by star rating” option, which is the string “&sort_order=Stars” concatenated to the Prefix, Country, and City.

An example of how we’ve left the original style/formatting in the preceding requirements is the way in which the requirements meander from formal “the system shall” wording to brief, informal note form. This is an important agile principle: if the customer is happy with this form of requirements, then we can save a lot of time by not having to dot every “i” and cross every “t.” Whatever gets the point across. The requirements aren’t the finished product, and they’re not the goal in themselves—they just describe the goal, so we shouldn’t spend ages perfecting them.

You’ll also notice that the requirements talk about “applets” rather than “mapplets,” because the original idea was to create a Java applet to perform the map-based hotel search functions. This was partly because the customer’s website already has a hotel search applet that the new system will replace. However, it was soon decided that a web-based user interface (making heavy use of DHTML in the browser) would be more suitable, so the mapplet was born.

At this stage, we haven’t decided which requirements will go into which release. Once we’ve done a small amount of initial use case modeling (where the use cases are derived from the requirements), we’ll prioritize the use cases and divide them into different releases (we show this process later in this chapter). Further into the project, new requirements will be added and some of the existing requirements will change (or they’ll be dropped altogether). It’s a fluid process, but it’s still important to get the requirements written down so that we have a baseline from which to work.