Map

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.

Inserting the Map server control onto a page

Prerequisite

You must have installed the server controls. See Installing server controls into Visual Studio Toolbox.

  1. In Visual Studio, choose View > Toolbox.
  2. Click the Ektron server control tab to display the server controls.
  3. Drag the Map server control and drop it into the desired location on the page.

    NOTE: You also can place the cursor on the page where you want the server control, then double click the server control that you want.

    <CMS:Map ID="Map1" runat="server" />
  4. Click on Map in the code to display and modify the control’s properties using the Properties window of Visual Studio. The page is updated as you modify the property values.

Map 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.

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

Troubleshooting

  • If Map does not render on Web page, change the VirtualEarthMap web.config element as follows: 
    <add key="VirtualEarthMap" 
  value="https://dev.virtualearth.net/mapcontrol/
  mapcontrol.ashx?v=6.1&amp;s=1" />
  • If a user must click a warning away before users can see map on page, upgrade Google Maps to a premier subscription. For more information, see Google Maps for Business.

The following are Ektron-specific server controla server control uses API language to interact with the CMS and Framework UI to display the output. A server control can be dragged and dropped onto a Web form and then modified. properties. For information about native .NET properties such as font, height, width and border style, use 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.

  • 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.

    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. 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.

  • 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 taxonomya content-level categorization system that uses one-to-many relationships (such as Ronald Reagan is to Actor, Governor, and President) to create a scalable organization of content. A taxonomy lets your site visitors navigate content independent of the folder structure. 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: .

  • 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 taxonomya content-level categorization system that uses one-to-many relationships (such as Ronald Reagan is to Actor, Governor, and President) to create a scalable organization of content. A taxonomy lets your site visitors navigate content independent of the folder structure. 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 pop-up 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 (.ekml) that controls the display of this server control. To use the default .ekml file, leave this field blank.

    The default file follows this pattern: \siteroot\Workarea\template\this object\objectname.ekml. For example, \siteroot\Workarea\template\collection\collection.ekml.

    To customize the default .ekml file, copy it to a folder outside the siteroot\workarea folder and edit it. Next, in this property, enter the path to that file relative to the site root folder.

    See also: Ektron Markup Language

    See also: 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: . 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 ). 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: . 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. Leave blank to use the default style sheet. To use a custom style sheet, place it in a folder outside the siteroot\workarea folder then edit it. Next, in this property, enter the path to the custom style sheet relative to the site root folder.

    NOTE: 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.

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 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:

  • view content to which the location is assigned
  • find the distance to a location
  • center the map on a location
  • get directions to a location

  • 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 website. 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.

Bubble information:

  • Title. Content that corresponds to the numbered map location. Click the title to proceed to that content on your website.
  • 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.

Ektron supports 2 map providers: Google maps and Bing maps.

Configuring Google maps

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

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 Google Maps/Google Earth APIs Terms of Service.

  1. Go to Google APIs.
  2. Log into (or create) a Google account.
  3. Click Services from the left navigation panel.
  4. Enable Google Maps API v3.
  5. Click API Access from the left navigation panel.
  6. Click Create new Server key...

  7. Enter 1 or more server IP addresses and click Create. A key is created for server apps and browser apps (such as AIzaSyBcN7RJzxr4f-iOOfdMwUq9op-5xrtOh4M).
  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 following localhostkey with the key you obtained in Step 7.
    key="AQWESyCAtPrvLE6I2RTS7xK1-3btrrTO0eO6543"/>

Configuring Bing maps

Follow these steps to use Bing Maps with the Map server control.

  1. Obtain a Bing Map API key (https://www.bingmapsportal.com/).
  2. Insert the API key in web.config.
    <add key="BingMapsAPIKey" value="nnnnnnnnnnnnnnnnnn"/>

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.

To learn about customizing the display using the Ektron Markup Language, see map.ekml.

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

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

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.

NOTE: To enable the emailing of directions for Bing maps in 9.10 and up, you must configure the system email and SMTP settings. See also: Enabling Email Notification

Restricting locations to taxonomy categories

If you use Ektron’s taxonomya content-level categorization system that uses one-to-many relationships (such as Ronald Reagan is to Actor, Governor, and President) to create a scalable organization of content. A taxonomy lets your site visitors navigate content independent of the folder structure. 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 Organizing Content with Taxonomies.

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.

Displaying/suppressing map elements

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

  • Tabs/Search box. GeoControl
  • Text box. DisplayTextResult
  • Zoom/direction. ZoomControl; for Bing Maps in 9.10 and up, or 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

Because the map only displays content whose address lies within the map’s boundaries, focus the initial display on your businesses/locations. Map 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

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 Configuring 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 servicesEktron Windows Service uses Windows Web Services to perform these activities: • Schedules the future publication and removal of content. • Transmits notifications that a sync should be started between the staging and production servers. • In the 3-Tier feature, transfers data between servers. 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

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.