10. Defining Keyword Test Editor's Contents and Behavior

Applies to TestComplete 14.10, last modified on June 5, 2019

The users design and view keyword tests in the Keyword Test editor. It lists all operations included in the test and displays information on each operation, such as the operation name, type, settings and description. Some of this information is read-only, some can be modified via special dialogs or even directly in the editor’s grid.

For custom operations created with script extensions, the data to display in the Keyword Test editor is defined using Column elements in the description.xml file. Dynamic (editable or generated on-the-fly) content is provided by helper script routines included in the operation code. Support for in-place editing of operation’s data also required additional script code and the appropriate definitions in the description file.

We will divide the procedure of defining the Keyword Test editor’s contents and behavior for our custom keyword test operation into two steps:

1. Defining Data to Display

First of all, let’s define which information on our custom operation the KeywordTest editor should display:

Column Contents
Item The operation name: “Log Attributes”.
Operation None.
Value The font color and style and the background color specified by the operation settings, in the following format:

Font: Color, [Bold], [Italic], [Underline], [Strikeout]; Background: Color; Remarks: Format

Square brackets denote optional elements, which should only be present if the font has the appropriate style set.
Description The operation description held in the operation’s Description field.

As you can see, the Item column should display the same value for all instances of our custom operation. The contents of the Value and Description columns, on the contrary, should be taken from the operation’s fields and thus can be different for different operation instances.

To implement support for dynamic content, we need to create script routines that will return the desired content. The routines’ code follows; add it to the laCode unit:

JScript

// Returns the text to be displayed in the Description column of the KeywordTest editor
function LogAttr_GetDescription(Data)
{
  return Data.Description;
}

// Returns the text to be displayed in the Value column of the KeywordTest editor
function LogAttr_GetValue(Data)
{
  var str = "Font: " + GetColorName(Data.FontColor);
  if (Data.Bold) str += ", Bold";
  if (Data.Italic) str += ", Italic";
  if (Data.Underline) str += ", Underline";
  if (Data.Strikeout) str += ", Strikeout";
  str += "; Background: " + GetColorName(Data.BackColor);
  str += "; Remarks: " + (Data.PlainTextRemarks ? "Plain text" : "HTML");

  return str;
}

This code snippet contains two functions, LogAttr_GetDescription and LogAttr_GetValue. The former returns the text to be displayed in the Description column, the latter returns the text for the Value column. Both functions have the Data parameter that provides access to the operation’s fields by their names. The LogAttr_GetValue function uses a helper GetColorName routine to convert the numeric value of a color to the color name; this routine was defined in one of the previous steps.

Now open the C:\My Extension Files\LogAttrExtension\description.xml file in your text or XML editor and add the following code to it:

XML

[description.xml]

<?xml version="1.0" encoding="UTF-8"?>
<ScriptExtensionGroup>
    <Category Name="Keyword Test Operations">
        <ScriptExtension Name="Log Attributes Keyword Test Operation" Author="SmartBear Software" Version="1.0 test" HomePage="smartbear.com">
            <Description>Provides the Log Attributes keyword test operation.</Description>
            <Script Name="laCode.js">

                <KDTOperation Name="Log Attributes" Category="Logging" Icon="la-icon.bmp">
                    <Data>
                        <!-- General properties -->
                        <Field Name="Description" />
                        <!-- Log Attributes object properties -->
                        <Field Name="FontColor" />
                        <Field Name="BackColor" />
                        <Field Name="Bold" />
                        <Field Name="Italic" />
                        <Field Name="Underline" />
                        <Field Name="Strikeout" />
                        <Field Name="PlainTextRemarks" />
                    </Data>
                    <Columns>
                        <Column Name="Item" Value="Log Attributes" />
                        <Column Name="Value" GetValue="LogAttr_GetValue" />
                        <Column Name="Description" GetValue="LogAttr_GetDescription" />
                    </Columns>

                    <Events>
                        <Event Name="OnCreate" Routine="LogAttr_OnCreate" />
                        <Event Name="OnExecute" Routine="LogAttr_OnExecute" />
                    </Events>
                </KDTOperation>

            </Script>
        </ScriptExtension>
    </Category>
</ScriptExtensionGroup>

We have added a child Column containing three Column elements to the KDTOperation element. Each Column element corresponds to a particular column of the KeywordTest editor. In our case -- to the Item, Value and Description columns. These elements define the operation information to be displayed in the appropriate columns.

Let’s examine some of the added Column elements:

