Essential ATG Dynamo Training - Got atg Certified Relationship Management Developer?
This is not an official ATG site: ATG, Dynamo, Scenario Server and Personalization Server are trademarks or registered trademarks of Art Technology Group
Articles Exercises Resources Links Search

Planning, Development and Deployment of a Portal Gear Using Dynamo 5.5

Part 1 - Planning and Setup

Part 2 is here : Part 3 is here

July 18, 2001 : Version 1.0

Introduction

This document describes the planning, development and deployment of a Portal Gear. Following the steps in this guide you can successfully build your own gears to enrich your customers portal experience.

The guide assumes familiarity with the basic Dynamo concepts as would be gleaned from the Dynamo Essentials Instructor lead course offered by ATG Educational Services.

This is a multi-part document. This first piece describes the problem statement and then begins to solve it.

This document describes the set up and configuration of a template JSP Gear and a simple community using that gear for viewing as HTML or via a WAP enabled device.

Further documents are planned to:

  • Add full configuration
  • Flesh out this Gear using EJBs and messaging.

Contents

Problem Statement

    Gear Modes

    Display Modes

    Device Outputs

    Gear Alerts

    Roles

Developing the Gear (Part 1)

    Creating the LottoGear Application

Registering the Gear with PAF

    The Portal Manifest File

    The Portal Admin UI

Viewing the Gear

    HTML Browser

    WAP Browser

Problem Statement

Write a gear which displays lucky lotto numbers for a user.

Gear Modes

Content – Main Display

  • Display the 'greetingMessage'
  • For subscribers:
    • Display 'batchCount' sets of 'numberCount' numbers between 'minNumber' and 'maxNumber'
  • For non subscribers
    • Display request subscription button

Preview – Static Preview Content Display

  • Display a made up 'greetingMessage' and 2 sets of 6 numbers

Initial Configuration

(the mode that allows configuration of the gear at the time the gear definition is installed by the portal administrator)

  • Specification of ‘sendNumbersEnabled’. This flag controls whether the gear displays the button to send the numbers to the current user via email. Checking this option means that the administrator should have configured a listener for the ‘com.atg.training.Lotto.SendNumbers’ gear alert.

Install Configuration

(high-level administrative customization, for example, determining whether a gear will be configurable at lower levels or specifying a source for a content feed)

  • Specification of 'maxBatches'

Instance Configuration

(customization options for a specific page or community)

With the idea that a given community will be interested in a specific lotto, like the California state lotto

  • Specification of 'greetingMessage'
  • Configuration of 'minNumber', 'maxNumber, 'numberCount'

User Configuration

(customization options an individual community member may set for his/her own view of the gear)

Allow the user to specify how many sets of numbers they want

  • Configuration of 'batchCount' up to 'maxBatches'

About

(information about the gear; for example, author, copyright, and version)

  • Display ATG Training information links to www.atg.com

Help

(assistance with using the gear)

Displays configuration help on the properties with information on the current settings and who can set them

  • sendNumbersEnabled
  • maxSets
  • greetingMessage
  • numberCount
  • minNumber
  • maxNumber
  • setCount

Display Modes

The gear will support both modes

  • shared - Compact view of the numbers
  • fullpage - Larger view of the numbers

Device Outputs

The gear will support both outputs

  • HTML
  • WML

Gear Alerts

  • com.atg.training.Lotto.SendNumbers
    • Support the option of send an alert when the user clicks the send me my numbers button
  • com.atg.training.Lotto.SubscribeRequest
    • Sent when a user requests a subscription

Roles

There are one role for this gear

  • Subscriber: someone who is allowed to see the numbers

Everyone else will see a button to request a subscription in the content view

Developing the Gear (Part 1)

