m-Painter AJAX Helpers

Click here to access current documentation for this feature.

AJAX (Asynchronous JavaScript And XML) is often used for interacting with a data server through a browser page without needing to refresh.

You have already seen AJAX in use with Multiple Record Inquiries. As you enter text into an Advanced Search input box, the page begins to suggest valid data for you! With AJAX m-Painter helpers, you can now add similar functionality into all of your Web applications.

• AJAX Suggest
• AJAX Validation
• AJAX Dropdown List
• AJAX Cascading Dropdown List
• Suggest and Validation
• Return Data
• Remove Helper

Each feature can be accessed from either the m-Painter Toolbar or from the context menu of an Input box:

Each AJAX Helper feature will be discussed below:

AJAX Suggest

AJAX Suggest can be implemented on any Input text box. When configured, as your end-user begins typing, the server will return a list of valid values. Users can either continue typing, or select a value from the list. Behind-the-scenes, the logic is passing the values entered in by your end-user and comparing that text to the value of a pre-existing field in a pre-existing application. For this function to work, you must first build a Multiple Record Retrieval to use as your AJAX querying list.

First, select the input box you wish to be used for the AJAX Suggest, then select the "Insert AJAX Feature" icon from the m-Painter Toolbar.

Select "Ajax Suggest" from the Ajax Feature dropdown List. Use the dropdown list to select a pre-existing Lookup Retrieval.

Note: Only applications from the current Data Dictionary will appear in this list. If you wish to use applications from other Data Dictionaries, use the URL text area to manually type the DICTIONARY.APPNAME.

Lastly, use the "Lookup Field Name" to choose the field you want used from your existing application as the "Suggest" field. Click OK & Save.

AJAX Validation

AJAX Validation is not seen by the end-user until they attempt to submit the form. AJAX Validation queries a pre-existing Multiple Record Retrieval, determines if the end-users input matches a valid record in the database, and submits the record. If a matching value does not exist, a pre-determined error message is shown and the form is not submitted.

First, select the input box you wish to be used for the AJAX Validation, then select the "Insert AJAX Feature" icon from the m-Painter Toolbar.

Select "Ajax Validation" from the Ajax Feature dropdown List. Use the dropdown list to select a pre-existing Lookup Retrieval.

Note: Only applications from the current Data Dictionary will appear in this list. If you wish to use applications from other Data Dictionaries, use the URL text area to manually type the DICTIONARY.APPNAMEs.

Next, use the "Lookup Field Name" to choose the field you want used from your current application to be validated against from your pre-defined Multiple Record Retrieval.

Enter in an Error Message that the end-user would see in the event that their validation fails. Click OK & Save.

AJAX Helpers: Some m-Power templates have built in AJAX suggestion boxes, which suggest data to the customer as they are typing. While this feature is not built into Reports (or Single Row Maintainers), the ability to add it in is very straightforward. This video will describe how to add AJAX suggest & validate to your report.

In order to use Ajax helpers, it is essential that you have one or more fields using a runtime value prompt. You can add these prompts through the record selection screen.

After compiling your application, open m-painter, and navigate to the prompt page. We will being by adding Ajax suggest to the customer name. Now, click on the input box of the field you want to have an Ajax feature. Select Ajax from the toolbar at the top.

Select the Ajax feature you would like your prompt to use. For this prompt, we are using Ajax suggest. After choosing the feature, you need to select a pre-built multi-record inquiry that will provide the Ajax suggestions. A field in the retrieval must match the field you are adding to the Ajax feature.

Note: Only applications from the current Data Dictionary will appear in this list. If you wish to use applications from other Data Dictionaries, use the URL text area to manually type the DiCTIONARY.APPNAMEs.

Finally use the Lookup Field Name to choose the field you want used from your existing retrieval.
If instead you would like to validate over the input, you can change this by selecting the Ajax validation feature. This feature allows you to do some runtime validation. Users are only able to proceed to the output page when they’ve selected one of the values from the external retrieval. At the bottom of the window, add an error message the user will see if an invalid field value is entered. Click Ok.

Save and run your application. The application can now make suggestions over a field, or validate user input.

AJAX Dropdown List

AJAX Dropdown Lists are similar to the standard dropdown lists that are created in m-Painter. A pre-defined dropdown list template is queried at run-time to create the end-users dropdown options. When selecting this option, be aware that this functionality requires JavaScript to be enabled on the client's PC to work properly.

First, select the input box you wish to be used for the AJAX Dropdown List, then select the "Insert AJAX Feature" icon from the m-Painter Toolbar.

