> developer > dnu > courses > portal overview page 38

Novell Portal Services Overview and Gadget Development

April 2003

DeveloperNet University Course

Reader Rating    from ratings

Lab 20 - Gadget Development Introduction

• Use of Gadget Runner for testing.
  
  
• Use the Configuration Manager to persist data in gadgets.
  
  
• Learn the interaction of the stylesheets with the Java code.
  
  
• Packaging gadgets for deployment in a production environment.
  
  
• Learn how to control the settings for newly developed gadget.
  
  

There is a considerable room for confusion in the varying (and long) file structures encountered when developing gadgets and in this exercise. A summary of the common structures is as follows.

NPS SDK and the gadgetRunner Environment

• <NSPSDK> - the install root of the NPS SDK.
  
  
• <NPSSDK>/samples/ - sample code fro the SDK.
  
  
• <NPSSDK>/tomcat/webapps/nps - the web application directory for the gadgetRunner tool.
  
  
• <NPSSDK>/tomcat/webapps/nps/WEB-INF/classes - classes directory for gadgetRunner.
  
  
• <NPSSDK>/tomcat/webapps/nps/portal/gadgets/<gadget>/skins - root directory for any XSL skins to be applied to <gadget>.
  
  

NPS Deployment Portal

• <webapps> - the Web Application direcoty NPS is deployed to.
  
  
• <webapps>/nps/packages - the Novell Gadget Package (NPG) deployment target.
  
  
• <webapps>/nps/portal/gadgets/<gadget>/skins - root directory for any XSL skins to be applied to <gadget>.
  
  

Example 1: Gadget Runnner

The Gadget Runner is a simple web server and servlet container that will run a single gadget, allowing you to easily develop and test gadgets locally. The Gadget Runner is installed with the SDK.

1. Run <NPSSDK>/gadgetRunner.bat.
   
   

This should (hopefully) launch the Gadget Runner, open a web browser, navigate to http://localhost:8080/nps and display the HelloWorld gadget, via making the appropriate selection in the pull-down.

2. Make some changes to the output from the HelloWorld gadget (<NPSSDK>/samples/HelloWorld/HelloWorld.java) and save.
   
   
3. Recompile HelloWorld, ensurning that the classfile is output to <NPSSDK>/tomcat/webapps/nps/web-inf/classes.
   
   

You will need the following in your classpath:

• <NPSSDK>\tomcat\common\lib\servlet.jar
  
  
• <NPSSDK>\tomcat\webapps\nps\WEB-INF\lib\<NPSSDK>.jar
  
  

Reload the page and you should now have your new revised HelloWorld gadget displayed! It should look like Figure 51, below.

Figure 51: Revised Hello World.

Example 2: main.xsl and the Configuration Manager

Try substituting the BigLetters.xsl for the main.xsl (i.e. rename BigLetters.xsl to main.xsl) and re-run the gadget in the browser. XSL file found in:

<NPSSDK>\tomcat\webapps\nps\portal\gadgets\...

...HelloWorld\skins\default\devices\default\

Notice how the appearance of the output changes. This highlights the effect main.xsl has on the rendering of the final html displayed by the browser, Figure 52.

Figure 52: Bigger Hello World.

1. Execute the ConfigGadget via selecting ConfigGadget from the pull-down and clicking Run.
   
   
2. Enter some new values for the two settings and update these changes with the Update button.
   
   
3. Stop the gadgetRunner and then relaunch it. Navigate back to the ConfigGadget in the browser, notice how the previous changes are persistent.
   
   

This data is being written by the Configuration Manager to the Tomcat session information. In a production environment, gadget configuration settings would be stored in an LDAP directory, such as Novell eDirectory.

1. Examine the ConfigGadget code (<NPSSDK>/samples/ConfigGadget), paying particular interest to the calls with set and get the configuration data (i.e. the values for setting1 and setting2):
   
   

   .
   .
   // Check each setting to see if we need to update the   config
String setting1 = req.getParameter(SETTING1);
if( setting1 != null && !setting1.equals("") )
{
      setConfigSetting( SETTING1, setting1 );    
}  
   .
   .

These ideas will be used to alter the next example.

2. Choose GetHTMLPage from the pull-down and run this gadget.
   
   
3. Examine the code of GetHTMLPage, notice how the URL is hard coded;
   
   

private static final String URL = "http://www.ebay.com";

4. Examine the main.xsl for GetHTMLPage (in the <NPSSDK>/tomcat/webapps/nps/portal/gadgets/GetHTMLPage directory).
   
   
5. Edit this XSL file so the rendered HTML displays a form so the user may enter a new URL. This new URL will be passed back to the gadget bound to parameter NEW_URL (see the code below). You will need to send the GI_ID and the new URL to the gadget. Take a look at the code snippet below for a clue.
   
   

<FORM>
   <input type="hidden" name ="GI_ID">
      <xsl:attribute name="value">
      <xsl:value-of select="../@id"/>
      </xsl:attribute>
   </input>
   <input type="text" name="NEW_URL" value="http://"/>    
   <input type="submit" name="submitButton"
      value="Change the URL buddy"/>
