How to extend Add Assets Dialog in CentraSite Control

(How to add your own importer)

This document applies to CentraSite ActiveSOA

1 Introduction

CentraSite Control offers a pluggable architecture that allows you to extend the standard

graphical interface by adding your own features.

More information at:

http://documentation.softwareag.com/webmethods/soal8/dg-plug/overview.htm

Plugins are implemented as Java classes. The points in the code at which

plugins can be added are called extension points.

com.centrasite.control.import is one of these extension points, which makes

it possible to extend CentraSite control with user-defined importers.

Importers make it possible to import specific kind of objects into CentraSite,

e.g. import web services or import types in order to extend the (data) model

of CentraSite. This document has the goal to show you exemplarily, how the

import extension point (com.centrasite.control.import) can be extended, so

that a user-defined importer can be called from add assets dialog (i.e. there

is a new entry in the “Importer” drop down list).

Extension point com.centrasite.control.import in Add Asset dialog

2 Introducing the sample project: ImportMyFile

Goals of the sample project are:

1. Developing an importer, which makes it possible to upload a file into

the temp directory of PluggableUI:

<Tomcat folder>/work/Catalina/<server name>/PluggableUI

Layout of the desired plugin

2. Extending the extension point com.centrasite.control.import, to

integrate the importer into add assets dialog.

Extended extension point com.centrasite.control.import in Add Asset dialog

3 Setting up the sample project

Follow the steps below to set up the Java project for ImportMyFile:

1. Create a new Java project in Eclipse using File > New > Project > Java > Java

Project.

2. Specify ImportMyFile as the project name and check radio button Create project

from existing source.

3. Choose Browse.

4. Navigate to the PluggableUI web application folder of the Software AG Common

Tomcat application. This folder is normally located in Documents and Settings\All

Users\Application Data\Software AG\Tomcat\<version>\webapps\PluggableUI,

where <version> identifies the current product version.

5. Choose the Make New Folder button. This causes an entry New Folder to be

created under PluggableUI. Select the entry New Folder, then from its context

menu choose Rename, then enter the name ImportMyFile.

6. Choose OK.

7. In the New Java Project dialog that becomes visible again, choose Finish.

A new Java project called ImportMyFile has been created due to the previous actions.

This project is now visible in the Package Explorer view in Eclipse.

This project needs to be adapted:

1. Create the following four subfolders of ImportMyFile:

o accesspath

o classes

o xml

To create each of these subfolders, choose New > Folder from the context menu

of ImportMyFile in the package explorer, then type the name in the New Folder

dialog.

2. If not already exist, create a source folder called src. You can create the source

folder by choosing New > Source Folder from the context menu of ImportMyFile.

3. In the context menu of ImportMyFile, choose Properties.

4. Select Java Build Path from the tree on the left.

5. Select the Source tab and enter the value "ImportMyFile/classes" in the field

Default output folder.

6. Switch to the Libraries tab.

7. Choose Add External JARs.

8. In the JAR Selection dialog, navigate to

<PluggableUIFolder>/\WEB-INF/lib

9. Select all files, using for example the key combination Control-A, and choose the

Open button.

JARs located <PluggableUIFolder>/\WEB-INF/lib

10. Choose the Add External JARs button again.

11. In the JAR Selection dialog, navigate to

<PluggableUIFolder>/CentraSiteControl/lib.

12. Again, select all files and choose the Open button.

JARs located in <PluggableUIFolder>/CentraSiteControl/lib

13. CentraSite currently supports both of Java Versions 5 and 6. In order to avoid

incompatibilities, we recommend compiling plugins with Java 5. So make sure

that the Java Compiler properties of the project match the following screenshot.

Java Compiler properties for ImportMyFile project

14. Choose OK to close the properties window.

4 Plugging into CentraSite Control

We have now created a Java project inside the PluggableUI web application. However,

there is one missing piece that tells CentraSite Control that this folder contains a plugin:

the plugin configuration file. Amongst other things, the plugin configuration file contains

the information about where a plugin plugs into in CentraSite Control.

The idea of using plugins to extend an application's functionality is quite simple and

meanwhile well established e.g. in the Eclipse platform. The CentraSite Control software

provides so-called extension points. These are positions in the program logic of the

CentraSite Control program where functionality can be added by a plugin. Every time the

program flow comes to such an extension point, a search for plugins that extend

CentraSite Control at this point takes place and the code provided by the plugin is

invoked.

Let’s convert our arbitrary Java project to a CentraSite Control plugin folder by

providing a plugin configuration file. To do so, follow the steps below:

1. In the context menu of ImportMyFile in the package explorer, choose New > File.

2. Type plugin.xml as the file name and choose Finish.

3. Copy and paste the following XML code into plugin.xml.

<?xml version="1.0" encoding="UTF-8"?>

<plugin id="demo.plugin.ImportMyFile" order="103">

<requiredPlugin id="com.centrasite.control" />

<extension point="com.centrasite.control.import"

id="importMyFile"