Select "Ajax Dropdown List" from the Ajax Feature dropdown List. Use the dropdown list to select a pre-existing dropdown list application. Click OK & Save.

Note: Only applications from the current Data Dictionary will appear in this list. If you wish to use applications from other Data Dictionaries, use the URL text area to manually type the DICTIONARY.APPNAME.

AJAX Cascading Dropdown List

A popular feature of m-Power Reports is the ability to have a cascading dropdown list. That is, the selection of one dropdown list, affects subsequent dropdown lists. Now, with AJAX Cascading Dropdown Lists, this functionality is available for all application types except Retrievals. When using a Cascading Dropdown List, your first dropdown list must use the standard AJAX Dropdown List. Then all subsequent dropdown lists will be of the cascading variety. Since we already built the AJAX Dropdown List in the previous example, let's now build our Cascading dropdown.

First, select the input box you wish to be used for the AJAX Cascading Dropdown List, then select the "Insert AJAX Feature" icon from the m-Painter Toolbar.

Select "Ajax Cascading Dropdown List" from the "Ajax Feature Dropdown List. Use the dropdown list to select a pre-existing Dropdown List Application.

Note: Only applications from the current Data Dictionary will appear in this list. If you wish to use applications from other Data Dictionaries, use the URL text area to manually type the DICTIONARY.APPNAME.

For the "Dependent Field Lookup Name" dropdown, select the field that associates back to your previous dropdown list. Similarly, for the "Selected Dependent Field" dropdown, select the input from the current application that your dependent field is mapped too. For instance, if my first dropdown box is pulling in the Customer Number on Input R001, when I create my 2nd dropdown list, I would enter "CUSNO" and "R001" for the Dependent Field Name and Dependent Field boxes, respectively. Click OK & Save. At runtime, your end-user cannot choose the 2nd dropdown option, until the 1st dropdown value has been selected.

Suggest and Validation

The AJAX Suggest and Validation is simply the combination of the AJAX Suggest & the AJAX Validation features.

To implement, select the input box you wish to be used for the AJAX Suggest & Validation, then select the "Insert AJAX Feature" icon from the m-Painter Toolbar.

Select "Suggest and Validation" from the Ajax Feature dropdown list. Use the dropdown list to select a pre-existing Multiple Record Inquiry.

Note: Only applications from the current Data Dictionary will appear in this list. If you wish to use applications from other Data Dictionaries, use the URL text area to manually type the DICTIONARY.APPNAME.

Next, use the "Lookup Field Name" to choose the field you want used for the Suggest/Validation from your pre-defined Multiple Record Retrieval.

Enter in an Error Message that the end-user would see in the event that their validation fails. Click OK & Save.

Return Data

The AJAX Return Data feature will populate one or more inputs in a maintainer based on one key field.

To implement, select the input box you wish to be used for the AJAX Return Data, then select the "Insert AJAX Feature" icon from the m-Painter Toolbar.

Select "Ajax Return Data" from the AJAX Feature Dropdown list. Use the dropdown list to select a pre-existing Multiple Record Inquiry.

Note: Only applications from the current Data Dictionary will appear in this list. If you wish to use applications from other Data Dictionaries, use the URL text area to manually type the DICTIONARY.APPNAME.

Next, use the "Lookup Field Name" to choose the field you want used as the key field for your return data from your pre-defined Multiple Record Retrieval.

Note: All returned data will be returned based on this first field. If multiple records are found for this key, the first record is the one that will be returned.

Map all fields that you wish to be returned by selecting the "Fields From Retrieval" and the "Current App Fields". Click Add to add that relationship. Repeat as needed to fully map each field. Click OK & Save.

Note: At runtime, after the first field is entered and the user moves their focus away from the field (either by using tab or clicking on a different input), AJAX will go out to your inquiry, pull the relevant data, and return it to the inputs based on the field mapping you have selected.

Remove Helper

In the event that you create an AJAX Helper but later decide you want to revert back to a standard Input box, use this option to remove any AJAX Helper.

To remove helpers, select the input box you wish to revert, then select the "Insert AJAX Feature" icon from the m-Painter Toolbar.

Select "Remove Helper" from the Ajax Feature Dropdown List. Click OK & Save.

Additional Notes

• AJAX Helpers are not supported with the Grid Maintenance Template.
• AJAX Validation helpers are not supported with the Pivot and Interactive Report Templates.
• AJAX Return Data helpers are only supported with the Work-with, Single, and Grid Add Maintenance Templates.