</FORM>

6. Now we'll edit the code of GetHTMLPage to receive the URL from the browser, save (i.e. persist) this with the Configuration Manager and then use this URL to fetch the web page.
   
   
7. Firstly define some constants for; a default URL, a key name to assign to the new URL to be stored persistently by the Configuration Manager, and the empty string which we'll use later.
   
   

private static final String URL_DEFAULT = "http://www.novell.com";
private static final String URL_KEY = "MyURL";
private static final String EMPTY_STRING = "";

8. Next we'll write a processRequest() method which will catch the user inputs before the gadget output the data via the getData() method. In doing this we persistently store the URL. Remember to check that the URL receive from the browser input is not null or empty.
   
   

public void processRequest(HttpServletRequest req) 
                           throws GadgetInstanceException
{
   String tempURL = req.getParameter("NEW_URL");
   if (tempURL != null && !(tempURL.equals(EMPTY_STRING)))
   {
      setConfigSetting(URL_TAG, tempURL);  
   }
   writeConfig();
}

9. Lastly when we retrieve the content from the URL in the getData() method we'll use our new URL rather than the hard coded one. Note, on the first invocation of the gadget the user has not entered a new URL so the NEW_URL parameter is blank, thus we need to retireve content from a default URL.
   
   

public void getData(HttpServletRequest req, 
                     BufferedWriter out, 
                     Document domTree)
                     throws GadgetInstanceException
{   
   try
   {
      // Open an input stream to the URL
      PortalURL url = new PortalURL( getSession(), 
      getConfigSetting(URL_TAG, URL_DEFAULT));
      .
      .
      .

When working, you should be able to change the URL dynamically.

During the next exercises we will be leaving Gadget Runner and deploying our gadgets into the NPS production environment (i.e. the real portal).

Exercise 3: AvailableSettings.xml

As a gadget developer, you need to inform the portal of any configuration settings required by your gadget. You do this by creating an XML file (normally called AvailableSettings.xml) that describes each setting in detail. This file gets included in the .NPG file created by the Packager and is available to the portal when the gadget is installed.

1. Create a file named AvailableSettings.xml in the same directory as main.xsl for the GetHTMLPage gadget: <NPSSDK>/tomcat/webapps/nps/portal/gadgets/GetHTMLPage/).
   
   
2. Enter the following XML into the file, substituting the text "MyURL" for the tag used to reference the URL in the Configuration Manager (i.e. the tag used in the setConfigSetting() and getConfigSetting() of your code).
   
   

<?xml version="1.0"?> 
<config> 
   <setting>
      <name><![CDATA[MyURL]]></name> 
      <value><![CDATA[http://www.yahoo.com]]></value> 
      <cumulative>0</cumulative> 
      <overwriteable>1</overwriteable> 
   </setting> 
</config> 

3. Save this file.
   
   

Exercise 4: Gadget Packaging

After creating a gadget, you will need to package it for deployment. This SDK includes a utility that compresses a gadget's files into a single file.

1. Run the file <NPSSDK>\packager\packager.bat
   
   
2. Specify the Gadget name (GetHTMLPage) and the Main gadget class (GetHTMLPage).
   
   
3. Change the "info" text on the version number to something meaningful (i.e. 0).
   
   
4. Accept all other defaults and click Next.
   
   
5. When requested to select the main classfiles navigate to the GetHTMLPage.class file and select it. (Located at .../<NPSSDK>/tomcat/webapps/nps/WEB-INF/classes if you installed this into the gadgetRunner).
   
   
6. This gadget does not use any third party jars so skip the "select jars..." request.
   
   
7. When specifying the stylesheet directory, navigate to the directory containing main.xsl (<NPSSDK>/tomcat/webapps/nps/portal/gadgets/GetHTMLPage). Since our new AvailableSettings.xml is now located here, this will be included too.
   
   
8. Click next, then Finish.
   
   
9. The package (GetHTMLPage.npg) will be saved in the ...\<NPSSDK>\packager\ directory.
   
   

Exercise 5: Installing Packages into the Portal

1. Copy the GetHTMLPage.npg to the <webapps>\nps\packages directory for the portal.
   
   

   Note:

   This is not the SDK directory and does not reside under the <NPSSDK>\ structure).
   
   

2. Log in to the portal as admin (NDS admin user name and password).
   
   
3. Click on the Administer The Portal button.
   
   
4. Select Gadgets and then click Update.
   
   
5. Browse to the directory on the portal we installed the package to and Open.
   
   
6. Click Update.
   
   
7. Refresh the portal (via the Refresh All button).
   
   
8. Create a new page and odd the GetHTMLPage to it.
   
   
9. Notice that the Gadget Assignment Configuration screen reflects the settings we placed in AvailableSettings.xml (Figure 53).
   
   

Figure 53: Gadget Specific Configuration.

10. Assign the page to the context containing the users (o=novell).
    
    
11. Re-login as a user within the o=novell context to view our new gadget.