Using the Map Server Control

The Map server control displays a map that flags locations of interest. Each location is an Ektron content item to which map information was added. For example, if your site hosts a school district, each location could represent one school.

You can zoom the map in and out, get directions to a location, and narrow the list of locations using a text search. For example, if your map initially flags all schools in a geographic area, you can redraw the map to show only schools with a gym.

If you want the map to show events, you can apply dates to Ektron content, which allows searching by date or location.

IMPORTANT: As a map’s boundaries change, only locations within the boundaries appear. Likewise, if a date is assigned to content, only content within the selected date range appears.

If a map has at least one flagged location, a box can appear to its right with information about each location, which are sorted by distance to starting location. From this box, you can:

  • No.—Map item number. The lowest numbered item is closest to the map’s center.
  • Title—The content that corresponds to the numbered map location. Click the title to access that content on your Web site. The text below the title is the Metadata Map Address field, followed by the Metadata Description field (see illustration below).
  • Distance—Distance from the map’s center to this content location.
  • Map—Click icon to recenter map on this content’s location.
  • Directions—Click icon to select the Directions tab and paste this content location’s address into the end location box. You could then enter a starting location to get directions to this location.

When you hover the cursor over a numbered map location, a text “bubble” appears.

The bubble shows the following information.

  • Title—The content that corresponds to the numbered map location. Click the title to proceed to that content on your Web site.
  • Summary—Value of the content’s Summary tab.
  • Metadata description—Value of the content’s Metadata Description field.
  • Get Directions—Click To Here or From Here to select the Directions tab and paste this location’s address into the To or From location box. Then, supply the missing location to get directions between locations.
Using maps on the sample site

Using Maps on the Sample Site

