There are many possibilities of using Flash in a Joomla! website. In this article by Suhreed Sarkar, we will get familiar with how to use the YOS amMap extension to display interactive maps on your Joomla! website.

Showing maps using YOS amMap

Adding a map to your site may be a necessity in some cases. For example, you want to show the population of countries, or you want to show a world map to your students for teaching geography. Flash maps are always interesting as you can interact with them and can view them as you like. amMap provides tools for showing Flash maps. The amMap tool is ported as a Joomla! component by yOpensource, and the component is released with the name YOS amMap. This component has two versions—free and commercial. The commercial or pro version has some advanced features that are not available in the free version.

The YOS amMap component, together with its module, allows you to display a map of the world, a region, or a country. You can choose the map to be displayed, which areas or countries are to be highlighted, and the way in which the viewers can control the map. Generally, maps displayed through the YOS amMap component can be zoomed, centered, or scrolled to left, right, top, or bottom. You can also specify a color in which a region or a country should be displayed.

Installing and configuring YOS amMap

To use YOS amMap with your Joomla! website, you must first download it from http://yopensource.com/en/component/remository/?func=fileinfo&id=3. After downloading and extracting the compressed package, you get the component and module packages. Install the component and module from the Extensions | Install/Uninstall screen.

Once installed, you can administer the YOS amMap component from Components | YOS amMap. This shows the YOS amMap Control Panel, as shown in the following screenshot:

YOS amMap Control Panel displays several icons through which you can configure and publish maps. The first thing you should do is to configure the global settings for amMap. In order to do this, click on the Parameters icon in the toolbar. Doing so brings up the dialog box, as shown in the following screenshot:

In the Global Configuration section, you can enter a license key if you have purchased the commercial or the pro version of this component. For the free version, this is not needed. In this section, you can also configure the legal extensions of files that can be uploaded through this component, the maximum file size for uploads, the legal image extensions, and the allowed MIME types of all uploads. You can also specify whether the Flash uploader will be used or not. Once you have configured these fields, click on the Save button and return to YOS amMap Control Panel.

Adding map files

You can see the list of available maps by clicking on the Maps icon on the YOS amMap Control Panel screen or by clicking on Components | amMap | Maps. This shows the Maps Manager screen, as shown in the next screenshot.

As you can see, the Maps Manager screen displays the list of available maps. By default, you find the world.swf, continents.swf, and world_with_antartica.swf map files. You will find some extra maps with the amMap bundle. You can also download the original amMap package from http://www.ammap.com/download. After downloading the ZIP package, extract it, and you will find many maps in the maps subfolder. Any map from this folder can be uploaded to the Joomla! site from the Maps Manager screen.

Creating a map

There are several steps for creating a map using YOS amMap. First we need to upload the package for the map. For example, if we want to display the map of the United States of America, then we need to upload the map template, the map data file, and the map settings file for the United States of America. To do this first upload the map template from the Maps Manager screen. You will find the map template for USA in the ammap/maps folder. Then we need to upload the data and the settings files. For doing so, click on the Upload link on the YOS amMap Control Panel screen. Then, in the Upload amMap screen, which is shown in the next screenshot, type the map's title (United States) in the Title field. Before clicking on the Browse button besides the Package File field, you first add the ammap_data.xml and the ammap_settings.xml files to a single ZIP file, unitedstates.zip. Now, click on the Browse button, and select this unitedstates.zip file. Then click on the Upload File & Install button.

Once uploaded successfully, you see this map listed in the YOS amMap Manager screen, as shown in the next screenshot. You get this screen by clicking on the amMaps link on the toolbar.

As you can see, the map that we have added is now listed in the YOS amMap Manager screen. However, the map is yet in an unpublished state, and we need to configure the map before publishing it. We need to configure its data and settings files, which are discussed in the following sections.

Map data file

The different regions of a map are identified by the map data file. This is an XML file and it defines the areas to be displayed on the map. The typical structure of a map data file can be understood by examining ammap_data.xml. The file has many comments that explain its structure. This file looks like as follows:

