A perfect case study for the development of APEX Plugins is the integration of Google Maps into APEX. The Plugin we will develop here should not only show a part of a map, it should also provide the ability to place multiple markers on the map. The positions of the markers will be passed as a string which contains a JSON object. All the other information will come from settings of the Plugin itself. In the most cases, the GPS position we want to place on the map, came out of the database. Therefor we need a PL/SQL Function which converts this data into a JSON string. All the required functions are described in this article. To see a Demo of the Plugin, click here!

Basics

Since version 4.0 it is possible to extend the functionality of APEX with theso-called "Plugins". The plugins are used in the APEX Application Builder like ordinary components (eg. items, buttons, forms, etc.). According to there use, Plugins are separatedin the following types:

Region Type Plugins

Item Type Plugins

Dynamic Action Plugins

Process Type Plugins

Plugins are ideal tools to modularizeand adapt APEX applications to individual needs. An APEX Plugin is characterized by the fact that all files and programs that are necessary for the plugin are managed together in one place. These are PL/SQL-Programs and/or JavaScript code as well as CSS and image files. This makes it possible to reuse a Plugin and so it is quite easy to install it in another APEX environment.

The Development of the Multi-Marker-Map Plugin

Considerations

The functionality of our new Plugin, has already been described above rudimentary. It is an "Item-Type" Plugin, which has the ability to show a Google-Map with multiple markers. So one problem to be solved is, how to pass the unlimited number of marker positions to the plugin. So the first idea is, to store each marker position in an Array. But that could be very difficult because it is not easy to pass arrays from PL/SQL to JavaScript. On the other hand we need JavaScript to integrate the Google Maps API. The solution is a JSON string. Within the PL/SQL Programm we generate the data into a string in JSON notation, to pass it to JavaScript (that's no problem). In the JavaScript function it is quite easy to convert this string into a real JSON. Perfect!

In summary we need:

the knowledge of the Google Maps API

a PL/SQL function which automatically will be called during the rendering of the page (so called Callback function)

a JavaScript function, which is the interface to the Google Maps API

The Plugin also needs a few parameters to control the size of the map, the zoom factor and a name to make sure that the ID of underlying HTML-Object is unique. For further use we can extend this Plugin by additional functionalty but for now we want to keep it as simple as possibe. For that please refer the Google Maps API.

Step 1: Create the Plugin

Plugins are managed within the Applicatin under the Shared Components. Here you can import any existing Plugin as well as create a new Plugin (see Fig. 1, 2).

Fig. 1: Shared Components

Fig. 2: Plugin Dialog within the Shared Components

After the creation of the (sill) empty Plugin, we have to enter some basic information. A Plugin allways has two names: The external name appears everywhere, where a developer can choose a Plugin. The intention behind the internal name is to share the Plugins in a worldwide community. So it is necessary to give it a unique name. Therefor it is recommendet to use the URL concept for the internal name. We choose GoogleMaps and com.apex-plugins.googlemap as external and internal name. Because, our new Plugin will be used on pages as a Page-Item we choose the type Item. Thats all so far to save the Plugin (see Fig. 3).

Fig. 3: create Plugin

Step 2: Programming

Now, the Plugin is saved rudimentary and it is available for the application developers BUT the functionality of the Plugin is still missing. To place the program code, we have three kind of so-called Callback Functions:

Render Function: the most important function; it is used during the runtime when the page is rendered.

AJAX Function: Dynamic "on-demand" processes can be programmed in this callback function. In this function you have also access to the global apex variables.

Validation Function: Any validation process should be programmed here. Errors will be returned in the predefined record t_page_item_validation_result

The PL/SQL Rendering Function

The Rendering Function contains all the code which is needed during the rendering to display the element of the Plugin on the page. This can be simple HTML code as well as function calls to JavaScript libraries. In our example we use this to call the Google Maps API. The name of the function doesn't matter. The only thing to take care are the parameters because these are fixed. The name for the rendering function has to be entered in the section "Callbacks" in the appropriate field. (see Fig. 4).

Explanation

The effective name of the render function has to be entered in the section Callbacks to tell APEX which function is to call during rendering. Parameter and return value are fixed.

15

The local variable l_map_width stores the content of the custom attribut 1 of the Plugin.

19

The value of the item will be transfered into the local variable l_location. This value stores the JSON string with the GPS positions.

25-36

If the page is shown "printerfriendly" the item will be invisible; if it's "readonly" the item is "displayonly".

39

Include the JavaScript library of the Google Maps API

45

Include our own JavaScript library where the communication to the GoogleMaps API is programmed. (see next chapter)

51-53

Place the Item on the Page with the given layout (width, height)

56-73

The function add_onload_code is inserting the JavaScript code which is loaded when the onload-trigger is executed. This calls the function which is included in line 48.

76

Return the record of the type T_PAGE_ITEM_RENDER_RESULT which a least should contain a "TRUE" if the item is navigable.

The JavaScript Function

In the PL/SQL Program above, the JavaScript function googleMap will be called during the onload-event of the HTML page. This function creates a connection to Google Maps and places the markers on the map. To use our own JavaScript function within a Plugin, we have to upload it first in the section Files of the Plugin (see Fig. 5). The name of the JavaScript file is used to include it within the PL/SQL Program with the add_library function. Be careful and don't forget to leave the extention ".js"!

Assign the values of latitude and longitude to align the map; create a new GoogleMaps object LatLng to pass the position to the map.

33-37

Assign the settings of the map like zoom-factor or map-type ("ROADMAP").

38-41

Show the map at the position given in the parameter map_id

43

Determine the number of markers (with the length of the markers array)

45

The "Info Window" is to show the name of the marker

47-54

Create a new marker with the given information of a particular "marker" and place it on the map.

55-60

Add a listener to show the info window when click on the marker

Step 3: Plugin Attributes

Standard Attributes

Step 3: Plugin AttributesAll Object which are used within APEX have several attributes to adjust the size, apperance, etc. of the item. For our new GoogleMap item we have to set which attributes can be used. This can be done in the section "Standard Attributes". (see Fig. 6).

Fig. 6: selected Attributes for our Plugin

Custom Attributes

Beyond the standard attributes we need a few adjustments to control the appearance of the map. These settings are individual and depend on the type of Plugin. In our case we need the size (width, hight) and the default zoom-factor. In addition we should have a seperate name to make sure, that the HTML object will have a unique name. We can access these attributes very easily from PL/SQL (as we saw in the code snippet above). For each of these attributes we add an entry in the section Custom Attributes as shown in Fig. 7,8)

At the end we should have four attributes like in Fig. 9. The sequence of the attributes of course is very important because within the PL/SQL function we transfer the content of the attributes exactly in this order (see line 15-18 of the rendering function).

Fig. 9: The custom attributes of our Plugin

Use it!

If we executed all the described steps correctly, we should now be able to use our new Google Maps Plugin. Therefor just place a new element of the type "Plug-ins" on your page and step through the dialog. You will find the new "GoogleMap" Plugin as well as our custom attributes (see the following pics).