Component Custom Methods

Custom methods can be added to components and templates. Custom methods allow scripts to be defined on a component, and call the same script from another event.

In the image below, a Button component has a custom method called printHello. The method takes a single parameter called customMessage, concatenates the value of customMessage with a static string, and calls system.gui.messageBox to show the message.

images/download/attachments/6047143/1_intro.PNG

Calling a custom method requires a path to the component where the method resides, as well as the name of the method. To call the printHello method from the actionPerformed event on the same button, the script would look like the following:

images/download/attachments/6047143/2_originating_component.PNG

Custom methods can be called from scripts on other events and components. A script on a Label component located in the same container as the Button can call the printHello method.

images/download/attachments/6047143/3_a_different_component.PNG

Example - Error Checking User Input

The following example will create a custom method that reads input from several components, and checks the values to make sure valid data was entered.

Step 1 - Creating the Custom Method

The image below shows a container named Text Field Container. Inside are four Text Field components can enter data into. The container also has a Button component that will read the values from each component.

images/download/attachments/6047143/4_component_overview.PNG

The error checking method will be placed on Text Field Container since all of the components that will be checked are inside this container. To create a custom method, right-click the Text Field Container component, and select Scripting

images/download/attachments/6047143/5_container_scripting.PNG

Right-click on Custom Methods, or double-clicking the images/download/attachments/6047143/6.5_double_click.PNG green plus button will also create a new custom method.

images/download/attachments/6047143/6_add_custom_method.PNG

A new custom method will appear. The new method can be renamed, and parameter names for the method can be defined.

images/download/attachments/6047143/7_new_method_created.PNG

Rename the method to errorChecking. This method will not accept parameters, so leave the Parameters Text Field blank. Expand and copy the example below and paste it into the Script text area. Make sure the indentation matches the image below.

errorCheck
#Build a list of names from each Text Field component that will be checked for errors
textFieldNames = ["First Name","Last Name", "Account", "Address"]
#Initialize a list to store the values of each Text Field
textFieldValues = []
#Initialize a sting that will show each error detected
errorMessage = ""
#Iterate through each component
for component in textFieldNames:
#Retrieve the value for the current text field
value = self.getComponent(component).text
#Add the value to textFieldValues.
textFieldValues.append(value)
####Begin Error Checking
####Check for blank values
if value == "":
#Add a message to errorMessage describing the problem.
#The "\n" characters denote a new line in Python strings
errorMessage += "The %s Text Field is empty. Please enter a value\n" % (component)
####Check for additional errors by adding more if-statements below, and add the new message errorMessage
####End Error Checking
#After the for-loop finished looking for errors, check if any errors have been added to errorList
#If the amount of characters in errorMessage is more than 0, we can assume an error message has been added,
#so check the amount of characters in errorMessage with Python's len()
if len(errorMessage) > 0:
#Show the user the errors
system.gui.messageBox("The following errors were detected\n" + errorMessage, "Errors detected")
else:
#No errors were detected, so do something useful with the values here. Otherwise show the user the values...
system.gui.messageBox(str(textFieldValues))  

images/download/attachments/6047143/8_error_check.PNG

Step 2 - Calling the Custom Method

Now that a custom method had been created, a script needs to call the method. Add a script to the button in Text Field Container on the actionPerformed event.

Invoke errorCheck
#Call the errorCheck method on the button's parent
#container: Text Field Container
event.source.parent.errorCheck()

images/download/attachments/6047143/9_call_the_method.PNG

Step 3 - Testing the Custom Method

Click OK to close the Component Scripting window, save the project, and put the designer into preview mode. Add some data to some of the text fields, but leave at least one blank. Clicking on the button will display which text fields were empty. The image below shows the Last Name and Address text fields are empty, and the script detected this.

images/download/attachments/6047143/10_errors_detected.PNG

Now any script that has access to this window can check the text fields for errors. This example could be expanded to look for additional errors, such as checking for prefixes in some or all of the values.