RADE Web Application Composer

What you can do with DialogBuilder

DialogBuilder is an interactive tool that enables you to create JDialog panels. You can:

• Design your window
• Position your widgets on the window and define their attachments
• Set or modify properties to the widgets
• Declare methods on widgets and associate them with events
• Preview the window.

Files associated to DialogBuilder editor are XMLDlg files. They appear in IRAD with the icon. For more information on the JDialog framework, see the JDialog Overview article.

[Top]

What You Need to Know Before Starting

To find out more about the DialogBuilder interface, see Getting Familiar with the Web Application Editor. To know how to create a process, use widgets,..., see Building a Web Application with JDialog.

Working with a CAAV5 workspace in IRAD

DialogBuilder requires a CAAV5 workspace. The CAAV5 file tree is mandatory, because many files are created in specific directories in this file tree. Inside this CAAV5 workspace, you need at least one framework and one module.

There are 2 different ways to do this, depending on the fact that you have the "Java Interactive Dashboard" product available or not.

• if you have the JID product, see the Java Interactive Dashboard article for more information on how to manage your CAAV5 workspace in IRAD (how to open or create a workspace, how to create a framework and module, how to define prerequisites, etc...)
• if you do not have the JID product, use Convert to WAC project. For more information on this command, see Before Starting.

[Top]

Step-by-Step with CAAJdgSmartDictionary

Purpose of the CAAJdgSmartDictionary

CAAJdgSmartDictionary is one of the provided use case for the JDialog framework. See Creating a command use case to see how to create this JDialog window by writing Java code.

The expected result looks like this:

We are going to create the same window interactively using the DialogBuilder.

[Top]

Before Starting 

Before launching WAC, you need to set the JAVA_HOME variable. Otherwise, the following message will be displayed when running the Get prerequisites or the Create/Update RuntimeView commands.

You can set this variable:

• In the system variables.
• In the CAA V5 Development Environment Setup V5R18 window. In this window, select WebApplicationcomposer, double-click JAVA_HOME and enter the desired value (.jdk or jre).

Creating a Web Project

1. From the Start->Programs menu, access the IBM Rational->IBM Rational Application Developer v7.0->Rational Application Developer application.
2. In the Workspace Launcher window, click Browse... to select the directory that will  contain the data. Click OK. The  application opens.
3. From the File menu, select New->Other, then Dynamic Web Project.
4. In the New Dynamic Web Project window, enter the name of your project in the Name field and click the Advanced> button (SmartDictionary in this use case.)
5. In the Servlet version combo box, select 2.4.
6. In the Target server combo box, select Websphere Application Server v6.0 and click Finish.

[Top]

Working With a CAA V5 Workspace

Using Web Application Builder requires to work in a CAA V5 workspace. In order to follow along this scenario, you need a CAAV5 file tree, with a Framework and a java Module. In order to be able to build your java controller associated to your dialog, you also need to specify where are your prerequisites.

There are 2 different ways to do this, depending on the fact that you have the "Java Interactive Dashboard" product available or not.

• If you work with Java Interactive Dashboard (JID): You can create the required CAA framework/module architecture through dedicated custom menus. For more information about the way to manage your CAA V5 workspace in IRAD, see the Java Interactive Dashboard article.

  Create the framework MyFw. To do so, select File>New>Other, CAA elements and then CAAV5 Framework. Create the module "CAAJdgSmartDictionary.mj". To do so, select File>New>Other, CAA elements and then CAAV5 Module. Choose Server as Module Type. Select the CAAJdgSmartDictionary.mj/src directory in the Navigator View, and create the package com.dassault_systemes.smartdictionary using File>New>Other>Java>Package.

• If the Java Interactive Dashboard (JID) product is not installed: IRAD provides you with a custom menu allowing you to create your CAA V5 workspace architecture. To access it:

  Display the Navigator view in IRAD by selecting the Window menu, and select Show View->Navigator. Right-click your project name and point to Convert to WAC project. This opens a wizard where you will need to provide some information as explained below.