You can view maps on Ektron’s sample site. To do so, open the home page (http://your server address/siteroot/default.aspx). Then, choose Contact Information > Map VE or Contact Information > Map Google. If you want to work with these maps in VisualStudio.NET, the Bing Maps for Enterprise map is on the map.aspx page. The Google map is on mapgoogle.aspx.

Ektron provides a Google map key that you can use for testing on localhost. But, if you want to use Google map with your production server, you must install a license key.

Obtaining a license to use Google maps

Obtaining a License to Use Google Maps

Before your production server can use Google’s map feature, follow these steps to obtain and install a license key. For Google Map’s terms and conditions, see http://code.google.com/apis/maps/terms.html

  1. Go to http://www.google.com/apis/maps.
  2. Click Sign up for a Google Maps API key.
  3. Read the terms and conditions. At the bottom of the page, check the box I have read and agree with the terms and conditions.
  4. Enter your URL in the My web site URL: field. For example, http://www.example.com/maps.

    WARNING! A single Maps API key is valid for a single “directory” on your Web server. If you sign up for the URL http://www.example.com/maps, the key is good for all URLs in the http://www.example.com/maps/ directory.

  5. Click Generate API Key.

  6. You are asked to sign in to Google. If you don’t have an account, create one.
  7. A new page appears with your license key at the top. Copy the key.

  8. Without closing that page, open the site root/web.config file.
  9. Go to the line that begins <add key="GoogleMap".
  10. Within that line, replace the localhost key (shown below) with the one copied in Step 7.
    key=ABQIAAAAKS0eaO74jIASu1UolJlxPRQAPC5zwhKxdscXMmLMOnW7z2LmSRQrVhfXVp1hq2cv_ZsOvqP4GQ69eg"/>
Controlling the map experience

Controlling the Map Experience

NOTE: Within Visual Studio, you cannot see the map in design mode. But, you can right click the mouse and select View in Browser to see the effect of changing properties in a browser.

For information on customizing the display using the Ektron Markup Language, see map.ekml.

Recentering the map

Recentering the Map

The Search tab lets you recenter the map on a location. You can enter a combination of street address, city, state and zip code and click Search. Only content within that geographic area which satisfies other search criteria appears.

Finding locations with a search term

Finding Locations with a Search Term

You can use the Find What tab to find only locations that include a search term. For example, if a map flags hotels, you can click the Find What tab then insert pool in the text box above to view only hotels with a pool. The Find What tab uses the same logic used in the Web Search to find content on your site.

Getting directions

Getting Directions

Use the Directions tab to get directions between 2 locations. Enter a combination of street address, city, state, and zip code into both text boxes above the tabs and click Get Directions. The screen displays text directions on the left, and a map of the directions on the right.

Restricting locations to taxonomy categories

Restricting Locations to Taxonomy Categories

If you use Ektron’s taxonomy feature to classify mapped content, you can click Display on Map to restrict the map’s locations to content in your categories. The popup window also prompts you to select one or a range of dates, and only retrieves content to which one of the selected dates is assigned.

For example, the category Restaurant has 5 subcategories in Ektron’s sample site.

When you use the map, you can click Display on Map, see your content’s categories, and select those of interest. The map updates to show content in selected categories only. To learn about assigning taxonomy categories to content, see Taxonomy .

NOTE: While an OR logical relationship among selected categories is the most intuitive and common, you can set up AND or NOT relationships among categories. See SelectedCategoryLogicalType (LogicalType)Use this property to determine the logical relationship among several categories on the Display on Map tab. (See ”The Display on Map Button” on page 9-324). There are 3 choices: OR, AND, and NOT.By default, an OR relationship exists among your selections. So, for example, if all 3 Restaurant categories are checked, then any restaurant that is defined as American, Chinese or Pizza appears on the map. If you change this property’s value to AND, only content to which all selected categories apply appear on the map. In the above example, only restaurants defined as American and Chinese and Pizza appear on the map. Alternatively, you can set the property’s value to NOT. In this case, only content to which the selected categories are not applied appear on the map. To continue the above example, if you select Chinese, only restaurants that are not assigned the Chinese category appear on the map..

Displaying/suppressing map elements

Displaying/Suppressing Map Elements

You can use Map server control properties to display or suppress the following map elements.

  • Tabs/Search box—GeoControl
  • Text box—DisplayTextResult
  • Zoom/direction—ZoomControl; for Bing Maps for Enterprise maps, this property also controls the Map type selection.
  • Map type (road, satellite, combination)—TypeControl; affects only Google maps.

Setting a map's initial boundaries

Setting a Map’s Initial Boundaries

Because the map only displays content whose address lies within the map’s boundaries, focus the initial display on your businesses/locations. Map server control properties let you specify a beginning address (or longitude/latitude) and a starting zoom level. All content with address data within that area is flagged on the map.

If your locations are too spread out to appear on a single map, create several regional maps. Each map server control must appear on a separate Web form.

IMPORTANT: You cannot place more than one map server control on a Web form.

Setting content found on a map

Setting Content Found on a Map

Whether you use Google or Bing Maps for Enterprise maps, content must have latitude and longitude values to appear on a map.

Google maps take a content item's address and return its latitude and longitude. You don’t need to use Google’s automatic retrieval of latitude and longitude. Instead, you can enter the values manually. To do so, open the content item, go to its metadata, and enter the latitude and longitude values under Search Data.

To automatically obtain latitude and longitude information for a content item:

IMPORTANT: The following procedure assumes you are using Ektron’s sample site. If you are using the Min site, you must create searchable metadata definitions for Map Address, Map Latitude and Map Longitude. When defining Map Latitude and Map Longitude, set their Style to Double. If you are using dates with metadata, set MapDate’s style to Date.

  1. Obtain a Google maps license key. See Obtaining a License to Use Google Maps
  2. Create the content if necessary. On the content’s Metadata tab, under Search Data, enter a MapAddress (that is, any combination of street, city, state, and zip code).

    If you enter only a zip code, the latitude and longitude are set to that post office.

  3. Publish the content.

    This action creates the Web Service call to Google maps, which retrieves the latitude and longitude for each address. If Google maps cannot find a latitude and longitude (usually due to insufficient or conflicting information), it writes failure information to your server. You can view this under Windows Event Viewer > EktronLog. Any event’s properties explain why the retrieval of latitude and longitude failed.

Restricting content for a particular map

Restricting Content for a Particular Map

You may want a map to show a subset of all content with a latitude and longitude. For example, your business includes restaurants and bakeries, and you want a map to show only bakeries.

To accomplish this, place content for restaurants in one folder, and bakeries in another. Then, in the map server control that shows bakeries only, at the FolderID property, identify the bakeries folder.

If you want another map to show both restaurants and bakeries, create the restaurant and bakery folders under a parent folder. Then, in that map server control’s FolderID property, identify the parent folder, and set the Recursive property to true.

Map server control properties

Map Server Control Properties

Within Visual Studio, you cannot see the map in design mode. However, you can right mouse click the mouse and select View in Browser to see the effect of changing the properties.

IMPORTANT: You cannot place more than one map server control on a form. Also, see the following troubleshooting tips:

The following are Ektron-specific server control properties. You can find information about native .NET properties such as font, height, width and border style in Visual Studio® help.

  • Address (String)

    To set a default map center, enter its address. The address appears in the Search field when the map first displays. If you only enter a zip code, the map centers on its post office. If you enter an address, the latitude and longitude properties are ignored.

  • Authenticated (Boolean)

    Indicates if you are logged into the CMS Explorer and can use it to browse to content, collections, and so on. See Also: Browsing Your Ektron Site Using CMS Explorer.

  • ContentId (Long)

    Use this field in conjunction with the EnableSearchResult field to limit the map to a single content item. Here, you identify the content item to be mapped. Content must have latitude and longitude values to appear on a map.

  • CustomIcon (Boolean)

    Use this field if you want the Category popup box to display an icon to the left of each category, as shown below.

    Prerequisite: To use this value, open the webroot/Workarea/images/application/maps/tree folder. In that folder, create a new folder whose name is the same as the Taxonomy category assigned to the Map server control at the MapCategory property. In the sample site, this Taxonomy’s name is MapCategory. Then, place the icons in that folder by category title name with a .png extension. Use an underscore (_) to separate taxonomy levels. For example, the image for the category Restaurant > American must be named Restaurant_American.png.

  • DateSearch (Boolean)

    Set to True to assign a date to content. This feature is helpful for date-related content, such as concerts, meetings, or sporting events. You can filter what appears on the map by date. If you set this property to true, assign a date to date-related content using the MapDate standard metadata field. Then, publish the content. When you click a map’s Display on Map button, the popup screen includes date criteria, as shown below. See Also: Restricting Locations to Taxonomy Categories. You can select map items by a single date or a range of dates.

  • DisplayTextResult (Boolean)

    If you want to display a box of information about each map item to the right of a map, enter True. To suppress the text box, enter False. See Also: Displaying/Suppressing Map Elements

  • DistanceUnit (Unit)

    Enter the map's units of distance. Choices are miles and kilometers. The default value is miles.

  • DoInitFill (Boolean)

    By default, Fill occurs during the Page_Init event. Set to false if you want to postpone the fill-action until later. In this case, Fill is automatically called during the Page Render event. You might do this if you need to set or change a property on the control in code-behind and have it render with your changes shown.

  • EnableSearchResult (Boolean)

    Use to determine if the Map server control accesses the Ektron search to return results. True is the default value. You would change it to False if you want to display a map with only one content item, that is, a single location. Specify this item at the ContentID property. In this case, the map does not find other Ektron content whose longitude and latitude are within the map’s boundaries. Site visitors viewing the map can still use the Search and Directions tabs to get directions to the location. For example, your site features homes for sale, and you want a map to show a featured home of the week. To do so, set this property to False, and enter the content that describes that home in the ContentID field.

  • FolderId (Long)

    Enter the ID number of the folder whose content is searched on this map. If the recursive property is true, folders below this folder are also searched.

  • ForceCategory (Boolean)

    When set to true, this property causes the map to only show content associated with the taxonomy category defined in the MapCategory property. When set to false, the map shows all content within the map’s boundaries. For example, if 5 content blocks appear on a map and 3 are assigned to a taxonomy, set this property to True and the MapCategory property to the ID of the taxonomy. When a user views the map, it displays the 3 content items associated with the taxonomy.

  • GeoControl (Boolean)

    If you want to see a search box with tabs above a map, enter True. To suppress the text box, enter False. See Also: Displaying/Suppressing Map Elements

  • Hide (Boolean)

    Hides or displays the output of the control in design time and run time.

    • True—Hide the control output.
    • False—Display the control output.
  • Language (Integer)

    Set a language for viewing content; shows results in design-time (in Visual Studio) and at run-time (in a browser).

  • Latitude (Decimal)

    To set a default map center via latitude and longitude (as opposed to an address), enter the latitude here.

  • Longitude (Decimal)

    To set a default map center via latitude and longitude (as opposed to an address), enter the longitude here.

  • MapCategory (Long)

    Enter the ID number of the taxonomy whose categories appear when up click this map’s Display on Map button. When a map first appears, all eligible content appears. If you click Display on Map, you can choose categories and limit the map to items assigned to them. For example, you could view restaurants only. As another example, a map could initially display all campuses in your state college system. Use the Display on Map popup window to limit the map to community colleges.

    While an OR relationship among categories is the most intuitive and common, you can set up an AND or NOT logical relationship among selected categories.

  • MapProvider (Provider)

    Select the service that provides the map, either Google or Bing Maps for Enterprise.

  • MapStyle (Style)

    Enter the map’s display mode: Road, Satellite or Hybrid. This setting only affects Bing Maps for Enterprise maps.

  • MarkupLanguage (String)

    Enter the template markup file that controls the map page display. For example, mymapmarkup.ekml. If you enter no EkML file, the default one at Workarea\Template\map\map.ekml is used. If the *.ekml file is located in the \workarea\template\map folder, just enter its name. If the file is in another folder, enter the path relative to site root. For example, \workarea\customfiles\markup\mymapmarkup.ekml See Also: Controlling Output with Ektron Markup Language and map.ekml

  • MinZoomLevel (Integer)

    If you want to set a map zoom level below which map locations will not appear, enter that value. The default value is 4. Possible values are between 1 (most detailed) and 19.

  • PageSize (Integer)

    Enter the number of locations that can appear on one page of the text box after a search is executed. See Also: Displaying/Suppressing Map Elements. If more than this number of locations are available, use [First] [Previous] [Next] [Last] at the bottom of the page to view additional locations.

  • Recursive (Boolean)

    In the FolderID property, you specify a folder whose content is searched on this map. To extend the search to all folders below this folder, set this property to true.

  • SelectedCategoryLogicalType (LogicalType)

    Use this property to determine the logical relationship among several categories on the Display on Map tab. (See Restricting Locations to Taxonomy Categories). There are 3 choices: OR, AND, and NOT.

    By default, an OR relationship exists among your selections. So, for example, if all 3 Restaurant categories are checked, then any restaurant that is defined as American, Chinese or Pizza appears on the map. If you change this property’s value to AND, only content to which all selected categories apply appear on the map. In the above example, only restaurants defined as American and Chinese and Pizza appear on the map. Alternatively, you can set the property’s value to NOT. In this case, only content to which the selected categories are not applied appear on the map. To continue the above example, if you select Chinese, only restaurants that are not assigned the Chinese category appear on the map.

  • StartZoomLevel (Integer)

    Enter the zoom level at which the map initially appears. See Also: Setting a Map’s Initial Boundaries. Zoom level 1 is the least detailed, showing the entire world. Zoom level 19 is the most detailed, showing the smallest streets. By default, maps in the sample site have a zoom level of 12, which shows an area of about 10 miles (16 kilometers). A site visitor can adjust the level using the zoom control (circled below).

  • Stylesheet (String)

    Specify the path to a style sheet for use with this server control. The location can be relative or absolute. Leave blank to use the default style sheet.

    WARNING! If you enter a valid EkML file at the MarkupLanguage property, the Stylesheet property is ignored.

  • SuppressWrapperTags (Boolean)

    Suppresses the output of the span/div tags around the control.

    • True—Suppress wrap tags.
    • False (default)—Allow wrap tags.
  • TemplateParamName (String)

    Sets a QueryString parameter for the ID of users that are returned in the search results. This parameter is passed to the template page defined in the TemplateUserProfile property when a user clicks the Location (map) icon associated with a user.

  • TemplateUserProfile (String)

    The URL path of the user profile template. The path can be relative or absolute.

  • TypeControl (Boolean)

    If this map uses Bing Maps for Enterprise maps, this property enables or disables the zoom/direction/type control (highlighted below). It lets you zoom the map in and out, move the center in any direction, and change the display style (Road or Aerial).

    If this map uses Google Earth maps, this property enables or disables the type control (highlighted below). It lets you change the display style (Map, Satellite, or Hybrid). Use the ZoomControl property to display or suppress Google Earth’s zoom and direction controls.

  • WrapTag (String)

    Lets a developer specify a server control’s tag.

    • Span (default)—designate an inline portion of an HTML document as a span element.
    • Div—apply attributes to a block of code.
    • Custom—Lets you use a custom tag.
  • ZoomControl (Boolean)

    Use this property to display or suppress the Google map zoom control (highlighted below). For Bing Maps for Enterprise maps, the TypeControl property determines the zoom control display.