Using Web Settings with CODE Designer

CODE Designer is an optional install with WebSphere® Development Studio Client for iSeries® up to Version 7.0 of this product. IBM® WebFacing Tool Version 7.1 and beyond includes Web Setting options that don't exist in CODE Designer. We strongly recommend that you use the Web Setting view of IBM WebFacing Tool for Web Setting customizations.

We recommend that you use the Web Settings with your DDS source to customize your application. You can use the Web Settings tab in CODE Designer to customize how your programs will look and function when accessed through a Web browser. Programs that use DDS source to describe 5250 display screens can be accessed with a Web browser after the DDS source has been converted with the WebFacing Tool. Use Web Settings when you want to manipulate the Web presentation of individual screens and individual fields within screens. If you want to change the Web presentation of multiple screens or of an entire WebFacing project, use Style properties. Installation of CODE Designer is optional.

Loading DDS source in CODE Designer

You can access CODE Designer from the Windows® Start menu of WebSphere Development Studio Client for iSeries or from within IBM WebFacing Tool. To Load DDS source in CODE Designer from within IBM WebFacing Tool:

  1. Open the WebFacing perspective.
  2. Expand WebFacing project > DDS.
  3. Right-click the member and select Open With > CODE Designer. Sign on if prompted. If you do not have a connection to a WebFacing server set up, you will need to create one. You will receive a message if CODE Designer is not installed
  4. Load additional source members from within CODE Designer by selecting File > Open and choosing the DDS source to open from the Open for Edit dialog. The servers available in this dialog are those defined using the Communications Console. Libraries displayed are those in the library list for the user ID you sign on with.
Note: You can also open DDS source in CODE Designer from the Remote System Explorer by expanding an existing connection, right-clicking the source member, and selecting Open With > CODE Editor.

Accessing Web Settings in CODE Designer

After a DDS source member has been loaded into CODE Designer, Web Settings can be accessed by clicking the icons in CODE Designer's DDS Tree. The DDS Tree is located on the left-hand side of the CODE Designer window. Web Settings are also accessible by selecting DDS objects from within CODE Designer's Details and SCREEN tabs. If Web Settings are available for the selected object, the Web Settings tab will be displayed in the bottom pane of CODE Designer.

CODE Designer objects and Web Settings

CODE Designer allows you to design DDS screens graphically. In CODE Designer, each DDS object is represented by an icon or push button. For example, there are push buttons so that you can easily create named fields or text constants for your DDS screen. The Web Settings available for each DDS object vary depending on the object that you are working with. The table below lists the Web Settings available for each DDS object. Refer to the section of this document Web Setting descriptions for more details on each setting. When you use Web Settings for an object, special comments are added to your DDS source which later get processed by the WebFacing conversion. Web Setting comments begin with the characters *%%WB.

Table 1. CODE Designer Web Settings
DDS object CODE Designer graphic Available Web Settings
Standard Record
Subfile Control Record
 
Date Field
Time Field
Timestamp Field
Message Constant
Date Constant
Time Constant
User Constant
System Constant
 
Named Field (Input capable)
Continued Field (Input capable)
Source Reference Field (Input capable)
Database Reference Field (Input capable)
Database Reference Field by Selection (Input Capable)
 
Named Field (Output)
Continued Field (Output)
Source Reference Field (Output)
Database Reference Field (Output)
Database Reference Field by Selection (Output)
Text Constant
 
Date Field (Hidden)
Time Field (Hidden)
Named Field (Hidden)
Continued Field (Hidden)
Source Reference Field (Hidden)
Database Reference Field (Hidden)
Database Reference Field by Selection (Hidden)

Web Setting descriptions

Key labels

For function or command keys in your DDS source, you can specify the text labels to be used in your Web pages to represent the keys. To change a label, select a label from the Labels already defined list, enter the text you would prefer for the key in the New Label field, click Change. To remove a label that you have defined, select the label from the Override labels in web setting list, click Remove.

Key order