1. In the Convert to WAC Project window, select Mkmk (if need be), the Tool level and Next>. The levels available in the list will depend on your install. The tools are initialized. Click Close in the Initializing tools... window.
2. Click Add... in the Convert to WAC Project window to define the prerequisites of the CAA V5 workspace you are creating. A Select Directory dialog box is displayed.
3. Browse to the directory containing the runtime view and click OK.
4. Click Next> once your prerequisites are defined. The Installing Prereqs dialog box is displayed. Click Close when the installation is done.
5. Click Close in the Eclipse Setup window.
6. In the Framework name field, enter the framework name: MyFw and click Next>.
7. In the Module name field, enter the module name: CAAJdgSmartDictionary and click Finish. The Navigator view now displays the generated folder and the files matching the required CAA V5  workspace architecture (see picture opposite.)
    

The final step consists in creating a new Java package for the generated classes that will contain the generated business logic driving the behavior of your web application.

1. Expand the CAAWebApplication folder in the Navigator view.
2. Right-click the SampleFw/SampleMd.mj/src folder and select New->Other->Java->Package to display the window below. Click Next>.
3. In the Name field, enter com.dassault_systemes_sample1.
4. Click Finish when done.

 Running the Application on a WebSphere Test Environment

Create a new JDialog to start the local test server. To do so, select your web project in the Navigator view, and select Run >Run on server from the contextual menu. Wait until the server is in the state "started".

1. Open the Server perspective. To do so, from the Window menu, select Show View->Servers.
2. In the Server Configuration view, right-click and select New->Server. The New Server dialog box is displayed.
3. Select WebSphere v6.0 Server and click Finish.

• Customize your server. Right click your WebSphere v6.0 Server@localhost, and select Start.

The following editor appears:

• Right-click your application in the Navigator view, and select Run->Run on Server.

[Top]

Creating a Dialog 

1. Select File/New/Other.../CAA e-application/JDialog File and click Next. 

   

2. In this window, select the CNext/resources/dialog directory in the framework where the new XMLDlg file will be created for your window. Then, select the module and the package where the java controller will be generated. 

   If an empty list appears in the package selection window, check that your selected module is defined as a Source directory in your project. If not, use the CAA Project/Update-Generate Projects... window to declare this module as an IRAD project.

