hands-on lab: developing an interactive mapping ... lab: developing an interactive mapping...

Hands-on Lab: Developing an interactive mapping

application for your Oracle database using Oracle

Maps

Hands-on Lab: Developing an interactive mapping application for your Oracle database using Oracle Maps

[email protected]

Oct. 2006

Table Of contents Hands-on Lab: Developing an interactive mapping application for your Oracle database using Oracle Maps .............................................................................................................. 3

1 Introduction.................................................................................................................. 4 1.1 Introduction to Oracle Spatial & Locator ............................................................. 5 1.2 Introduction to MapViewer................................................................................... 5 1.3 Oracle Maps .......................................................................................................... 5

2 Knowledge & Skill Prerequisites................................................................................. 6 3 Lab setup...................................................................................................................... 7

3.1 Installing Required Software ................................................................................ 7 3.2 Preparing the database .......................................................................................... 8 3.3 Preparing MapViewer........................................................................................... 9 3.3 Preparing Oracle APEX........................................................................................ 9 3.4 Application Architecture....................................................................................... 9

4 Developing the application ........................................................................................ 11 4.1 Creating the Application..................................................................................... 11 4.2 Installing photo/document downloading procedure............................................ 11

5 Populating Page 1 ...................................................................................................... 13 5.1 Displaying the map ............................................................................................. 13

6 Creating Page 2: new tag details form ....................................................................... 17 6.1 Adding a new form for tag details ...................................................................... 17 6.2 Adding a Page Process to insert new tags........................................................... 18

7 Adding new tags to the map....................................................................................... 20 7.1 Defining Page 2 branching.................................................................................. 21

8 Creating the tag list report.......................................................................................... 22 9 Search Tags by Area .................................................................................................. 24

9.1 Adding Search Area controls .............................................................................. 24 9.2 Creating a report for search results ..................................................................... 25 9.3 What happens when you define a search region................................................. 25

10 Serach Tags by Name .............................................................................................. 26 11 Online Resources ..................................................................................................... 26 Appendix A: Source code listing for P1.js................................................................... 27

1 Introduction In this hands-on lab, you will learn how to use Oracle Spatial, Oracle Application Server MapViewer and Oracle Application Express (APEX) to develop a simple online mapping application called “Geo-Tags”. This mapping application lets you create location-based ‘bookmarks’ or geo-tags on a Google-style interactive map, upload rich content to be associated with the geo-tags, and view the content via mouse clicks on the map. A screenshot of this application is shown below.

All the map data used by this application are stored in an Oracle Spatial database. The table for all the geo-tags is also ‘spatially’ enabled in that it contains (among other columns) a geometry column with a spatial index. All the maps are rendered by OracleAS MapViewer, and can be viewed in a highly interactive manner through the new AJAX-based Oracle Maps interface. You can drag the map around, mouse over to any geo-tag to see a tool tip, and click on it to view its associated multimedia file (such as a picture, a PDF doc, or even a short movie clip) in a tool-tip window. You will be able to browse all existing tags in an Oracle APEX report. The application also provides capability to search geo-tags by interactively drawing a region on the map as well as by their name. Although the maps are displayed and manipulated in a Google Maps like style, please note that we will NOT be using any service or map from the Google Maps server. This is an application written completely in Oracle’s technology stack. Hopefully at the end of the lab, you will realize the interactive mapping library of MapViewer to be quite powerful, its seamless integration with database ad hoc querying capability very versatile, and its built-in functions and customization possibilities far richer than those available from Google Maps or similar offerings.

1.1 Introduction to Oracle Spatial & Locator Oracle Spatial and Oracle Locator make location a native type within Oracle Database 10g. Oracle Locator is a feature of Oracle Database 10g Express, Standard, Standard One, and Enterprise Editions that provides spatial object type storage, indexing, and operations, to support a variety of location-based services (LBS) and 3rd party GIS solutions. Oracle Spatial is an option for Oracle Database 10g Enterprise Edition that provides advanced spatial features to support high-end GIS and LBS solutions. This lab only requires Oracle Locator functions.

1.2 Introduction to MapViewer OracleAS MapViewer is a J2EE application that comes with every edition of Oracle Application Server. Once deployed to Oracle AS, it listens and accepts incoming map requests. You can connect it to any Oracle database schema that contains spatial data, and it will be able to render sophisticated maps from those data. Starting with MapViewer version 10.1.3, it also comes with a standalone desktop tool called Map Builder . You can use Map Builder to preview spatial data stored in Oracle Spatial, and define sophisticated styling rules so that professional looking maps can be generated by MapViewer. The styling rules, once created in Map Builder, are stored back into the database. The MapViewer server then picks up those rules and apply them when rendering maps in response to incoming map requests. For this lab, the styling rules for the themes (map layers) involved are already defined and stored in the MVDEMO schema (described in a bit later), in the following views:

• USER_SDO_STYLES: this view stores individual map symbols and other types of styles such as: LINE patterns, COLOR definitions, and thematic mapping styles.

• USER_SDO_THEMES: this view stores the definitions of individual map layers or themes. A theme is always based on a data table or view, and specifies what rendering and labeling styles to be used.

• USER_SDO_MAPS: this view stores the definitions of base maps. Each base map contains a list of themes. It specifies the display order and on/off status of each theme at various map scales.

