Overview
The Quick Lists feature in m-Painter can be used for quickly generated dropdown lists, AJAX features, application lookups, and key pairs. This can be very handy and efficient when customizing your applications within m-Painter, as quick lists allow you to create a list within the m-Painter editor of the current application, removing the need to detour in order to create additional applications.
Quick List Types
- Static List – Create a manually entered list of values (value & description). Static Lists are best utilized when the list information is short and has a relatively definite amount of possible values (ex. Male/Female, Yes/No, Q1/Q2/Q3/Q4). Additionally, they are beneficial when you would like to create a list without needing to create and query a database table.
- Table Driven List – Create a list of values retrieved from a single database table of your choosing. Any field(s) within the table may be selected for the value and/or description values in your list. These are more robust than static lists in terms of functionality, and support an infinite amount of values.
Static Lists
Static lists allow for the creation of a custom list of key pairs (value/description). These are only used for dropdown lists and key pairs. Since they are static, they are not tied to any specific database table. Static Lists may be used to create option lists and key-value lookups, and really become useful when you would like to change the values/descriptions without pulling from a created database table.
An excellent use case scenario for a static list would arise while working with dates, specifically months. In this example report, a handful orders from the past year may be seen.
With a runtime selection and dropdown list currently added in, the orders can be filtered conveniently by month. The list displays all possible values for month that may be selected at runtime (1,2,3…12). While this list makes sense, being able to display these values as their month names rather than a number would be more practical to the end user. Creating a Quick List will be the easiest and quickest way to do this.
In m-Painter, open the Output page, and right click on the field for the month dropdown and select Insert/Edit Option List.
For Option Data Source, select External Retrieval. Select the new button that has appeared, Add/Edit Quick Lists.
The following menu displays any previously created Quick Lists that have been made in other applications. These Quick Lists are easily accessible from this menu, and may always be updated/deleted as need be. To add a new Quick List, select ‘Create New Quick List’, and choose Static List. The Create/Edit Quick List menu is explained below:
List Information
-Name: The name to be given for the Quick List being created (Note: Do not use special characters and/or multiple spaces between two characters in the List Name)
-Description: The description to be given for the Quick List being created
Add Item to this list
-Value: The actual values for the field that are being submitted to the database when the application is ran (in this example, the month numbers)
-Description: The substitute name for the field values which will be displayed in the dropdown list (in this example, the month names)
-Add Item to List: Creates the value/description pair and adds it to the option list
List Items
All the value/description pairs created will show up here. Note: The new dropdown Quick List will display the fields at runtime in the same order as they are arranged in this list.
-Remove From List: Remove the selected value/description pair from the list
-Move Up: Move the selected value/description pair up one row.
-Move Down: Move the selected value/description pair down one row.
After adding in all the value/description pairs for the dropdown list, press OK.
The Quick List just created does not appear instantaneously in the available quick lists after its initial creation. Select Refresh List and the Month Quick List will now appear.
Back at the Insert/Edit Option List, select the refresh button next to the Select External Retrieval dropdown and then select the created Quick List. Press OK.
After saving changes in m-Painter and rerunning the application, the dropdown list on the prompt page for month is no longer listing numeric values for month. It is now listing the month names (descriptions) we assigned to the numeric values.
Table-Driven Lists
Table-driven lists are the perfect option when making a static driven list would be impractical and there are too many key pairs to type in manually, or this list will need to be changed/updated frequently via a Maintainer.
A helpful example for using a table-driven list is to consider a report on a customer list, which includes a runtime value prompt for state, allowing the user to select a state’s initials to filter the customers by. Like the static driven example above, we can change these displayed values to read a more practical description, such as the full state name. However, keying in 50 different value/description pairs for state initials and state name in a static list would not be practical. Using a table-driven list with state names from a premade table would make much more sense.
It is important to remember, while this example covers a dropdown list, Table Driven lists are not limited to this. They may be applied to any other application which incorporates AJAX features, return data, or key-value lookups.
In m-Painter, open the PC Prompt page. Right click on the field for the state dropdown and select Insert Edit Option List.
For Option Data Source, select External Retrieval. Select the new button that has appeared, Add/Edit Quick Lists.
The following menu displays any previously created Quick Lists that have been made in other applications. These Quick Lists are easily accessible from this menu, and may always be updated/deleted as need be. To add a new Quick List, select ‘Create New Quick List’, and choose Table Driven List. The Create/Edit Quick List menu is explained below:
List Information
-Name: The name to be given for the Quick List being created (Note: Do not use special characters in the List Name)
-Description: The description to be given for the Quick List being created
-Select a Table: Choose which database table in your current dictionary that the values fields and descriptions will be accessed from
-Select a Field to Add: After choosing a table, select the fields from this table that will be added to the quick list.
Selected Fields
Any fields that were added from the above step will show up here.
-Name: Field name
-Description: Field name description
-Sort: Allows user to sort all values for the current field. If set to the default ‘N/A’, values will appear in the same order that they exist as in the database table. Other options include Ascending and Descending.
-Value/Desc: Specifies the selected field to either be a field value, or a description.
-Relation: Selects relation for the field value/description to be filtered on in the created quick list. Options include ‘Equal to’, and ‘Not Equal to’. This will be most useful if you are trying to include/exclude certain values from displaying in the list.
-Value: Specify the hardcoded value that the relation will be compared against.
After adding all the necessary fields from the table, press OK.
The Quick List just created does not appear instantaneously in the available quick lists after its initial creation. Select Refresh List and the Table Drive Quick List will now appear. Note that the Type specifies whether the Quick List is a “Static” or “Table” list.
Back at the Insert/Edit Option List, select the refresh button next to the Select External Retrieval dropdown and then select the created Quick List. Press OK.
After saving changes in m-Painter and rerunning the application, the dropdown list on the prompt page for month is no longer listing state initials. It is now listing the state names (descriptions) assigned to the state initials (values).
Notes
Promoting Quick Lists – Created quick lists are stored are in the ‘quick_lists.json’ file within /mrcjava/WEB-INF/classes/DICTIONARY. To use created quick list(s) in production applications, please ensure to promote this ‘quick_lists.json‘ file over to this same directory in the production environment.