XML

...
<Columns>
    <Column Name="Item" Value="Log Attributes" />
    <Column Name="Value" GetValue="LogAttr_GetValue" />
    ...
</Columns>
...

The Name attribute specifies the name of the KeywordTest editor’s column whose contents are defined by the given Column element. The Value attribute holds the text to be displayed in the column. This text is constant and cannot be modified. In contrast to it, the GetValue attribute specifies the name of a script routine that returns the value for the column whenever TestComplete requests it. This value can be different depending on the values of the operation’s parameters and fields.

2. Making Data Editable

To let the users specify custom description for our operation, we will make data in the Description column editable. For this, we need to do the following:

  • Choose the type of in-place editor for the column: text box, combo box, text box with embedded buttons or parameters editor. (For more information on each editor type, see the Implementing In-Place Editing Support.)

  • Create script routines that handle various events of the in-place editor.

  • Add information about the in-place editor’s type and event handlers to the description.xml file.

For the Description column, we will use a simple text box editor. This editor raises a number of events throughout the editing process (see Events Reference). To implement support for this in-place editor, we need to handle its StartEditing, GetEditValue, SetEditValue and ApplyChanges events. Below is the event handlers’ code. Add this code to the laCode unit:

JScript

[laCode.js]

var EditValue;

function LogAttr_Description_StartEditing(Data)
{
  EditValue = Data.Description;
}

function GetEditValue(Data)
{
  return EditValue;
}

function SetEditValue(Data, Value)
{
  EditValue = Value;
}

function LogAttr_Description_ApplyChanges(Data)
{
  Data.Description = EditValue;
}

In this code, we define a global variable, EditValue, to store the current value in the in-place editor. The event handlers read or modify the variable value to provide feedback between the in-place editor and the operation’s data.

Now we need to update the description file with information on the in-place editor and its event handlers. Open the C:\My Extension Files\LogAttrExtension\description.xml file in your text or XML editor and add the following code to it:

XML

[description.xml]

<ScriptExtensionGroup>
    <Category Name="Keyword Test Operations">
        <ScriptExtension Name="Log Attributes Keyword Test Operation" Author="SmartBear Software" Version="1.0 test" HomePage="smartbear.com">
            <Description>Provides the Log Attributes keyword test operation.</Description>
            <Script Name="laCode.js">

                <KDTOperation Name="Log Attributes" Category="Logging" Icon="la-icon.bmp">
                    <Data>
                        <!-- General properties -->
                        <Field Name="Description" />
                        <!-- Log Attributes object properties -->
                        <Field Name="FontColor" />
                        <Field Name="BackColor" />
                        <Field Name="Bold" />
                        <Field Name="Italic" />
                        <Field Name="Underline" />
                        <Field Name="Strikeout" />
                        <Field Name="PlainTextRemarks" />
                    </Data>
                    <Columns>
                        <Column Name="Item" Value="Log Attributes" />
                        <Column Name="Value" GetValue="LogAttr_GetValue" />
                        <Column Name="Description" GetValue="LogAttr_GetDescription" Editable="True" EditorType="Text">
                            <Event Name="StartEditing" Routine="LogAttr_Description_StartEditing" />
                            <Event Name="GetEditValue" Routine="GetEditValue" />
                            <Event Name="SetEditValue" Routine="SetEditValue" />
                            <Event Name="ApplyChanges" Routine="LogAttr_Description_ApplyChanges" />

                        </Column>
                    </Columns>
                    <Events>
                        <Event Name="OnCreate" Routine="LogAttr_OnCreate" />
                        <Event Name="OnExecute" Routine="LogAttr_OnExecute" />
                    </Events>
                </KDTOperation>

            </Script>
        </ScriptExtension>
    </Category>
</ScriptExtensionGroup>

As you can see, we have added two new attributes to the Column element corresponding to the Description column:

XML

...
<Column Name="Description" GetValue="LogAttr_GetDescription" Editable="True" EditorType="Text">
    ...
</Column>
...

The Editable attribute set to True specifies that the value in the column can be edited directly in the KeywordTest editor’s grid. The EditorType attribute specifies the type of the in-place editor for the column. In our case, it is Text, which means a text box.

We have also added a number of child Event elements to that Column element. These elements enable processing of the in-place editor’s events and specify script routines that will be used as the event handlers.

Prev     Next

See Also

Script Extensions
Customizing KeywordTest Editor Contents
Implementing In-Place Editing Support
Structure of the Description File

Highlight search results