1.3 Oracle Maps In the pre-AJAX era, online mapping application typically works in a serialized single request/response model. More specifically, the browser/client issues a request for a map, and the server generates a map in response. The map is then displayed to the client. Any interaction on the client side, such as zooming or panning the map, will often result in a new request being sent to the server to produce a new map in response to the client action. In this paradigm, the server is constantly generating, and re-generating, maps on the fly. This often severely affects the scalability and performance of the overall application. Oracle Maps, similar to Google Maps, introduces the caching of pre-generated map tiles on the server and in the client (via browser cache). As a part of MapViewer 10.1.3.1, Oracle Maps provides map tile caching and many other unique features:

• Caching of map tiles for any base map at the mid-tier

• Support of Features of Interest (FOI). FOIs are JavaScript (geospatial) objects generated at the mid-tier based on dynamic database queries and displayed at the client side with built-in interactions such as mouse over and tool tip.

• Highly interactive client side mapping interface. Your application will have built-in capability to drag the map around, instantly zoom or pan to any desired level/location, draw free-hand shapes on the map, add collapsible birds-eye-view map inside the main map area, among many other off-the-shelf functions. All of these functions are available to you through an open JavaScript API.

This lab will teach you how to use this new Oracle Maps JavaScript API to develop highly interactive mapping application. Please note however an understanding of how MapViewer works in general and its core concepts is essential to develop any successful enterprise level MapViewer applications.

2 Knowledge & Skill Prerequisites The following knowledge or skills are helpful.

• Oracle APEX basics • JavaScript programming basics • Oracle Spatial basics • MapViewer concepts • Oracle Application Server basics

3 Lab setup

3.1 Installing Required Software This lab requires the following products:

• Java JDK 1.5 (to run the Map Builder desktop tool) • Oracle database 9i or 10g (XE/SE/EE). 10g preferred. • Oracle Application Server 10.1.3 or 10.1.3.1 (SOA) • Oracle Application Express (APEX) 2.0 or higher • OracleAS MapViewer 10.1.3.1 deployed to the above Oracle Application Server