class="demo.plugin.ext.ImportMyFilePlugin">

</extension>

</plugin>

4. Save the file using <Ctrl>+S.

First of all a plugin must have an identifier (here "demo.plugin.ImportMyFile") which

has to be unique among all plugins. The order number of a plugin (here "103") gives

CentraSite Control a hint for the sequence in which the plugins have to be loaded at start

up. The higher the number, the later a plugin is loaded.

We need to declare our plugin as being dependent on the plugin com.centrasite.control

because we use an extension point provided by this plugin. This dependency is indicated

through the requiredPlugin XML element.

The XML element extension point denotes that our plugin extends the import extension

point in Add Assets dialog. For a list of all supported extension points, see Extension

Points.

Attribute class specifies the fully qualified name of the class that implements the

extension (here demo.plugin.ext.importMyFilePlugin). The top level package name for all

of our Java code will be demo.plugin. We choose ext as the subpackage name for the

implementing class to denote that code that extends CentraSite Control resides here.

Now we have to implement the extension, i.e. we have to provide a Java class called

demo.plugin.ext.importMyFilePlugin implementing a specific interface required by the

extension point.

1. In the context menu of ImportMyFil/src in the package explorer, choose New >

Class.

2. Specify demo.plugin.ext for the package name, ImportMyFilePlugin for the class

name and com.centrasite.control.extpt.AbstractImport for the superclass.

3. Make sure that the check box labelled with inherited abstract methods is checked

and press Finish.

Eclipse now opens the file ImportMyFilePlugin.java in the Java editor.

Modify ImportMyFilePlugin.java in the Java editor as follow:

package demo.plugin.ext; import com.centrasite.control.extpt.AbstractImport; public class ImportMyFilePlugin extends AbstractImport { public ImportMyFilePlugin () { } public String getName() { return ("ImportMyFile"); } public String getPageDescription() { return ("A simple plugin to demonstrate, how to extend the "+ "import extension point"); } public String getLayout() { return ("/ImportMyFile/importMyFile.html"); } }

4.1 Description of methods

getName()

getPageDescription()

getLayout() This method returns the location of html-file, which is associated with the plugin (see section “Generating the layout of plugin using Application Designer “)

Save the modified file and make sure that no compile errors occur.

When you save the file, the class file is automatically built into the folder classes of the

project ImportMyFile. (the classes subfolder of our project is suppressed from

displaying). The resulting class file is now accessible for the pluggable user interface of

CentraSite Control.

Finally, let's check if CentraSite Control is aware of our minimalist plugin:

Restart the Windows service Software AG Common Tomcat: > Start > Right click on My

Computer > Manage > Services and Applications > Services > Software AG Common

Tomcat > Restart the service.

If everything works fine, the drop down list of importers in the add asset dialog will show

a new entry:

Extended Add Asset dialog

The method getLayout() of class ImportMyFilePlugin is called by choosing the

ImportMyFile Entry and clicking on Next in Add Assets dialog. It returns the

location of the html-file, which is associated with the plugin.

There is a convenient way to generate this html file by drag and drop using

application designer, which is described in the next chapter.

5 Generating the layout of plugin using Application Designer

You can extend CentraSite Control by embedding your own layout pages. In

this step you will learn how to create a layout page using the Application

Designer IDE.

Before we start, let’s preview what the result of this step will be. Here is a

screenshot of the final result of this step. An HTML-based dialog, which

appears on screen after clicking on ImportMyFile entry in add assets dialog.

Layout of the desired plugin

Perform the following steps to initialize the Layout page:

1. Start the application designer 1 (leave your Eclipse instance running).

2. In the Navigation Frame, choose the button with the name of our plugin:

ImportMyFile.

1 The URL (assuming installation defaults) to start the application designer on a

machine where CentraSite is installed is

http://localhost:53307/PluggableUI/HTMLBasedGUI/workplace/ide.html.

3. Choose New Layout.

4. In the resulting dialog window enter importMyFile.xml in the input field labelled

with Name.

5. Left-click on the image with blank window (see screenshot) to create an HTML

page.

To get an idea about how our newly created layout looks initially, select the Preview icon

from the toolbar of the layout painter (located beside the diskette symbol). The current

look of layout importMyFile.xml is displayed in the preview area.

Initial look of the layout shown by clicking on preview

Starting from this layout, we will follow the steps below to create a layout that looks like

the one that is shown at the beginning of this step:

1. First of all, delete the items, which are not needed (titlebar, header and statusbar)

from the layout. To do this, navigate to the Layout tree, right-click on titlebar and

select remove. Delete header and statusbar in the same way.

2. Now, we fill the item pagebody with some entries. Save the layout by clicking the

diskette symbol in the tool bar of the layout painter.

3. Left-click on the Controls button of the button list in the Controls view (located

right to the preview area).

4. Add an Independent Row controls to the body of our page:

1. Left-click on Independent Row and hold the left mouse button down.

2. Drag the Independent Row icon to the page body of the layout.

3. Choose Add as Subnode from the popup menu that appears.