<?xml version="1.0" encoding="UTF-8"?>
<map map_file="maps/world.swf" tl_long="-168.49" tl_lat="83.63" 
br_long="190.3" br_lat="-55.58" zoom_x="0%" zoom_y="0%" zoom="100%">
<areas>
  <area title="AFGHANISTAN" mc_name="AF"></area>
  <area title="ALAND ISLANDS" mc_name="AX"></area>
  <area title="BANGLADESH" mc_name="BD"></area>
  <area title="BHUTAN" mc_name="BT"></area>
  <area title="CANADA" mc_name="CA"></area>
  <area title="UNITED ARAB EMIRATES" mc_name="AE"></area>
  <area title="UNITED KINGDOM" mc_name="GB"></area>
  <area title="UNITED STATES" mc_name="US"></area>
  <area title="borders" mc_name="borders" color="#FFFFFF" 
balloon="false"></area>
</areas>
<movies>
  <movie lat="51.3025" long="-0.0739" file="target" width="10"
   height="10" color="#CC0000" fixed_size="true" title="build-in
   movie usage example"></movie>
  <movie x="59.6667%" y="77.5%" file="icons/pin.swf" title="loaded
   movie usage example" text_box_width="250" text_box_height="140">
   <description>
     <![CDATA[You can add description text here. This text will
      appear the user clicks on the movie. this description text can
      be html-formatted (for a list which html tags are supported,
      visit <u>
<a href="http://livedocs.adobe.com/flash/8/main/00001459.html">this
  page</a></u>. You can add descriptions to areas and labels too.]]>
   </description>
  </movie>
</movies>
<labels>
  <label x="0" y="50" width="100%" align="center" text_size="16"
     color="#FFFFFF">
  <text><![CDATA[<b>World Map]]></text>
  <description><![CDATA[]]></description>
</label>
</labels>
<lines>
  <line long="-0.0739, -74" lat="51.3025, 40.43" arrow="end"
      width="1" alpha="40"></line>
  </lines>
</map>

This code is a stripped-down version of the default ammap_data.xml file. Let us examine its structure and try to understand the meaning of each markup:

• <map> </map>: You define the map's structure using this markup. First, by using the map_file attribute, we declare the map file that should be used to display this map. This markup has some other attributes through which we declare the top and the left offset in longitude and latitude. We can also specify the zooming level using the zoom_x, zoom_y, and zoom attributes.
• <areas> </areas>: Areas are the regions or countries on a map. These are defined in the map. We only need to define the areas that we want to display. For example, in the sample, we have defined eight countries to be displayed and one straight line. Each area element has several attributes, among which you need to mention mc_name and title. You specify the area's name in mc_name, which is predefined in the map template. The title element will be displayed as the title of that map area. For example, <area mc_name="BD" title="Bangladesh"></area> means the areas marked as BD in the map template will be displayed with the title Bangladesh. In order to specify the mc_name element, you need to follow the map template designer's instructions.
• <movies> </movies>: Movies are some extra clips that can be displayed as a separate layer on the map. For example, to display the capital of each country, a movie clip could be displayed in the specified latitude and longitude. You can also display some other animations or text using a movie definition.
• <labels> </labels>: The <labels> markup contains the text to be displayed on the map. You can add any text on a map by defining a label element.

To view and edit the map data file, ammap_data.xml, click on the map name on the YOS amMap Manager screen. This opens-up the amMap: [Edit] screen, as shown in the following screenshot:

The amMap: [Edit] screen displays several configurations for the map. From the Details section you can change the map name, publish the map, and enable security. From the Design section you can view and edit the data and the settings files. Clicking on Data will show the data file. You can edit the data file from the online editor. As we want to display the map of USA, we will make the following changes on this screen:

1. Select usa.swf in the Maps list.
2. Change the data file as follows:

   <?xml version="1.0" encoding="UTF-8"?>
   <map map_file="maps/usa.swf" zoom="100%" zoom_x="7.8%"
   zoom_y="0.18%">
   <areas>
     <area mc_name="AL" title="Alabama"/>
     <area mc_name="AK" title="Alaska"/>
     <area mc_name="AZ" title="Arizona"/>
     <area mc_name="AR" title="Arkansas"/>
     <area mc_name="CA" title="California"/>
     <area mc_name="CO" title="Colorado"/>
     <area mc_name="CT" title="Connecticut"/>
     <area mc_name="DE" title="Delaware"/>
     <area mc_name="DC" title="District of Columbia"/>
     <area mc_name="FL" title="Florida"/>
     <area mc_name="GA" title="Georgia"/>
     <area mc_name="HI" title="Hawaii"/>
     <area mc_name="ID" title="Idaho"/>
     <area mc_name="IL" title="Illinois"/>
     <area mc_name="IN" title="Indiana"/>
     <area mc_name="IA" title="Iowa"/>
     <area mc_name="KS" title="Kansas"/>
     <area mc_name="KY" title="Kentucky"/>
     <area mc_name="LA" title="Louisiana"/>
     <area mc_name="ME" title="Maine"/>
     <area mc_name="MD" title="Maryland"/>
     <area mc_name="MA" title="Massachusetts"/>
     <area mc_name="MI" title="Michigan"/>
     <area mc_name="MN" title="Minnesota"/>
     <area mc_name="MS" title="Mississippi"/>
     <area mc_name="MO" title="Missouri"/>
     <area mc_name="MT" title="Montana"/>
     <area mc_name="NE" title="Nebraska"/>
     <area mc_name="NV" title="Nevada"/>
     <area mc_name="NH" title="New Hampshire"/>
     <area mc_name="NJ" title="New Jersey"/>
     <area mc_name="NM" title="New Mexico"/>
     <area mc_name="NY" title="New York"/>
     <area mc_name="NC" title="North Carolina"/>
     <area mc_name="ND" title="North Dakota"/>
     <area mc_name="OH" title="Ohio"/>
     <area mc_name="OK" title="Oklahoma"/>
     <area mc_name="OR" title="Oregon"/>
     <area mc_name="PA" title="Pennsylvania"/>
     <area mc_name="RI" title="Rhode Island"/>
     <area mc_name="SC" title="South Carolina"/>
     <area mc_name="SD" title="South Dakota"/>
     <area mc_name="TN" title="Tennessee"/>
     <area mc_name="TX" title="Texas"/>
     <area mc_name="UT" title="Utah"/>
     <area mc_name="VT" title="Vermont"/>
     <area mc_name="VA" title="Virginia"/>
     <area mc_name="WA" title="Washington"/>
     <area mc_name="WV" title="West Virginia"/>
     <area mc_name="WI" title="Wisconsin"/>
   <area mc_name="WY" title="Wyoming"/>
   </areas>
   <labels>
     <label x="0" y="60" width="100%" color="#FFFFFF" text_size="18">
       <text>Map of the United States of America</text>
     </label>
   </labels>
   </map>
   

   As you can see, we have defined regions (states) on the map of USA, and towards the end of the file, we have added a label for the map.

3. Select Yes for the Published field in the Details section.

When you are done making these changes click on the Save button to save these changes. Now we will look into the map settings file.

Map data files for countries are available with the amMap package. Thus, if you download amMap 2.5.1, you will get the map settings files for different countries. For example, the map data file for USA will be in the amMap_2.5.1/examples/_countries/usa folder.

Build a stunning, content-rich, and interactive web site with Joomla! 1.5 and Flash CS4 Build an attractive web site integrating Flash objects into Joomla! Create stunning photo galleries with Flash transition and animation effects Use interactive Flash-based maps, charts, animations, videos, MP3 players, logos, headers, and banners in Joomla!-based web sites Turn your Joomla! web site into a feature-rich multimedia enhanced site through this step-by-step easy-to-follow guide enriched with screenshots  http://www.packtpub.com/joomla-with-flash/book

Map settings file

The map settings file is another XML file through which the map's display and other settings are defined. You can view and edit this file in the same way as you have done for the map data file, ammap_data.xml. A map settings file is named as ammap_settings.xml, and like the ammap_data.xml file, it has lots of annotations to explain each setting. You can view as well as edit this file by clicking on the Settings section in the amMap: [Edit] screen, as shown in the following screenshot:

An annotation for each setting is provided on the right side. You can configure the settings by following the instructions in the annotations. Once the changes have been made to this file, click on the Save icon on the toolbar to save the changes and close the screen.

Publishing a map through the module

After configuring the map through the amMap: [Edit] screen and editing the map data file, ammap_data.xml and the map settings file, ammap_settings.xml, you can display the map on the frontend by publishing the amMap module.

If you have not installed the amMap module yet, then install it from the Extensions | Install/Uninstall screen. The module and the plugin installation packages are bundled with the YOS amMap package that you have already downloaded. Once installed, go to Extensions | Module Manager and click on the YOS amMap module. That shows the Module: [Edit] screen for the YOS amMap module, as shown in the following screenshot:

Like other modules you can use the Details section to provide a title for this module, publish the module, select the position where it should be displayed, set the access level, and establish the order of display. Similarly, from the Menu Assignment section, you can specify the menus for which the module will be displayed. The settings specific to this module are displayed in the Parameters section. First you need to type the amMap's ID, which is displayed in the list shown on the YOS amMap Manager screen. After typing the amMap's ID, select Yes in the Enable Plugin field if you want to show this map using a plugin.

The next few settings are for displaying the map in your desired format. You can assign a module suffix (for example, green), which can be used to manipulate the display through a CSS. In the Display-Type drop-down box, select either SWF-Object or Embedding Flash Object. SWF-Object is the default mode and it uses a wrapper for embedding Flash objects. Then you can specify the width and height of the Flash object in pixels. This needs to be in line with your module's position. You can also specify the version of Flash needed to display the map. The default value for this field is 8, which means that Flash Player version 8 will display the map properly, and users having a version lower than this will be prompted to upgrade to the required version of Flash Player. In the Background Color field you can specify the background color for the module.

The path to the amMap files can be specified in the Path field. The default value for this field is components/com_yos_ammap/ammap, which is fine as the files are installed in this directory. You can specify default data and settings files in the Data file and Setting file fields. The default values for these fields are components/com_yos_ammap/ammap/ammap_data.xml and components/com_yos_ammap/ammap/ammap_settings.xml respectively. The files specified in these two fields will work only when no ID number for amMap is specified in the amMap's ID field.

You can specify a preloader color, a loading text, and a settings loading text. These texts are displayed when the map's data and settings are being loaded.

When all these settings have been set and saved by clicking on the Save button on the toolbar, you can preview the map by clicking on the Preview button on the toolbar. The map should be displayed as shown in the following screenshot, in the frontend:

When you move your mouse pointer over the map area you will see that the states are highlighted displaying the state's name. You can zoom in or zoom out using the Zoom control shown on the left of the map. Note that an overview map is displayed at the bottom-right corner. Clicking the arrow below it will hide the overview map.

If you want to display multiple maps, then you can copy the YOS amMap module and configure each instance with a different amMap ID. To copy the module, in the Extensions | Module Manager screen, select the module and click on the Copy icon in the toolbar. Then, rename the copied module. Alternatively, you can use the new module wizard by clicking on the New icon on the toolbar. In this wizard, you have to select YOS amMap in the Module: [New] screen and then configure it with the same settings, as described above.

Showing the map in content using a plugin

So far we have seen how to display a Flash map with the amMap module. You can also display the map in your Joomla! content, that is, articles. The YOS amMap component package comes with a plugin for displaying an amMap map into Joomla! articles. If you have installed the plugin already, then go to Extensions | Plugin Manager and click on Plugin - YOS Ammap. This displays the Plugin: [Edit] screen, shown in the following screenshot, for the YOS Ammap plugin:

Enable this plugin by selecting Yes in the Enabled field. Next, read the instructions given in the Description field. The instructions show how to use this plugin. From this text, you will notice that you can embed an amMap map in articles using the following syntax:

{yos_ammap mapid='3' width='500' height='400' flashv='8'
 bgcolour='#000000' type='js' plugin='1'}

You may be familiar with most of these by now. First, we have to specify the mapid, and then its width, height, flash version, background color, type, and plugin. Use 1 in plugin if you want to show dynamic data in the map. Therefore, using this syntax, we can add the map of USA in an article. The text for the article may be as follows:

amMap is an interactive flash map creation software. Use this tool 
to show locations of your offices, routes of your journeys, create 
your distributor map. Photos or illustrations can be used instead 
of maps, so you can make different presentations, e-learning tools and more.
YOS amMap is an Joomla extension which integrated almost amMap 
features. With YOS amMap you can easily integrate maps which provided 
by amMap to your Joomla site.
You can also include a map in Joomla! artilcle. Here is an example:
{yos_ammap mapid='3' width='600' height='500' falshv='8' plugin='1'}

The last line, inside {}, will show the map with the ID 3, which is the map of USA. When this article is published and viewed in the frontend, the article will look like the following screenshot:

As you see, the map of USA has been embedded in the article. The map behaves in the same way as it does inside the module. You can add multiple maps in an article using the same syntax. However, you must ensure that the map IDs are correct.

For more information on using the YOS amMap component, please visit http://yopensource.com/en/documentation/yos-ammap. You can also check www.ammap.com for more information on amMap and to download new map files.

Summary

In this article we have seen how to use YOS amMap and YOS amChart to create and display interactive Flash-based maps and charts.

Build a stunning, content-rich, and interactive web site with Joomla! 1.5 and Flash CS4 Build an attractive web site integrating Flash objects into Joomla! Create stunning photo galleries with Flash transition and animation effects Use interactive Flash-based maps, charts, animations, videos, MP3 players, logos, headers, and banners in Joomla!-based web sites Turn your Joomla! web site into a feature-rich multimedia enhanced site through this step-by-step easy-to-follow guide enriched with screenshots  http://www.packtpub.com/joomla-with-flash/book

About the Author

Suhreed Sarkar—IT consultant, trainer, and technical writer—studied Marine Engineering, served on board a ship for two years, then switched to the computer world with MCSE in Windows NT 4.0 track late in 2000. His latest field of study is business management and he has earned an MBA from the University of Dhaka. He has a bunch of BrainBench certifications including PHP4, Project Management, RDBMS Concepts, E-Commerce, Web Server Administration, Internet Security, Training Development, Delivery and Evaluation, and Technical Writing.

As a trainer, he has taught courses on web design, development, and e-commerce. He also delivers lectures on MIS and e-business in public and private universities in Bangladesh. Being passionate about learning and teaching new skills, he prefers hacking and teaching to actual coding for clients.

As a consultant and trainer he has experience consulting for some international organizations including the United Nations, where he helped clients building and adopting their enterprise portals, large scale databases, and management information systems. He is the best-selling technical author in Bengali—having a dozen books published on topics covering web development, LAMP, networking, and system administration. As an open-source enthusiast, he is active in different forums and takes every chance to promote open-source CMSs and shopping carts including Joomla, Mambo, Moodle, WordPress, osCommerce, Zen Cart, etc.

While not busy with hacking some apps, blogging on his blog (blog.suhreedsarkar.com), reading the philosophy of Bertrand Russell or the management thought of Peter F Drucker—he likes to spend some special moments with his family—wife, son, and daughter. Suhreed lives in Dhaka, Bangladesh with his family and may be reached at suhreedsarkar@gmail.com.