You can download a fully functioning copy of the required Oracle products from OTN (Oracle Tech Net, otn.oracle.com). JDK 1.5 can be downloaded from Sun Microsystems’ Java site. For database, the Express Edition (XE) offers the quickest installation and works just fine for this lab; but if you already have an existing database then that should work too. Or if you would like to deploy a relatively large spatial data set to your database later on, then starting with a none-XE database might be better for you. The lab will require a single database schema called MVDEMO . This schema will contain the sample map data set that comes with OracleAS MapViewer 10.1.3.1 (downloadable from OTN). It contains the simplified boundary data for all the states and counties of the United States. It also contains the layers for major cities and highways. For instructions on how to create this schema and load the sample data set, please see the readme file that comes with the data set (which is part of the MapViewer 10.1.3. The Oracle Application server version 10.1.3 can be installed in under 15 minutes and it basically contains (for the purpose of this lab) an HTTP server and an OC4J instance. You do not need to setup any infrastructure database or metadata repository as required when installing earlier versions of Oracle Application Server (such as 10.1.2). In fact this lab will not work with earlier versions of Oracle Application Server such as 10.1.2. The reason is that you cannot deploy MapViewer 10.1.3.1 on Oracle Application Server 10.1.2 or earlier versions. Once your database and Oracle Application Server 10.1.3 are up and running, you will need to install Oracle APEX and configure it to work with your Oracle App Server installation. For detailed instructions on installing and configuring Oracle APEX, please refer to the Oracle APEX Installation Guide. For instructions on how to deploy MapViewer on Oracle Application Server, please see the MapViewer User’s Guide. This is often a simple task involving a few mouse clicks. An alternative midtier architecture is to use a standalone Oracle HTTP Server (configured for Oracle APEX), plus the MapViewer Quick Start kit (which is a standalone OC4J with MapViewer readily deployed). In this case, however, you must configure OHS so that it acts as a proxy for the standalone OC4J instance running MapViewer. You can set this up using Oracle HTTP Server’s mod_proxy configuration, such as in the following example:

� � � � � � � � � � � � � � � � � ��

� � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � � �� ! � " � � � � #

� � � � � � � � � � � � � � � � � � �

In either midtier architecture, the critical thing is that both Oracle APEX and MapViewer are accessed from the same web domain (URLs with the same host and port). In other words, if you access your Oracle APEX environment through a URL such as http://www.mycorp.com:7777/pls/apex, then you must be able to access the MapViewer instance through the URL http://www.mycorp.com:7777/mapviewer. Please see the related note below for the reason behind this requirement. Regarding XE and its Oracle APEX environment: Ideally, we would like to develop this lab application by using only database XE and the MapViewer Quick Start kit, since database XE already comes with its own Oracle APEX environment. Unfortunately for this demo we will not be able to use this combination. The reason is that Oracle APEX in XE listens on its own port (8080 by default), and MapViewer will be running in the standalone OC4J on a different port, and currently there is no easy way to coerce the two into sharing a single listener. This makes the servers of origin appear different when your browser loads the lab application, and some of the key Oracle Maps functions will fail due to the restriction on cross-domain AJAX calls imposed by most browsers.

3.2 Preparing the database In order to start developing the Geo Tag application, you need to load the sample data set into the database user ‘mvdemo’.

1. Import the mvdemo data set that comes with MapViewer 10.1.3.1 release (available on MapViewer’s OTN site). For detailed instructions, please check the readme file in the demo data set. Make sure the data set is imported into the database user named ‘mvdemo’.

2. Run the SQL script geotag.sql (comes with this lab package) on the database user ‘mvdemo’. The script creates a table named geotag for storing user created geo-tag information. It also creates a spatial index, as well as two associated MapViewer themes for the table. The theme GEOTAGS is for displaying all the tags on the map in their normal state, while the theme GEOTAGS_SELECT is used only to display/highlight tags that are within a custom defined search area. The following lists the table columns of geotag: SQL> desc geotag; Name Null? Type ----------------------------------------- -------- ---------------------------- NAME NOT NULL VARCHAR2(64) CONTENT BLOB MIME_TYPE VARCHAR2(48)

FILE_NAME VARCHAR2(64) LOCATION MDSYS.SDO_GEOMETRY DESCRIPTION VARCHAR2(4000) LAST_UPDATE DATE AUTHOR VARCHAR2(128)

3.3 Preparing MapViewer After you imported the mvdemo data set, you must create a MapViewer data source named “mvdemo”, and create also a map cache instance named “demo_map” that caches map tiles for the base map. For detailed instructions, please check out the Oracle Maps tutorials page and its setup info. The Oracle Maps tutorials page contains a list of 40+ simple Oracle Maps demos that are a great way of getting yourself accustomed to the specifics of the JavaScript API. This step is performed correctly if you can run any of these 40+ tutorials.

3.3 Preparing Oracle APEX The first thing you need to do is to log in as Oracle APEX admin and create a new workspace based on the ‘mvdemo’ database schema. Then create a new Oracle APEX developer user as the owner of the demo application we will be building.

3.4 Application Architecture The following diagram illustrates the big picture of this application.

Note that the Oracle APEX engine assembles the application’s pages. Within the main application page, it is Oracle Maps that assembles and manages the map display. We also utilize Oracle APEX’s file upload and download functions.

4 Developing the application The application we will be building consists of two pages. Page 1 displays the map itself, plus various controls for creating custom search areas on the map, as well as a few Oracle APEX reports that list the geo-tags. Page 2 contains a single form that is used to fill in details (such as tag name and associated rich content) for a new geo-tag. The navigation rules between these two pages are quite simple. When the user right-clicks on the map (displayed in page 1), which initiates the process of creating a new geo-tag for that location, the application will automatically load page 2. When the user submits page 2, Oracle APEX will execute a custom page process to insert the new tag into the table geotag. Oracle APEX then redirects us back to page 1 where the map will be refreshed.

4.1 Creating the Application 1. Log into Oracle APEX 2. Click on Application Builder , then Create 3. Select Create Application then Next 4. Enter the application name ‘geotag’. Make sure the schema is set to

MVDEMO . Accept the defaults for the rest and click Next. 5. In the Pages panel, select default page type (Blank) and click Add Page. 6. Now you will see a summary table showing that you have created Page 1.

Click Next. 7. In the Tabs panel, select ‘No Tabs’ then Next. 8. Click through Shared Components and Attributes panels while accepting

defaults. 9. In the User Interface panel, select Theme 15, then click Next. 10. In the confirmation page, click Create. 11. The application is now created. You can click the Run button to test run this

application. It will ask for authentication then displays Page 1, which is basically blank at this stage.

4.2 Installing photo/document downloading procedure Note that each geo-tag can have an associated photo or PDF document uploaded from the end user’s PC and stored in the database table geotag. When a user clicks on a geo tag on the map, the associated photo or document is automatically fetched from the database and displayed/opened inside the info-window of the geo-tag. In other words, when the user clicks on a geo-tag, we need to download the associated multimedia file from the database to the client’s browser. In order to make this downloading work, we must install a PL/SQL procedure that does this for us, then expose this PL/SQL procedure as URL in the FOI click event handler (which displays the info window when you click on a tag). The following steps install just such a downloading procedure.

1. From the Oracle APEX Workspace home page, click SQL Workshop 2. Select SQL Commands 3. Enter the following PL/SQL procedure in the text area:

CREATE OR REPLACE procedure download_file(p_name in varchar2) AS v_mime VARCHAR2(48); v_length NUMBER; v_file_name VARCHAR2(2000); Lob_loc BLOB; BEGIN select MIME_TYPE, CONTENT, FILE_NAME, DBMS_LOB.GETLENGTH(content) into v_mime, Lob_loc, v_file_name, v_length from geotag where name=p_name; -- setup HTTP header -- use an NVL around the mime type; if null set to application/octet owa_util.mime_header( nvl(v_mime, 'application/octet'), FALSE ); -- set the size so browser knows how much to download htp.p('Content-length: '|| v_length); -- file name will be used in save as htp.p('Content-Disposition: attachment;filename="'||replace(replace(substr(v_file_name,instr(v_file_name,'/')+1),chr(10),null),chr(13),null)|| '"'); -- close the headers owa_util.http_header_close; -- download the blob wpg_docload.download_file(Lob_loc); END download_file; /

Now click on the Run button to execute the above script. Next, enter the following in the same SQL Commands query area and execute it:

GRANT EXECUTE ON download_file to PUBLIC /

5 Populating Page 1 In this section we will start populating Page 1 with various components to display the map as well as several reports.

5.1 Displaying the map In this step we are going to create a new region inside page 1, and display the draggable map inside this new region. Since this application utilizes MapViewer’s new JavaScript based API, we must include this library as part of Page 1. The best approach to include JavaScript in Oracle APEX, is to use a page’s HTML Header attribute.

1. From Page 1, click on the Edit page attributes icon, as shown here:

2. On the next page, click on HTML Header , then enter the following in its text area:

<script language="JavaScript" src="/mapviewer/fsmc/jslib/oraclemaps.js"></script>

What the above does, is loading the Oracle Maps JavaScript API library into the page, so that its functions, such as displaying a map, can be invoked in our mapping related application logic. Now in the same text field, add the following script containing the mapping related application logic: <script language="Javascript" src="/geotag/p1.js"></script> The above loads the JavaScript file p1.js into the current page. This file is part of the lab package. Now click on Apply Changes.

3. About the p1.js file. The p1.js file is already included in the lab package. Your task is to place this file in a place so that our application can access it using the URL “/geotag/p1.js”. To do so, you need to navigate to the web server’s HTML document root directory, typically $IAS_HOME/Apache/Apache/htdocs. Now create a directory named geotag. Then inside this directory, copy the text file p1.js from the lab files directory. This file contains JavaScript code that implements the application specific logic. The main function in this file is called showMap() listed below. For complete source code listing please see Appendix A. var mapview;

var themebasedfoi; // function showMap() { var baseURL = "http://"+document.location.host +"/mapviewer";; var mapCenterLon = -122.45; var mapCenterLat = 37.67; var mapZoom = 4; var mpoint = MVSdoGeometry.createPoint(mapCenterLon,mapCenterLat ,8307); mapview = new MVMapView(document.getElementById ("map"), baseURL); mapview.addBaseMapLayer(new MVBaseMap("mvdemo.d emo_map")); mapview.setCenter(mpoint); mapview.setZoomLevel(mapZoom); themebasedfoi = new MVThemeBasedFOI('geotags','mvdemo.geotags'); themebasedfoi.setBringToTopOnMouseOver(true); themebasedfoi.addEventListener("mouse_click", f oiClick); mapview.addThemeBasedFOI(themebasedfoi); mapview.addCopyRightNote("(C)2006 Oracle Corpor ation (C)2006 Navteq"); mapview.addNavigationPanel("EAST"); mapview.setCenterMark("/i/bullseyeicon_cctitle. gif", 18, 18); mapview.display(); setMapListener(); } ……

What the above code does is setting up the initial map display by providing the center and zoom level, as well as the map contents. Specifically, it will display a background base map named “mvdemo.demo_map”, as well as an interactive theme for all the geo-tags (defined in the theme “mvdemo.geotags”). This is all done in the single function showMap(). Although the p1.js file is now in place, we still need to somehow invoke the function showMap() in order to actually have a map displayed inside our application page. To do this requires two steps, as described below.

4. Create a region for map display. The first step toward displaying a map is to create an HTML region inside Page 1. 1. Start editing Page 1.

2. Click on the icon inside the Regions panel. 3. Select HTML type, then click Next 4. Enter Map as the region title, accept the defaults for the rest. Then click Next. 5. For Region Source, enter the following: <div id="map" style="left:0px; top:0px; width:700px; height:600px; border:1px solid #CFE0F1"></div> What the above does, is creating a region that contains a single HTML DIV element with the id ‘map’. This DIV will serve as the main container for our map, and the id ‘map’ is actually referenced in the showMap() JavaScript function in the file p1.js. Note that the CSS style for the above DIV is completely customizable, so for instance you can change the width/height or how the border

looks. Recall that this DIV serves as the container or framework inside which Oracle Maps will display the actual map contents. 6. Now click on Create Region to complete this step.

5. Invoke showMap(). The second step towards displaying a map, is to actually invoke the showMap() function in the page’s onLoad event handler, so that the map can be displayed whenever the page itself is displayed. 1. From Page 1 editor, click on the Edit page attributes icon. 2. Click the Display Attributes tab. Change Cursor Focus to “Do not focus cursor”. Click Apply Changes. 3. Now click on the Edit page attributes icon again. Then select the On Load tab. Enter the following in the text area: onload="showMap(); first_field();" 4. Click on Apply changes.

6. Run the demo. At this point, you should be able to run Page 1 and see a map displayed. Click on the Run button on the top of the page, and you should see a map like this:

Note that you may not initially see any green stars representing the user uploaded geo tags. They will appear as you start to add them. If you do not see a map, carefully re-examine all the steps above and make sure you entered all the texts exactly as is. Also it is recommended that you use the FireFox browser as it has a built in JavaScript console (under the menu Tools) providing a detailed break down of any JavaScript related errors.

6 Creating Page 2: new tag details form Now we are going to create a new page that will display a form to the user so that they can fill in details about the new tag to be created.

a. From Application Builder, click on Create Page b. Select Blank as the page type, then click Next c. Accept default page number, then click Next d. Enter ‘Create a new tag’ as the page name, then click Next e. Choose No Tabs then click Next f. Click Finish

6.1 Adding a new form for tag details Now that we have created Page 2, let’s add a single region and form to it.

a. From Page 2 editor, click on the icon inside the Regions panel b. Select HTML as the region type c. Enter “Tag details” as the region title. Accept defaults for the rest. Click Next d. Leave Region Source empty. Click Create Region.

Now let’s add all the necessary form fields to the new region we just created.

a. Go back to Page 2 editor

b. Click on the icon inside the Items panel c. Select Text type then click Next d. Select Text Field then click Next e. Enter “P2_NAME” as the Item name, accept the defaults for the rest then click

Next f. Accept defaults in the Item Attributes panel and click Next g. Accept defaults in the Source panel and click Create Item.

Now repeat the above steps to create the following additional Items, with the exact name and type below: Name Type

P2_Description Text Area P2_ Author Text Field P2_TAGX Text Field P2_TAGY Text Field

Finally, we need to add one more field that can be used to upload a photo or document from a local PC for the new tag.


b. Click on the icon inside the Items panel c. Select File Browse as the item type then click Next d. Enter P2_FILE_NAME as the item name then click Next e. Accept default values then click Next f. Accept default values then click Create Item.

Next, we need to add two buttons so that the user can submit the form or cancel it and return to Page 1. Let’s first create the Submit button.


b. Click on the icon inside the Buttons panel c. Accept the defaults then click Next d. Accept the defaults in the Button Position panel then click Next e. Choose the link “[Submit]” for button name and label, accept defaults for all other

fields, then click Next f. Accept defaults for Button Template then click Next g. Accept default values for Display Properties then click Next h. Accept defaults for Branching then click Create Button

Let’s now create the Cancel button. When user clicks on the Cancel button, the browser will go back to Page 1.


b. Click on the icon inside the Buttons panel c. Accept the default then click Next d. Accept the default in the Button Position panel then click Next e. Choose the link “[Cancel]” for the button name and label. For Action, choose

“Redirect to URL without submitting page”. Click Next. f. Accept default for Button Template then click Next g. Accept default values for Display Properties then click Next h. Choose Page 1 in the Branching panel, accept the defaults for the other fields,

then click Create Button.

6.2 Adding a Page Process to insert new tags So what happens when the user fills out the tag details form and clicks on the Submit button? Well, we need to define a Page Process so that a new tag can be inserted into the geotag table based on the submitted form values. Note also that by default Oracle APEX will save the uploaded file into a system table named APEX_APPLICATION_FILES. In our page process we will need to move the uploaded file content and a few other attributes about from this table into the geotag table. Let’s now create a new Page Process for page 2. 1. Go back to Page 2 Editor

2. Under the Page Processing column, click on the icon inside the Processes panel. 3. Select the PL/SQL category then click Next 4. Enter “Insert” as the process name, accept defaults for the other fields then click Next 5. In the text area titled “Enter PL/SQL Page Process”, enter the following SQL statements:

insert into GEOTAG select :P2_NAME, blob_content, MIME_TYPE, :P2_FILE_NAME, mdsys.sdo_geometry(2001, 8307, mdsys.sdo_point_type(:P2_TAGX, :P2_TAGY, null), NULL, NULL), :P2_DESCRIPTION, sysdate,

:P2_AUTHOR from APEX_APPLICATION_FILES where name = :P2_FILE_NAME; delete from APEX_APPLICATION_FILES where name = :P2_FILE_NAME;

6. Accept the defaults for the other fields then click Create Process. What we just did, is creating a page process based on a few SQL queries. Oracle APEX will automatically execute these SQL for us whenever a new tag form is submitted.

7 Adding new tags to the map Now that the page process is in place, we can start adding new tags to the map. To initiate this, all you need to do is navigating to the desired location on the map (using the built-in navigation/zoom tools) where you want the new tag to be, then right clicking on that location. You will immediately be forwarded to Page 2 where you can fill in all the tag details. This action (forwarding to Page 2) is implemented in p1.js using Oracle Map’s event listener mechanism. Specifically, in p1.js we have the following two functions that implement this logic.

function setMapListener() { mapview.addEventListener("mouse_right_click", addNewTag); } function addNewTag() { var mouseLoc = mapview.getMouseLocation(); var x = mouseLoc.getPointX(); var y = mouseLoc.getPointY(); var zoom = mapview.getZoomLevel(); var Session_Id = html_GetElement('pInstance').value; redirect("/pls/apex/f?p=101:2:"+Session_Id+"::NO::P2_TAGX,P2_TAGY:"+x+","+y); }

As you can see we added an event handler to the mapview object so that it listens for the mouse right-click event on the map. The event handler will get the current location of the mouse click, and pass this piece of information as the values of the parameters P2_TAGX and P2_TAGY when invoking Page 2 in the redirect() call. Recall that P2_TAGX and P2_TAGY are two of the form fields we created previously for Page 2. In the above redirect() call we are pre-populating these two form fields with specific values. The syntax for the URL passed into redirect() is described in the Oracle APEX Developer’s Guide. Note that the number 101 in the URL refers to the application ID, and you must change it if your application has a different ID. We are also using the Oracle APEX html_GetElement method to obtain the current session id required for a successful manual redirect to Page 2. Once in Page 2, simply fill in the details (you will notice that the two fields, TAGX and TAGY, are already filled in with the new tag’s location X and Y), and choose a local photo/PDF document file, then click Submit. A new record will now be created in the table geotag, and you will be directed back to Page 1 where the new tag is displayed as a green star on the refreshed map (this redirecting is achieved through the branching defined in Step 7.1). Make sure you add at least one geo tag, otherwise the tag list report we will be creating next won’t have any data to display.

7.1 Defining Page 2 branching So what happens when you submit the new tag details form and the tag is inserted in the table geotag? We must define where Oracle APEX should branch to after a successful submission and processing of Page 2 (note that if we cancel the submission of Page 2 then we are redirected back to Page 1 through the redirect URL defined for the Cancel button). In this case, we want Oracle APEX to redirect to Page 1 so that the map is refreshed with the newly created geo-tag. The steps for creating a ‘success’ branching are:

1. Go back to Page 2 editor

2. In the Page Processing column, find the Branches box. Click on the icon. 3. Accept defaults and click Next 4. Enter 1 in the Page field, then click Next 5. Select Always from the Conditional Type dropdown list, then click Create

Branch.

8 Creating the tag list report Now let’s add a report that lists all the existing tags. This report is based on the geotag table, so even though initially it will not display any rows, as soon as you add a new tag it will show up in the report. 1. Click on the Create icon inside the Regions panel 2. Select Report as the region type then click Next 3. Select SQL Report then Next 4. In the Display Attributes panel, enter “Complete tag list” for Title. Make sure Column is set to 2. Accept the defaults for the other fields. Click Next. 5. In the Source panel, enter the following SQL query:

select name, mime_type, author as Uploader, description, a.location.sdo_point.x X, a.location.sdo_point.y Y, 'location' loc from geotag A

6. Now click Create Region. 7. Now click on the Edit Report Columns link (shown below) so that we can customize the new report’s columns. Basically we want to hide the columns X and Y, but use their value to construct a ‘recenter’ link that serves as the value of the LOC column.

In the ensuing Report Attributes panel:

• Make sure you unselect the check boxes under the Show column for the two fields named X and Y. Click on the Apply Changes button.

• Then, click on the icon next to the LOC field. • Now click on the Link tab on the top of the Column Attributes panel. • Enter “Where” as the Link text. Select URL from the Target drop down list.

Then enter javaScript:recenter(#X#, #Y#) in the URL text field. • Now click Apply Changes.

What we just did, is to hide the two columns X and Y. We then use the values of these two columns as the parameter for the LOC column’s Link URL, which when clicked upon will invoke the recenter() function defined in the p1.js file. Now run Page 1, and you will see a full report of all the existing tags next to the map. The LOC column contains an HTML link for each row. When you click on this link, the map will be automatically re-centered to the location of the corresponding tag.

9 Search Tags by Area The next task for this lab is to add the Search Tags by Area capability. This will allow user to define a visual search area on the map through rubber banding (which creates a rectangle on the map), hand drawing (which creates an arbitrary polygon on the map), or radius (creates a circular area) and all the geo-tags that are within the search area will be highlighted on the map.

9.1 Adding Search Area controls The first thing we need to do is adding a tool bar on top of the map so that user can select which type of Search Area they would like to create. The tool bar will contain a drop down list with three tools: Rubber Banding (for creating a rectangular search area), Hand Drawing (for creating a polygonal search area) and Radius (for circular search area). The tool bar also contains two buttons, Go and Clear. User must click on the Go button before they can start rubber banding etc on the map. The tool is not initialized for use until the Go button has been clicked upon. Clear button is used to clear any existing Search Area on the map. The 3 tools (Rubber Banding, Hand Drawing and Radius) in turn are implemented using the built-in Oracle Maps API classes called MVRectangleTool, MVRedlineTool and MVCircleTool . These classes will automatically handle your mouse press and dragging actions, render the temporary shape being created/dragged on the map, and when done, return a geometry representing the search area/shape you just created. Let’s first add the drop down tools list. The two buttons are created as Post Element Text of the drop down list.

1. Go to Page 1 Edtior

2. Click on the icon inside the Items panel 3. Choose Select List as the item type then click Next 4. Choose Select List in the Item Type panel then click Next 5. Enter P1_MAPSEL as the item name; select Map from the Region drop down list;

accept defaults for other fields then click Next 6. In Identify List of Values, click on the link “Create or edit static List of

Values” below the text area. In the pop up window, enter the following 3 pairs of values for the two columns (Display Value and Return Value): Display Value Return Value Rubber Banding RECT Hand Drawing POLYGON Radius CIRCLE

Click Apply then click Next. 7. In the Item Attributes panel, enter “Define search are by” as item label. Accept

defaults for the other fields, then click Next. 8. Accept default values in the Source panel, then click Create Item. 9. From Page 1 Editor, click on the item we just created (from inside the Items

panel), then click on the Label tab. In the Label panel, enter the following for the Post Element Text area:

<input type="button" onclick="doRegionSelect();" value="Go" /> <input type="button" onclick="clrRegionSelect();" value="Clear" />

Now click Apply Changes. This adds two HTML buttons, Go and Clear, next to the drop down list. When clicked, the Go button invokes the JavaScript function doRegionSelect() defined in the p1.js file, while the Clear button will invoke clrRegionSelect().

9.2 Creating a report for search results When a search area is defined on the map through rubber banding etc, all the tags within the area are automatically highlighted with a pushpin symbol. The next task is to create a report just for these tags on Page 1. We will again start by creating a region first.

1. From Page 1 Editor, click on the icon inside the Regions panel. 2. Select HTML as the region type; click Next 3. Enter “Tags within search area’ as the region title. Set Column to 2 (so that this

report stacks below the Complete List of Tags report). Accept defaults for the other fields then click Next

4. Enter the following in the Region Source area: <div id="tag_select_list" style="position:relative; left:0px; top:0px; width:100%; height:100%"> Click Create Region.

9.3 What happens when you define a search region Now if you re-run Page 1 and define a search region, you will immediately see a new report being displayed under the “Tags within search area” title. Note that Page 1 itself is not even refreshed. Here again, the JavaScript code in p1.js file is performing some magic through the two functions “highlightFOIs()” and “populateTagSelectList()”. The first function, which is invoked as soon as the rubber banding or hand drawing is complete, adds a MapViewer theme named “mvdemo.geotags_select” as an FOI layer to the current map. The Oracle Maps API then asks the server (through an AJAX call) to process this new layer while supplying the shape geometry of the search area as a parameter. The MapViewer server uses this search area geometry to filter the tags in the database using the SDO_RELATE operator (an Oracle Locator function), and returns the result Features Of Interest to the client. The Oracle Maps client then displays them as the PIN symbols on top of the current map (the PIN symbol is just a regular MapViewer marker style and it is specified as part of the geotag_select theme’s definition). The second function, populateTagSelectList(), basically creates an instant HTML table based on the attributes that are available from the just loaded “mvdemo.geotags_select” theme’s FOIs. This table is then added as the innerHTML contents of the DIV named “tag_select_list”, giving you the effect of a partial page refreshing.

10 Serach Tags by Name We will leave this task as an exercise to the interested reader. Basically, you can create a regular Oracle APEX SQL-based report here so that end user can enter a search string and list all then geo-tags with a matching name in this report.

11 Online Resources Below is a list of online resources where you can read about and download/install various software packages required by this lab.

• OTN (Oracle Tech Net): http://www.oracle.com/technology/index.html • Oracle Spatial: http://www.oracle.com/technology/products/spatial/index.html • OracleAS MapViewer: http://www.oracle.com/technology/products/mapviewer • Oracle APEX: http://www.oracle.com/technology/apex/index.html • Oracle Database:

http://www.oracle.com/technology/software/products/database/oracle10g/index.html

• Oracle Middleware: http://www.oracle.com/technology/products/middleware/index.html

• Oracle Spatial/MapViewer discussion forum: http://forums.oracle.com/forums/forum.jspa?forumID=76

Appendix A: Source code listing for P1.js Note that the Oracle Maps API calls are in bold text, while calls to APEX JavaScript library is in bold and italic style. This file is included as part of the lab package. // This file contains mapping related application logic // for the Geo-tag demo var mapview; var themebasedfoi; // main function for displaying the map function showMap() { var baseURL = "http://"+document.location.host+"/mapviewer";; var mapCenterLon = -122.45; var mapCenterLat = 37.67; var mapZoom = 4; var mpoint = MVSdoGeometry.createPoint(mapCenterLon,mapCenterLat,8307); mapview = new MVMapView(document.getElementById("map"), baseURL); mapview.addBaseMapLayer(new MVBaseMap("mvdemo.demo_map")); mapview.setCenter(mpoint); mapview.setZoomLevel(mapZoom); themebasedfoi = new MVThemeBasedFOI('geotags','mvdemo.geotags'); themebasedfoi.setBringToTopOnMouseOver(true); themebasedfoi.addEventListener("mouse_click", foiClick); mapview.addThemeBasedFOI(themebasedfoi); mapview.addCopyRightNote("?2006 Oracle"); mapview.addNavigationPanel("EAST"); mapview.setCenterMark("/i/bullseyeicon_cctitle.gif", 18, 18); mapview.display(); setMapListener(); } var tagHtml; //this function defines what gets displayed when you click on //a geo-tag on the map function foiClick(point,foi) { tagHtml = getMediaString(foi); mapview.displayInfoWindow(point, tagHtml, 250,120); } function openDocWindow(url) { window.open(url); } //this function constructs the URL that displays/downloads //previously uploaded multimedia file associated with //an FOI (geo-tag). function getMediaString(foi)

{ //these fields are defined in the GEOTAG theme's hidden-info columns //using the Map Builder tool. var name = foi.attrs[0]; //name var desc = foi.attrs[1]; //desription var type = foi.attrs[3]; //mime type var mediaTag; //TODO: we may need to URL encode the name in case there is white space //in the file name which will result in a broken link inside info-window var contentUrl = "/pls/apex/MVDEMO.download_file?p_name=" + escape(name); if(type=="image/png" || type=="image/jpeg" || type=="image/gif" || type==”image/pjpeg”) mediaTag = "<img src="+contentUrl+" >"; else if(type=="application/pdf") mediaTag = "<a href=\""+contentUrl+"\" onclick=\"openDocWindow('"+contentUrl+"');\"> click here to view the document </a>"; else if(type=="application/vnd.rn-realmedia" || type=="video/vnd.rn-realvideo") { mediaTag = "<OBJECT ID=\"RVOCX\" CLASSID=\"clsid:CFCDAA03-8BE4-11cf-B84B-0020AFBBCCFA\" WIDTH=\"320\" HEIGHT=\"240\">"+ "<PARAM NAME=\"SRC\" VALUE=\""+contentUrl+"\">"+ "<PARAM NAME=\"CONTROLS\" VALUE=\"imagewindow\">"+ "<PARAM NAME=\"CONSOLE\" VALUE=\"video\">"+ "<PARAM NAME+\"LOOP\" VALUE=\"ture\">"+ "<PARAM NAME=\"AUTOSTART\" VALUE=\"true\">"+ "<EMBED SRC=\""+contentUrl+"\" WIDTH=\"320\" HEIGHT=\"240\" NOJAVA=\"true\" CONTROLS=\"ImageWindow\" CONSOLE=\"video\" AUTOSTART=\"true\" />"+ "</OBJECT>"; } var html = "<table class=\"t15standard\" border=\"1\">"+ "<tr><td width=\"80px\" class=\"t15data\">Name:</td> <td class=\"t15data\">"+name+"</td></tr>"+ "<tr><td width=\"80px\" class=\"t15data\">Description:</td> <td class=\"t15data\">"+desc+"</td></tr>"+ "<tr><td width=\"80px\" class=\"t15data\">Type:</td> <td class=\"t15data\">"+type+"</td></tr>"+ "<tr><td id=\"mediaCell\" colspan=\"2\">"+mediaTag+"</td></tr>"+ "</table>"; return html; } //this function is called from the 'where' column of various reports //to recenter the map to where the geo-tag is located. function recenter(x, y) { mapview.setCenter(MVSdoGeometry.createPoint(x,y,8307)); } //when you Right Click on the map, page 2 is opened so you can provide //details about a new geo-tag to be created. function setMapListener() { mapview.addEventListener("mouse_right_click", addNewTag); } //this function manually opens page 2 while passing the current mouse //(right) click location function addNewTag() { var mouseLoc = mapview.getMouseLocation(); var x = mouseLoc.getPointX(); var y = mouseLoc.getPointY();

if(toolSel=="RECT") { if(rectangleTool) rectangleTool.clear(); } else if(toolSel=="POLYGON") { if(redlineTool) redlineTool.clear(); } else if(toolSel=="CIRCLE") { if(circleTool) circleTool.clear(); } //also remove the highlighted tags if (mapview.getThemeBasedFOI('highlight_theme')) { mapview.removeThemeBasedFOI(highlightTheme); } //remove the selected tags list clearTagSelectList(); } //when defining a search area using the Hand Drawing tool, we //need a small options area where user can click on the 'Done' //button to complete the hand drawing operation. This option //area is implemented as a custom/individual FOI on the map. function showRedlineOption() { mapview.removeFOI("redline_option"); var html = "<div style='position:absolute;left:10px;top:2px;font-size:12;border:1px solid black;background-color:#dddddd;width:70px' onmousedown='redlineTool.generateArea();mapview.removeFOI(\"redline_option\");highlightFOIs();' >Click here when done</div></div>" ; var redlineOp = MVFOI.createHTMLFOI("redline_option", mapview.getMouseLocation(), html, 10, 5) ; mapview.addFOI(redlineOp); } /** This function is invoked as soon as the user is done with the selection tool (such as releasing the mouse button when rubber banding). We will get the geometry for the search area, set it as the filtering geometry on the highlight theme, and ask MapViewer to send us back the FOI features for the highlight theme that are within the search area. */ function highlightFOIs() { if (mapview.getThemeBasedFOI('highlight_theme')) { mapview.removeThemeBasedFOI(highlightTheme); } var geom; toolSel = document.getElementById('P1_MAPSEL').value; if(toolSel=="RECT" && rectangleTool) geom = rectangleTool.getRectangle(); else if(toolSel=="POLYGON" && redlineTool) geom = redlineTool.getPolygon(); else if(toolSel=="CIRCLE" && circleTool) geom = circleTool.getCircle(); else

return; if(!geom) { alert("selected region is null!"); return; } highlightTheme = new MVThemeBasedFOI('highlight_theme', 'mvdemo.geotags_select'); highlightTheme.setQueryParameters(geom); highlightTheme.addEventListener("after_refresh", populateTagSelectList); mapview.addThemeBasedFOI(highlightTheme); } //this function is used to manually create an HTML report of all the geo-tags //that are within the search area. This report will be displayed in the //region under the Complete Tags List region. function populateTagSelectList() { var result=""; var theme=mapview.getThemeBasedFOI("highlight_theme"); if (theme!=null && theme.isVisible()) { var foiarray=theme.getFOIData(); if (foiarray!==null) for(var i=0;i<foiarray.length;i++) { result=result+"<tr>"+ "<td class=\"t15data\">"+foiarray[i].name+"</td>"+ "<td class=\"t15data\">"+foiarray[i].attrs[1]+"</td>"+ "<td class=\"t15data\">"+foiarray[i].attrs[2]+"</td>"+ "<td class=\"t15data\">"+foiarray[i].attrs[3]+"</td>"+ "<td class=\"t15data\"><a href='javascript:onclick=recenter("+ foiarray[i].x+","+foiarray[i].y+");'>where</a></td></tr>"; } } if (result!="") { result="<table class=\"t15standard\" border='1' width='100%' cellspacing='0' cellpadding='2'>"+ "<tr><th class=\"t15header\" >NAME</th><th class=\"t15header\" >DESCRIPTION</th><th class=\"t15header\" >UPLOADER</th>"+ "<th class=\"t15header\">TYPE</th><th class=\"t15header\">LOCATION</th></tr>"+result+"</table>"; } var div=document.getElementById("tag_select_list"); div.innerHTML=result; } //this function is used to clear/remove the search result tag list. function clearTagSelectList() { var div=document.getElementById("tag_select_list"); div.innerHTML=""; }

hands-on lab: developing an interactive mapping ... lab: developing an interactive mapping...

Documents