Developing ArcGIS JavaScript API portlets with NetBeans

It is quite easy to use the ArcGIS JavaScript API in a portal environment, although there are some considerations that have to do with portlet development as opposed to jsp/servlet development. The samples provided in the ArcGIS JavaScript API Resource Center are not intended to be deployed in a portlet container but with some minor tweaks we can get any of them up and running.

A Portal page is a single web page that is used to display content collected from multiple sources. Portlets are individual web applications intended to display content on a portal page. To the user, a portlet is a single window on a portal page. To developers, portlets are Java based modules that can be plugged into a larger portal page. Finally, a portlet application is a collection of portlet modules that are packaged together for deployment. Portlets within the same portlet application can share information and context allowing inter-portlet communication and sharing of resources, property files, and support classes. Portlets are managed by a portlet container and consequently they have to be prepared and deployed in a portlet specific manner according to either vendor or portlet version specifications.

Let’s walk through the steps to create a simple ArcGIS JavaScript API JSR 168 Portlet application. The steps will use NetBeans 6.1 with Portal Pack 2.0 plug-in installed and we will deploy to GlassFish server with OpenPortal Portlet Container installed. Portal Pack is a set of plug-ins for NetBeans IDE which provide portlet development and deployment support. Open Portal Portlet container is an enterprise-class standard Java Portlet Container (Portlet 1.0/2.0).

Create a Portlet Project

1. In NetBeans, select File -> New Project -> Web -> Web Application.
   
   
   
   
2. Enter the Project Name and location and click Next.
   
   
   
   
3. Ensure the Portal Server Container is selected and click Next.
   
   
   
   
4. Under Frameworks, select ‘Portlet Support’ and choose Version 1.0 to build a JSR 168 portlet project (Version 2.0 is for JSR 286 portlet projects). Check 'Create Portlet' and 'Create Jsps' and fill in the Package and Portlet Class Name. Uncheck the Portlet Mode 'Edit'.
   
   
   

The portlet application is now created with a default portlet class and relevant jsp files. The portlet configuration file, portlet.xml, is updated with the portlet we created through the wizard. We will now edit the view mode jsp file to add a simple ArcGIS JavaScript API map.

Update source

The new project wizard created the Portlet class and jsps for view and help modes. Your directory structure should look similar to this:

Open up your view mode jsp file, AgsJsApiPortlet_view.jsp, and delete all generated content. We will now edit the page to include an ArcGIS JavaScript simple map sample. Copy and paste the code below into your view mode jsp.

<%@page contentType="text/html; charset=ISO-8859-1"%>
<%@page pageEncoding="UTF-8"%>

<%@taglib uri="http://java.sun.com/portlet" prefix="portlet" %>

<portlet:defineObjects/>

<div id="esrimap">
  <link rel="stylesheet" type="text/css" href="http://serverapi.arcgisonline.com/jsapi/arcgis/1.1/js/dojo/dijit/themes/tundra/tundra.css">
  <script type="text/javascript" src="http://serverapi.arcgisonline.com/jsapi/arcgis/?v=1.1"></script>

  <script type="text/JavaScript">
    dojo.require("esri.map");

    function init() {
      var map = new esri.Map("<portlet:namespace/>");
      map.addLayer(new esri.layers.ArcGISTiledMapServiceLayer("http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_Imagery_World_2D/MapServer"));
    }

    dojo.addOnLoad(init);
  </script>
  <div id="<portlet:namespace/>" class="tundra" style="width:400px; height:300px; border:1px solid #000;"></div>
</div>

The jsp is like any typical jsp with an added <portlet:defineObjects> tag. The portlet specification mandates the portlet container to provide an implementation of the portlet tag library. The portlet tag library enables jsp's included in portlet projects to have access to portlet objects. In order to use the tag library we declare it with the statement:

<%@taglib uri="http://java.sun.com/portlet" prefix="portlet" %>

When using the ArcGIS JavaScript API, we typically include at least one style sheet and required scripts. Our simple map portlet uses the following style sheet for graphic elements inside our map DIV:

<link rel="stylesheet" type="text/css" href="http://serverapi.arcgisonline.com/jsapi/arcgis/1.1/js/dojo/dijit/themes/tundra/tundra.css">

And this is a reference to the location of the ArcGIS Server JavaScript API files:

<script type="text/javascript" src="http://serverapi.arcgisonline.com/jsapi/arcgis/?v=1.1"></script>

The next script is where we put our JavaScript code for working with the map. First we reference a package, initialize a map, and then add an event:

<!-- map package referenced using dojo.require()   -->
dojo.require("esri.map");

<!-- initialization function to add a layer to the map -->
function init() {
	var map = new esri.Map("<portlet:namespace/>");
	map.addLayer(new esri.layers.ArcGISTiledMapServiceLayer("http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_Imagery_World_2D/MapServer"));
    }

<!-- the addOnLoad() event which takes in the init function as a parameter. -->
dojo.addOnLoad(init);

Although we do not need to edit our portlet class file generated by NetBeans, let's have a look at the doView() method to inspect what is happening. I added some comments to help understand the generated code.

 
public void doView(RenderRequest request,RenderResponse response) throws PortletException,IOException {
    // Set the MIME type for the render response        
    response.setContentType("text/html");    
    // Invoke the JSP to render and include the response  
    PortletRequestDispatcher dispatcher =
      getPortletContext().getRequestDispatcher("/WEB-INF/jsp/AgsJsApiPortlet_view.jsp");
    dispatcher.include(request, response);
}

Deploy and test

To run the portlet, right click on the project and click “Run”. NetBeans will first deploy the portlet on the portlet container configured with the project. If deployment is successful, NetBeans will open the configured browser and display your portlet within the Portlet Container Driver as shown below:

Can I have multiple maps in a single portal page independent of each other?

Yes, in order to have multiple maps in a single portal page, you must make the same considerations as required in a standard HTML page containing multiple instances of the same ArcGIS JavaScript API applications. There are two main requirements to consider, 1. A portal page can only have a single reference to the ArcGIS JavaScript API from any of the portlets it includes and 2. Use a unique identifier for each map (the <portlet:namespace/> tag generates a unique id and is recommended here). Using the example provided above, we could add another ArcGIS JavaScript Map Portlet with the following code, taking note of the comments where we remove the ArcGIS JavaScript API reference and ensure our map has a unique identifier:

<%@page contentType="text/html; charset=ISO-8859-1"%>
<%@page pageEncoding="UTF-8"%>

<%@taglib uri="http://java.sun.com/portlet" prefix="portlet" %>

<portlet:defineObjects/>

<div id="esrimap">
   <!-- REMOVED JSAPI SCRIPT AND STYLESHEET REFERENCE -->

  <script type="text/JavaScript">
    dojo.require("esri.map");

    function init() {
      <!-- UNIQUE IDENTIFIER FOR EACH MAP -->
      var map = new esri.Map("<portlet:namespace/>");
      map.addLayer(new esri.layers.ArcGISTiledMapServiceLayer("http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer"));
    }

    dojo.addOnLoad(init);
  </script>
  <!-- REFERENCE UNIQUE IDENTIFIER FOR EACH MAP -->
  <div id="<portlet:namespace/>" class="tundra" style="width:400px; height:300px; border:1px solid #000;"></div>
</div>

Contributed by Dan O'Neill of the ArcGIS Server Java development team.