Creating the LottoGear Application

  1. In the ACC select J2EE Deployment
  2. Select File->Create New J2EE Application and supply project and application names, PortalTraining and LottoGear respectively:
  3. Double click the LottoGear Application to bring up the application editor and select <unnamed> to edit the main application properties. Fill in the Application details and save the application by clicking the save button:
  4. Select ‘Web Modules’, enter ‘web-app’ as the web module name and click create
  5. Click on web-app.war and fill in the Display Name and description fields, then save the application using the save button at the top right of the window:
  6. To view any pages inside the web application directly through the browser or register our gear pages with the PAF we need to specify a context root for the web module. Do this on the ‘Server’ tab, specifying ‘/gear/lotto’ as the context root. This value will be used in the gear’s Portal Manifest File. (PMF)
  8. Now we need to import the required jsp tag libraries into this web application. To do this select ‘Tag Libraries’ underneath web-app_war and import the following libraries:

    9. URI

    TLD File Location

    Copy From Location

    /core-taglib

    /WEB-INF/coreTaglib1_0.tld

    /DAS/taglib/coreTaglib/1.0

    /dsp

    /WEB-INF/dspjspTaglib1_0.tld

    /DAS/taglib/dspjspTaglib/1.0

    /paf-taglib

    /WEB-INF/pafTaglib1_0.tld

    ** See Note **

    Note: If pafTaglib1_0.tld does not appear in the copy from list, copy the files manually from the folders beneath C:\ATG\Dynamo5.5\Portal\paf\taglib\pafTaglib\1.0. Place the tld file to the C:\ATG\Dynamo5.5\PortalTraining\j2ee-apps\LottoGear\web-app_war\WEB-INF\ folder and the lib file to the C:\ATG\Dynamo5.5\PortalTraining\j2ee-apps\LottoGear\web-app_war\WEB-INF\lib folder.

  9. The follow 3 steps may be done manually or by expanding the attached zip file from the C:\ATG\Dynamo5.5\PortalTraining\j2ee-apps\LottoGear folder. It’s recommended that you still read the steps in order to understand what is being done. Using windows explorer create the following folder structure under C:\ATG\Dynamo5.5\PortalTraining\j2ee-apps\LottoGear\web-app_war. Create two folders full and shared, one for each Display Mode. Under each of these create two folders html and wml. One for HTML browser content and one for WAP browser content:
  10. In each of the folders create one file for each Gear Mode and Device Output you wish to support. Each file should contain the following template code. The most files you could need here is 8 (gear modes) * 2 (Display Modes) * 2 (Device Outputs) = 32. The attached zip file contains all these files for you.
    11. <%@ taglib uri="/paf-taglib" prefix="paf" %>
<%@ taglib uri="/core-taglib" prefix="core" %>
<%@ taglib uri="/dsp" prefix="dsp" %>

<paf:InitializeGearEnvironment id="pafEnv">

<dsp:page>

<%-- set a parameter so we can get to it without JSP escaping --%>
<dsp:setvalue param="paf" value="<%= pafEnv %>"/>
<h1>LottoGear : Work In Progress</h1>
<p>The Requested URL is: <%= pafEnv.getOriginalRequestURI() %></p>

</dsp:page>
</paf:InitializeGearEnvironment>

    In our LottoGear case these are the files we need:

    Mode

    Filename

    Content

    content.jsp

    Preview

    preview.jsp

    Initial Configuration

    initial_config.jsp

    Install Configuration

    install_config.jsp

    Instance Configuration

    instance_config.jsp

    User Configuration

    user_configuration.jsp

    About

    about.jsp

    Help

    help.jsp
  11. Save the application using the save button
  12. Select Tools->Build Application – there should be no errors
  13. Select Tools->Start Application
  14. If you want the application to be started automatically we need to add it to the J2EEContainer. To do this select Tools->Add Application to J2EE Container. This creates a J2EEContainer.properties file in the C:\ATG\Dynamo5.5\PortalTraining\config\atg\dynamo\service\j2ee folder:
    15. #Generated by the Dynamo J2EE Deployment Editor
#Wed Jul 18 17:20:02 PDT 2001
applications+={atg.dynamo.root}/PortalTraining/j2ee-apps/LottoGear
  15. To actuate this configuration setting we need to add a dependency from the Portal.gears module to PortalTraining. We do this because Portal.gears is a codeless module used to load all the required gears, rather than specifying them all individually. (bin\startDynamo -m Portal.gears) Edit the file C:\ATG\Dynamo5.5\Portal\gears\META-INF\manifest.mf to include the new gear’s module, as follows:
    16. ATG-Required: Portal.paf …other modules… PortalTraining
  16. With these settings when you restart Dynamo you should see the following messages, indicating that your module is loaded and the LottoGear application is started:

    **** info /atg/dynamo/service/j2ee/J2EEContainer atg.j2ee.container.J2EEContainerResources->loadingApplication : Loading J2EE application from: C:\ATG\Dynamo5.5\PortalTraining\j2ee-apps\LottoGear
    **** info /atg/dynamo/service/j2ee/Darina Stage directory:C:\ATG\Dynamo5.5\PortalTraining\j2ee-apps\LottoGear
    **** info /atg/dynamo/service/j2ee/Darina Validating configuration
    **** info /atg/dynamo/service/j2ee/Darina Successfully validated configuration.
    **** info /atg/dynamo/service/j2ee/Darina Merging specifier data into base J2EE configuration.