3. Enter CAASmartDictionaryController as the controller class name associated to the window. Finally, choose the widget type of the root container of the window. "Frame" is selected for the sample.
4. Click Finish. The following files are created:
   • The .XMLDlg file for the window description (created in MyFw\CNext\resources\dialog directory)
   • The .CATNls file for all NLS titles, images, and texts in the window (created in MyFw\CNext\resources\msgcatalog directory)
   • The .java file for the controller associated to the window (created in MyFw\CAAJdgSmartDictionary.mj\src\com.dassault_systemes.smartdictionary)

   The DialogBuilder interactive editor is activated. Its toolbar is inserted, and the editor is opened on the Layout tab page, showing an an empty Frame. Your framework IdentityCard.h and your module ImakeFile.mk have been automatically updated to add CATJDialog, CATJSystem ans CATJsyODT as compiling prerequisite modules. 

   If you used Open CAAV5 workspace: For the compilation to take into account these new prerequisites, run mkGetPreq using CAA Project / Get Prerequisites.... In this window, select Access prerequisites from their origin location (mkGetPreq) or Copy prerequisites from origin location to a local directory and access them there (mkCopyPreq+mkGetPreq). The second mode corresponds to a simple mkCopyPreq command, and is not valid here. Do not use UNC path for prerequisites workspaces. IRAD does not support UNC path, so if a prerequisite workspace is not local, map a network drive, and use this drive instead of the UNC in the Get Prerequisites... window. If you used Convert to WAC project, your prerequisites have already been defined. This command will also automatically update your classpath to add CATJDialog.jar, CATJSystem.jar and CATJSyOdt.jar. This last operation can also be done independently using CAA Project/Update libpath based on makefiles.   If you used Convert to WAC: For compilation of the controller with IRAD without error, you need to update the ClassPath of your project in order to add CATJDialog.jar, CATJSystem.jar and CATJSyOdt.jar. Since you have already defined your prerequisites during the step "Convert to WAC", and since CAA Project/Update libpath based on makefiles... is not available without JID, do this manually: select you project in the Navigator view for example, and select Properties in the contextual menu. In the window, select Java Build Path, then the Libraries tab page. Click Add External JARs to add these 3 jars.

   Once you have set your prerequisites, you might need to republish and restart the local test Server.

   [Top]

    Defining the Page Setup and Widget Positioning

   • The Title banner of the window

   This title is a Label widget. Click the Label icon in the toolbar. By default, Label1 is created at the top-left in the window. In the outline, you can see that this label is a child of the root frame widget. 

   

   To identify this label, change its name. In the property view change the name field and set the value SmartDictionaryTitle. This is now the name of the widget. By default, the name of the widget is also the text displayed for the label.

   

   Now we want to give an NLS Title to this widget (different from the widget name): another way to modify the properties of a widget is to open the property window. Select the SmartDictionaryTitle in the Layout or in the Outline view, and click Properties in the contextual menu. The properties window is opened. Enter "Smart Dictionary" in the Title field and click OK. Then you see that the new title is displayed in the Layout, but the widget name remains SmartDictionaryTitle in the Outline view. This title is automatically added by the editor in the MyFw\CNext\resources\msgcatalog\CAAJdgSmartDictionary.CATNls file. 

   

   In order to display the title with a bigger font and with a red banner, change the Level property of the label. Set the Level property to 1, using one of the two methods explained previously.

   

   Now, we must change the widget attachment. For the moment, the label is at the top-left of the page, and it should be top centered and take the width of the page. This can be done with the mouse in the Layout tab page. Select the Label. The selected widget is highlighted with a pink frame. Grab this frame and stretch it to the right border of the Layout page. When you get the West-North-East cursor, release the mouse. The cursor will reflect that the widget is attached on left-top-right borders of the cell.

   

   • The Label and Combo Box for the Source Language

   Select the CATSmartDictionaryController frame in the Outline View, and insert a Label and a Combo Box using the contextual Menu

   

   The new Label and Combo Box are created as children of CAASmartDictionaryController root frame. Set the widget names to SourceLangLabel and SourceLangCombo as explained before, in the property view of each widget (field name) , and set the NLS Title "Source Language:" to the SourceLangLabel widget.

   

   By default, widgets are added in the first empty cell found. If none is found, a new row is added at the bottom of the page. In our sample, each widget is added to a new row. You need to move SourceLangCombo on the same row as SourceLineLabel. Use the mouse to drag the widget to its desired position. Select the Combo Box, and keep the mouse button pressed. The 3 cells of the grid layout are displayed with thin black lines.
   Move the Combo Box to the right of the SourceLangLabel cell. The future place of the Combo Box is symbolized with a small square . 

   

   Release the mouse, and a second column is created to contain the Combo Box.

   

   You can notice that an "empty cell" is created on the first row, near the SmartDictionaryTitle. Stretch again this label over the 2 columns so that it takes all the width of the page.

   Now you want to put the SourceLangLabel closer to the SourceLangCombo. Therefore, select the SourceLangLabel in the Layout, and keep the mouse down. You can see that this widget has a North-West attachment in the cell. Move the widget to North-East of the cell, and release the mouse. The Label is now closer to the Combo Box.

   

   You can now specify the SourceLangCombo content. Double-click SourceLangCombo in the layout or in the Outline view. The Properties window is displayed. Click Object contents. In this window, you can enter the list of the languages to be displayed in the combo box. Add English, French, German, Spanish, Italian and click OK.

   

   You should now see the following Layout:

    

   • The Label and Combo Box for the Destination Language

   Repeat the same steps for the Destination Language Label and Combo Box. Widget names are DestLangLabel and DestLangCombo. The NLS Title for DestLangLabel is "Destination Language:", and the content of DestLangCombo is French, English, German, Spanish, Italian. The result is the following:

   

   • The Enter Text Label and Text Field

   Repeat the same steps to insert a label and a TextField. Widget names are EnterTextLabel and WordZone, and the NLS Title for EnterTextLabel is "Enter Text".

   

   • The Translate button

   Insert a button. The widget name is TranslateButton and its NLS Title is "Translate". By default, a new row is created to insert this button, and the button is in the first column of this row. Drag the button over to the second column as explained before.

   

   • The Result

   Insert now 2 Labels for the Result. Widget names are ResultLabel and ResultZoneLabel. The NLS Title for ResultLabel is "Result:" but the text for the ResultZoneLabel is not static and will be dynamically managed by the java controller. By default, ResultLabel is created in the first empty cell found (first column of the fifth row), and the ResultZoneLabel is created in the first column of a new row. Drag the labels in the correct cells.

   

   • Resizable rows and columns

   Now, if you compare your window layout with the expected result, you can notice that there is more space between rows. By default, the total height of the window is divided by the number of rows, and the total width is divided by the number of column, depending also on the size of the widget displayed in each cell. In our example, the height is divided in 6 equal rows, and the width is divided in 2 columns almost equal. You can change it by specifying extendable rows and columns. Click the thin red line in front of the last row. Since it has now become the only extendable row in the window, it will extend to take as much space as possible. The first 5 rows now occupy the minimum necessary place to display the titles, and the remaining space is left for the last row. Had there been several extendable rows, the fix rows would have taken the minimum place to be displayed, leaving the remaining space to be shared between the extendable rows. The same mechanism exists for extendable columns. Click the thin red line of the last column.

   

   The layout of your window is now complete. Save your work using File/Save or Ctrl+S. All associated files (.XMLDlg, .CATNls, .java) are automatically saved.

   [Top]

   Declaring Java Variables in the Controller

   To define the behavior of your window in the java controller, manage the widgets through associated java variables. In this example, you will need to retrieve the selected languages in the 2 combo boxes, as well as the text to be translated, and set the result of the translation. Each widget being mapped to a java variable, you need 4 java variables in this example.

   We start by declaring the java variable _srcLangCombo associated to the SourceLangCombo widget:

   1. Select the SourceLangCombo widget in the Layout or in the Outline View. Set the value _srcLangCombo for the property "variable name" in the "Properties view" or in the "Properties window". 

    

   2. Set following other java variables on widgets:

   Widget	variable
   DestLangCombo	_destLangCombo
   WordZone	_wordZone
   ResultZone	_resultZone

   Now, the java controller contains 4 java variables declarations.

   [Top]

   Declaring Callbacks in the Controller

   In this application, the only method you need is the callback associated to the TranslateButton activation.

   1. Edit the "Properties window" on the TranslateButton Widget. In this window, there is a frame named "Events". It contains all events available for a push button. You must declare an associated callback when the button is activated. So for the "onButtonActivated" event, declare a method named "onTranslate". This method will be automatically added to the java controller with the default arguments for a callback.

   

   2. Save your work with Ctrl+S.
   3. Edit the java controller file MyFw\CAAJdgSmartDictionary.mj\src\com.dassault_systemes.smartdictionary\CAASmartDictionaryController.java:

      

   4. You can fill the body of the onTranslate method, corresponding to the documented JDialog Use Case, and save the file.

      // // Java Method generated: fill body public void onTranslate(CATDialog iDialog, CATNotification iNotification, Object iData){ _resultZone.setTitle("translate "+_wordZone.getText()+ " from "+_srcLangCombo.getSelection()+" to "+_destLangCombo.getSelection()); }

      [Top]

      Getting a Preview of the Window

      You now want to check that your window has been correctly defined, and that it runs correctly in a Web server project.

      Since your CAAV5 workspace has been defined as a Web Project in IRAD, you can use Run on Server in the Navigator view. When the server is started, select the Preview tab page in the DialogBuilder editor. 

      You can also run your application in a standard  web browser. To do so, remember to: Run mkrtv using CAAV5 Workspace->Create/Update Runtime View. Use Run on Server to start the server. Enter the following URL in the browser: http://localhost:9080/WebTest/html/CAAJdgSmartDictionary.

      While you design the layout of the window, the corresponding XMLDlg and CATNls files are created under the framework. Since the preview fetches files under the runtime view, an update of the runtime view is run transparently whenever you activate the Preview tab page.

      Select a source language and a destination language in the predefined list of languages in the combo boxes, enter a text to be translated, push the button Translate. The result is displayed in the result zone. The preview tab page offers more than a simple rendering of the window because your java code is also being executed in the web server.

      

      ---

      In Short

      Creating a JDialog window involves 4 steps:

      1. Defining the content and the layout
      2. Declaring java variables
      3. Declaring methods on events
      4. Getting a preview of the window.

      [Top]

      ---

      References

      [1]	JDialog Documentation HomePage
      [2]	JDialog Overview
      [3]	CAAJdgSmartDictionary JDialog Use Case
      [4]	Java Interactive Dashboard
      [Top]

      ---

      History

      Version: 1 [November 2006]	Document created
      [Top]

      ---

      Copyright © 1994-2005, Dassault Systèmes. All rights reserved.