For function or command keys in your DDS source, you can specify whether keys will be visible on your Web pages and the order in which the keys will be displayed. To work with this setting, select the Change order and visibility of command keys checkbox. To make a key visible, select the key from the Hidden list and click the arrow button to move it to the Display order list. To hide a key, select the key from the Display order list and click the arrow to move it to the Hidden list. If more than one key is available in the Display order list, the order in which it is displayed can be changed by selecting the key and clicking the Up or Down buttons. If the Change order and visibility of command keys checkbox is not selected, defined keys will be shown in numeric order.

Display size

The Display size setting is available if a secondary display size has been selected for your display file. Secondary display sizes can be set through the properties dialog of the file node icon in the DDS Tree. Use the Display size Web Setting to change the size of the HTML table that will be used to display your application in a browser.

Visibility

Options available for the Visibility setting are Hide Field or Show Field. If Show Field is chosen, the field will be displayed on your Web pages.

Location

Options available for the Location setting are Change span and Change position. After your DDS source has been converted with the WebFacing Tool, your application is positioned on a Web page using an HTML table. The HTML table has the same number of rows and columns as your DDS screen -- that is, 24 by 80 or 27 by 132. With Location settings, you can change how your fields will be positioned on the HTML table after your source is converted.

  • Change span allows you to indicate the number of rows and columns in the HTML table that will be given to your field. A potential use for Change span would be using a graphic in place of the text values that your program originally used to populate the field. For example, the original program may have required 7 columns for text for the field but the graphic that you want to use only requires 2 columns.
  • Change position allows you to indicate the row and column in the HTML table that will be the starting position for your field.

CODE Designer's screen view shows the row and column layout for your DDS source. Use this view to get an idea of how your fields will be positioned relative to each other if you make changes with Change span and Change position.

An additional option for the Location setting is CSS position. The Cascading Style Sheet - Positioning setting enables you to place fields anywhere on a Web page, without restrictions.
  • Row allows you to specify the row value for the field. It must be a positive integer greater than or equal to 1.
  • Column allows you to specify the column value for the field. It must be a positive integer greater than or equal to 1.
  • Offset allows you to specify the number of pixels the field is adjusted to, relative to the row or column value. This number can be 0, or a positive or negative integer.
  • Disable tabbing allows you to indicate whether or not the field can be tabbed to after it is moved. If you select Disable tabbing, the user cannot tab to this field. Otherwise, the field remains in the same tab order it was in before it was moved.
Program defined HTML

With the Program defined HTML setting, check the box Use field value as HTML if the value returned by the field is HTML markup that you would like to use in your page.

User defined HTML

User defined HTML allows you to specify HTML text or tags that can be displayed with or in place of the value for your field. To work with this setting, select the Specify HTML checkbox. In the entry area, enter the HTML tags you would like to use. If you want to use the value for your field as part of the HTML, click the button Insert field value. One example of how you could use this setting would be if you wanted the value for your field to be displayed with a bold font. To do this, use the <BOLD> tag with the &{FIELD.value} text.With this example, edit the entry area so that it displays <BOLD>&{FIELD.value}</BOLD>. If the code for &{FIELD.value} is not there by default, it can be added by clicking the Insert field value button.

Appearance and Text

Options available for the Appearance and Text setting are Change style class, Override field value, Override constant text, and Hide characters:

  • Change style class allows you to specify a style sheet class to be used with the field. As an example, you may want to display all numeric data with a particular font or color and you have defined a style sheet class numeric for this purpose. If you had a customer number field in your program such as custno, you could select the Change style class checkbox and enter the name for your numeric style sheet class.
  • Override field value allows you to specify text that you want to display in place of the returned value for your field.
  • Override constant text allows you to specify text that you want to display in place the value set for a text constant.
  • Hide characters allows you to indicate a range of characters in your field that you do not want to display. For example, if your screen displays a menu of options for a user to choose from and each option is listed numerically (such as: 1. User tasks - 2. Office tasks), you might want to hide the first two characters so that only the text for the option is displayed. In an example like this, you would choose Hide characters and specify a range of From 1 To 2.

Insert HTML