Registering the Gear with PAF

In order to use our LottoGear in the Portal we need to register it with the Portal Application Framework or PAF. To do this we need to write a Portal Manifest File for our gear and then install the gear.

The Portal Manifest File

Writing a Portal Manifest File is best done using copy and paste. So here is a file that you can use for your own purposes. Here we are only registering our content and about modes for brevity.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE portal-manifest PUBLIC "-//Art Technology Group, Inc.//DTD Portal Manifest//EN" 
"http://www.atg.com/dtds/portal/framework/portal_manifest_1.0.dtd">

<portal-manifest name="LottoGear" version="1" author="Portal Team">

  <gear-definitions>
    <gear-definition name="LottoGear">
      <description>An example gear which generates lotto numbers</description>

      <servlet-context>/gear/lotto</servlet-context>

      <dimensions>
        <dimension name="height">noPreference</dimension>
        <dimension name="width">noPreference</dimension>
      </dimensions>

      <gear-modes>

        <gear-mode name="content">
          <display-modes>
            <display-mode name="shared">
              <device-output name="html">/shared/html/content.jsp</device-output>
              <device-output name="wml">/shared/wml/content.jsp</device-output>
            </display-mode>
            <display-mode name="full">
              <device-output name="html">/full/html/content.jsp</device-output>
              <device-output name="wml">/full/wml/content.jsp</device-output>
            </display-mode>
          </display-modes>
        </gear-mode>

        <gear-mode name="about">
          <display-modes>
            <display-mode name="shared">
              <device-output name="html">/shared/html/about.jsp</device-output>
              <device-output name="wml">/shared/wml/about.jsp</device-output>
            </display-mode>
            <display-mode name="full">
              <device-output name="html">/full/html/about.jsp</device-output>
              <device-output name="wml">/full/wml/about.jsp</device-output>
            </display-mode>
          </display-modes>
        </gear-mode>

      </gear-modes>
    </gear-definition>

  </gear-definitions>
</portal-manifest>
  1. Create a portal definition file for LottoGear and save it to C:\ATG\Dynamo5.5\PortalTraining\j2ee-apps\LottoGear\LottoGearPMF.xml
  2. -–BUG—The PMF importer does not create the correct Device Output records in the database. It is necessary to modify the repository by hand via the DCC if you wish to support more than one Device output for a given mode. It’s a little tricky, need to find then new device outputs that were just added and add in the WML URLs where they are missing. Here’s an example of a fixed record:

The Portal Admin UI

  1. Point your browser to http://localhost:8840/portal/admin/
  2. Select ‘Install Gears’
  3. Click the browse button and find the PMF you just created
  4. Click Submit
  5. ‘LottoGear’ should appear in your list of available gears
  6. Go back to the portal admin page http://localhost:8840/portal/admin/ and select ‘Set up and Manage Portal Communities’
  7. Select create new community and enter the community name and the web friendly URL prefix for your community

  8. Click Submit then edit the community you just created, give a short description and change the status of the community to Online, then click Done.
  9. Edit the community again and then click on the ‘Community Pages’ tab

     
  10. Click edit for the Lotto Test Page. Then click add / remove gears
  11. Click LottoGear and click Done. Click Done again

     
  12. Check the LottoGear and click ‘Next>’
  13. Select the single column layout, check that LottoGear appears in the list, click ‘Next>’.
  14. Select a color scheme and click Done

Viewing The Gear

HTML Browser

  1. From the Community Pages page click view to see your page or type int the URL to your community page, http://localhost:8840/portal/lotto_test/Lotto_Test_Page

WAP Browser

  1. If you don't have a WAP browser handy you can download the WAP toolkit from Nokia which includes a WAP device emulator here
  2. If you configured a wml view in your PMF you can view that using a WAP emulator or device. The PAF breaks the portal down into cards which are navigated on the device. Here ‘clicking’ on LottoGear brings up the LottoGear’s WML version
 

copyright 2000-2002 Stuart Jones

ATG Certified Dynamo Development Engineer

Technical Training Advertise your Training Programs for Free! Los Angeles Web Design Shopping Cart Software  Form a Corporation