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.

    Create a new Web application

  2. Enter the Project Name and location and click Next.

    Enter the project name

  3. Ensure the Portal Server Container is selected and click Next.

    Select OpenPortal Portlet Container

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

    Select Portlet Support

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:

Directory structure 

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:

Displaying the portlet 

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>
Two portlets 

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

This entry was posted in Services and tagged , , , , . Bookmark the permalink.

Leave a Reply