The Insert HTML setting provides a way to customize your fields by adding additional HTML. HTML can optionally be added Before, Inside, and After the HTML tag that is automatically generated for the field. As an example, you might have an input field for employee numbers and at your company all employee numbers are prefixed with 64-. You could make the field easier to use by adding some HTML such as:

Before
<strong>64- prefix mandatory</strong>
Inside
value="64-"
After
<a href="help.htm">Click here for more information on this field</a>

In this example, the HTML Before the field provides some information about the field and uses the <strong> tag so that the information is emphasized with a bold font. Since the HTML generated by conversion uses the <input> tag for input fields, Inside the <input> tag we could add the HTML attribute value="64-" so that the field will be pre-populated with the employee number prefix and your users will not be required to enter it. After the field is the HTML for a link that users can click to get more information about the field.

Ensure that you thoroughly test pages that you are altering with the Insert HTML setting. Changes that you make can conflict with the HTML that is generated by the WebFacing conversion. One way to work around this would be to convert your program without using Web Settings, look at the .html or .jsp source that is generated to see what changes can safely be made with Web settings, apply Web settings and then re-convert.

Options for VALUES

The Options for VALUES setting is available for input fields that are specified with the VALUES keyword. Fields that are specified with the VALUES keyword are displayed on Web pages as a single choice selection box. The options displayed in the selection box are the values given as parameters to the VALUES keyword in your DDS source.

The Options for VALUES Web Setting allows you to change the label or text that is displayed to the user. For example, if one of the VALUES parameters that your program is expecting is "item8", you might change the text that is displayed in a browser to something more descriptive such as "8 gauge wire". While the text displayed to the user would be "8 gauge wire" the value returned to your program would be the same "item8" that the program would expect.

To use this Web Setting, select the Option texts for VALUES keyword checkbox. To set a new label for a VALUES parameter, select the value, enter the text that you want for the label in the New Label field.

Create graphic

Use the Create graphic setting if you want to display an image in place of your field. An example use for this setting would be a product database that includes images of inventoried items.