5. Please notice that the pagebody node of the Layout view (located above the

Properties view) now contains one itr subnode, representing the Independent Row

control.

6. From the Controls view, drag and drop a Label control onto the itr subnode of

the pagebody node in the Layout view.

7. In the Properties view (which now presents the properties for the Label control

we just added to the layout) set the name property to "File:" and the width

property to 30.

8. Drag and drop a Horizontal Distance control onto the itr subnode of the

pagebody node in the Layout view.

9. In the Properties view, set the width property for the Horizontal Distance to "10"

by just typing it in.

10. Drag and drop an embedded file upload control onto the itr subnode of the

pagebody node in the Layout view.

11. Set the properties of fileupload2 as below:

12. Drag and drop a Vertical Distance control onto the PageBody. Set the width

property to 30.

13. Save the layout by clicking again on the diskette symbol in the tool bar of the

layout painter. The result should look like below.

Now our layout looks like the one that is shown at the beginning of this step. But we are

not finished yet. Each layout needs to have some code behind it (the so-called page

adapter) which we did not provide yet. Among other things within a page adapter we can

specify how to react on events that occur due to user interactions (the push of a button for

example) or fill the controls with application specific values etc.

Follow the steps below to create an adapter for importMyFile.xml:

1. If not already active, switch to the Home tab of the layout painter.

2. Select Preferences and type in the absolute path for the Java source directory of

our CentraSite Control plugin ImportMyFile.

Tip:

Instead of typing the complete path, you can copy/paste the content of the field

Directory into the field source directory. Then append "/src" to the copied content

(compare with screenshot).

3. Choose the Save and Apply button at the top of the dialog.

4. In the Layout view select the topmost tree node called page (you probably need to

scroll up).

5. Change the model property of page from "DummyAdapter" to

“demo.plugin.ext.ImportMyFileAdapter".

6. Save the layout. The content of the Preview view changes and indicates an error

now. This is normal and can be ignored at the moment.

7. Switch to the Tools tab of Application Designer and select Code Assistant. The

generated code for our page adapter is visible on the right side, now.

We could apply the necessary changes for the adapter class using the Code Assistant. The

more convenient way is doing this inside of our already existing eclipse project to which

we will switch back soon. One more step is missing yet: the code is not stored in the file

system. Hence, press the diskette icon again! Now the adapter source code is stored in the

Java source directory of our CentraSite Control plugin ImportMyFile.

You can close the Application Designer now.

Return to your Eclipse environment. We need to refresh our plugin project. To do so,

select the folder ImportMyFile and press f5 to refresh. After doing this and expanding all

folders that relate to our plugin, your eclipse project should look like the one below.

Please note the contents of subfolders accesspath and xml which were formerly empty.

The contents have been created by our former activities. Most importantly, you should

notice that Application Designer has generated a new class in package demo.plugin.ext,

namely ImportMyFileAdapter.

Note that adapter classes used for plugins to CentraSite Control should be derived from

the class BaseAdapter rather than from the class Adapter as provided by Application

Designer.

Furthermore, we need to implement the interface ImportAdapter. This interface declares

a method (execute( )), which is invoked by clicking on Finish in add assets dialog.

So modify and extend the generated source code as below.

…

public class ImportMyFileAdapter

extends BaseAdapter implements ImportAdapter

{

//is called by clicking finish

public boolean execute() {

// your import code goes here

return true ;

}

public void setOrganization(String arg0) {

}

// further code generated by Application Designer follows here

…

}

Now, you need to implement the generated method-stubs. The method execute() is

invoked when the Finish button is pressed. So here you have to add your import logic

here.

The “Browse” button in your screen will cause a file to be copied to <Tomcat

folder>/work/Catalina/<server name>/PluggableUI. In addition, the method

onFileLoaded() will be called, so you can extend the generated implementation of this

method. To get a feeling how to do this, let us implement exemplarily the method

onFileLoaded().

public void onFileLoaded()

{

outputMessage(MT_SUCCESS, "Upload was successful!");

}

If everything works fine, the result of loading a file should look like the screenshot

below:

Congratulation! The layout is bonded to the adapter now and you can

complete the functionality of your plugin.

Tip: You can optionally extend the extension point

com.softwareag.cis.plugin.plugInInfo to get your plugin listed in

CentraSite control > About >Plugins (see screenshot below). How to do

this is explained in detail here (particularly in step 2).

Extension point com.softwareag.cis.plugin.plugInInfo

Related documents:

The CentraSite Control Pluggable Architecture

http://documentation.softwareag.com/webmethods/soal8/dg-

plug/overview.htm

Step by Step guide: how to use the pluggable architecture to define and

install your own plugins

http://documentation.softwareag.com/webmethods/soal8/dg-

plug/tutorial.htm

Application Designer

http://documentation.softwareag.com/webmethods/cit24/overview.htm

Writing Reports in Application Designer

http://documentation.softwareag.com/webmethods/cit24/devtopics/writingre

ports.htm