Populate the File name field with the complete path to an image file on your workstation or with the complete URL to an image file (e.g. http://www.ibm.com/image.gif). The File name field can be populated by entering a value directly or by using the Browse button to locate a local file. Local images that you specify will be copied to the ..\Web Content\images\generated\ directory of your WebFacing project during the WebFacing conversion. The images in this directory are later published to the server when you deploy your project with the Export wizard.

Width in pixels and Height in pixels can be used if you know the dimensions of an image. Adding width and height information can sometimes decrease the time required to render Web pages that contain images.

If there are fields in your program that return values that can be used as part of the image file name, or the full URL to an image file, these values can be added to the File name field by selecting the field from the Choose a field list and clicking Insert field value. For example, if you had &{FIELD1.value} that returned the value bicycle1, you could easily refer to a graphic bicycle1.gif that you may be working with on your workstation. In this example, populate the File name field from the Choose a field list and then add the .gif extension. Files that you identify by using the Choose a field list must be manually copied over to the ..\Web Content\images\generated\ directory.

Create hyperlink

Use the Create hyperlink setting so that your field is displayed as a hyperlink. There are three different approaches available for creating hyperlinks. They are: Specify static URL, JavaScript hyperlink, and Action hyperlink. If you want to override the browser's settings for hyperlink appearance, select the checkbox Override browser's hyperlink appearance with DDS appearance. If you use the Create hyperlink setting along with the Create Graphic setting, your field can be displayed as a graphic that also acts as a hyperlink.

Note: There are some conditions where Action hyperlinks that you create with Web settings will not show up in a browser. This is done to prevent error conditions when the hyperlink does not apply to what is active or available on the browser. For example:
  • The hyperlink is in a record that is not currently the top window or on the top layer.
  • A function key that you have associated with the link is not currently active.
  • A referenced field that is part of the link is not in an active record or is not readable. For example, the record is protected by other records which use the PROTECT keyword.
Override browser's hyperlink appearance with DDS appearance

Most browsers follow a convention for the color and appearance of hyperlinks on Web pages or have settings for hyperlink appearance that users can change. For example, unvisited links may be displayed in blue text and visited links may be displayed in purple text. If you want the browser to display the hyperlink with the same appearance as is used for the field in your DDS, select the checkbox Override browser's hyperlink appearance with DDS appearance.

Specify static URL

If there is a specific URL that you want to be displayed for a field, select Specify static URL. The output value of your field will be the text that is displayed as a hyperlink. The location loaded by the browser when a user clicks the link is the value that is entered in the URL field. If you want the link to launch a separate browser window when it is clicked, enter a name for the window in the Target field. If you leave the Target field blank or enter *SAME, the link will open in the current browser window.

If you are working with a WebFacing portlet project, you can specify *PORTLET in the Target field to open the link within the portlet.

If there is a field value in your DDS that you would like to be part of the URL, select a field from the Choose a field list and use the Insert field value button to add it to the URL field. An example use of Insert field value would be if there is a URL that you want to add additional parameters to. For example, if you had a servlet at a location like http://mysite.com/mywebapp/servlet/MyServlet and the servlet was expecting arguments for a variables called parm1 and parm2, you could use Insert field value to help construct the URL. In this example, your final URL might look like http://mysite.com/mywebapp/servlet/MyServlet?parm1=&{FIELD1.value}&parm2=&{FIELD2.value} where &{FIELD1.value} and &{FIELD2.value} are parameters you added using Insert field value and represent values that change at runtime.
Note: If you would like to use a field value from a different record format to be part of the URL for your hyperlink field, you must ensure that the field will be available on the Web page when the hyperlink is displayed. Fields that are in different record formats can be identified in the Choose a field list because they include the record format name, for example, &{RECORD2.FIELD1.value}. If both record formats are not available on the Web page when the hyperlink is displayed, an exception will occur when the hyperlink is selected.

JavaScript™ hyperlink

Enter the name of a JavaScript function that you want to be called when the link is clicked. For example, enter myFunction() . The function can be one that you have entered using the Insert into script Web Setting, a function that you have defined in an external JavaScript file, or a function that is included with WebFacing in the file webface.js. If you create your own external JavaScript files, put them in the usr directory of your WebFacing project. This directory is located in the path <project name>\WebContent\ClientScript\usr. Any scripts that you put in this directory are available to your WebFacing application at runtime. If you have a short inline JavaScript function, you can also enter the entire function in the JavaScript hyperlink field.

Action hyperlink
Action hyperlink creates a link that when clicked can position the cursor to a field, perform a submit, or a combination of the two. The Position cursor to the field and Submit functions both have values that you can specify.
Position cursor to the field
When the link is clicked, the runtime value for cursor location that is returned to your application will be the location of the field you specify here. You can select a field from the drop down list or manually enter the name of a field. If you do not select Position cursor to the field, the cursor is positioned to the field that was last selected by the Web user. This cursor value does not refer to the cursor as it is displayed by the browser, it refers to the WebFacing runtime's value for current cursor location of fields in the DDS record. If you want to assign a value to the field where the cursor is positioned, choose a field or enter a value in the in the Enter data field.

Entries in Position cursor to the field can take the following form:

&{FIELD}
Field in the current record.
&{RECORD.FIELD}
Field in the specified record.

Entries in the Enter data field can take the following form:

&{FIELD.value}
The value of the field in the current record.
&{RECORD.FIELD.value}
The value of the field in the specified record.

You can also manually enter values in the Enter data field.

Submit

If the Submit checkbox is selected, you can choose a Function key or JavaScript function call submit action for the hyperlink. For example, from the Function key drop down list, you can choose ENTER, LOGOFF, or a function key that you have defined in your DDS. If there is a function key from another DDS record that you would like to use, manually enter the value for the function key. When a user clicks a link that you have created for a function key, the program will execute that function. In the JavaScript function call field, you can enter the name of a JavaScript function that you want to be executed when the link is clicked. The function can be one that you have entered using the Insert into script Web Setting, a function that you have defined in an external JavaScript file, or a function that is included with WebFacing in the file webface.js. If you create your own external JavaScript files, put them in the usr directory of your WebFacing project. This directory is located in the path <project name>\WebContent\ClientScript\usr. Any scripts that you put in this directory are available to your WebFacing application at runtime.

You can combine the Position cursor to the field option with the Submit option. Do this if you want to set the value for a specific field and submit that value back to your program. To do this, select the Position cursor to the field checkbox, choose a field from the drop down list (or enter a field) , in the Enter data field choose a {FIELD.value} (or enter a specific value), select the Submit checkbox, select the Function key radio button, and choose ENTER from the Function key drop down menu. For information about the entry format to use for Position cursor to the field and the Enter data field, see the section of this document Position cursor to the field.

Insert into script
Use the Insert into script setting to customize the JSP files that are created for regular records or subfile control records. For example, if you have a subfile control record LISTCTL, the WebFacing conversion will create a corresponding JSP file LISTCTLJavaScript.jsp. The code that you add in the Scripting field of the Insert into script setting will be added to the file LISTCTLJavaScript.jsp when it is generated. This setting allows you to enter arbitrary javascript or JSP scriptlets into your converted programs. This can be used to initialize fields or perform any work required for the specific record format. For example, you could add code that sets a field's value if its initial value is null:
if(&{CID}.value="")
{
	&{CID}.value="0001";
}
In this example, the code &{CID} refers to a field CID that was selected using the Insert field name button. Fields under the Insert field name button are enclosed with an ampersand and two brackets; for example &{FIELDNAME}. Other examples would be JSP code that determines the IP address of a WebFacing user or javascript that displays the time of day of the user's system. You can use Insert into script along with the Send to browser setting. For example, you can use values determined by your scripts to populate hidden fields that you have set with the Send to browser setting. If there is an existing field in your DDS that you want to use as part of your script, add it to your script using the Insert field name button. For example, you can select an H or hidden field and use it in your script so that a value can be assigned to it.

Send to browser

The Send to browser setting can be used for H or hidden DDS fields. This setting modifies the generated JSP files for your records. For example, if you have an H field in a record called LISTCTL, when this setting is used, an HTML hidden input form element will be generated in the JSP file LISTCTL.jsp. Hidden input form elements begin with the HTML code <INPUT TYPE="hidden" . Using Send to browser enables an H field to become part the the browser environment and for values to be assigned to it based on that environment. For example, the IP address of a user that is determined by a script you added using the Insert into script setting.

Dynamic key label

The Dynamic key label setting can be used to determine the text label of a command key at runtime. This setting is only available for output fields. With this setting, a command key is associated with the output field and text for the command key is determined by the runtime value of the field. An example use is if your application is to support more than one language and you want the command key text to appear in the user's native language. One way of doing this is to have a MSGF per language that contains the text strings that your application uses and put each MSGF in a language specific library. If the output field's value is read from the MSGF, you could change the language of the text displayed in the field by putting the library that contains the MSFG for your user's language higher in the library list in the user's profile. Subsequently, the command key label would be displayed in their language.

To use this setting, choose the Dynamic key label setting and select Use field's value as command key label. In the Command Key list, choose the key that will be associated with the text from the output field. *AUTO can also be chosen from the Command Key list. *AUTO means that the field value is parsed at runtime to determine which command key to assign the label to.
Note: Only a limited set of string patterns are currently supported by *AUTO. Assess whether *AUTO will work with your application based on the patterns listed in the prefix and separator table below and your knowledge of the strings for command key labels that are used in your application. The table identifies patterns by a prefix and a separator. For example, if the string F3=Exit is the output value and *AUTO is the value chosen in the Submit Function Key list, the string Exit will be used for the command key label. That is, F is treated as the prefix, = is treated as the separator, and the text following the separator is used for the label.
Prefix Separator
F =
FP =
CF =
CA =
PF =
Warnings
  • *AUTO can affect runtime performance. Use of *AUTO can be avoided by ensuring that there is a one-to-one mapping of output fields to command keys.
  • If you are using MSGFs for the text of output fields, the MSGF text should not include the key. For example, for Exit, the text in a MSGF should be Exit not F3=Exit.

Feedback