dialog

Parameter	Type		Description
aTable	Table	→	Table owning the form or If omitted: default table or use of project form
form	Text, Object	→	Name (string) of table or project form, or a POSIX path (string) to a .json file describing the form, or an object describing the form
formData	Object	→	Data to associate to the form
*	Operator	→	Use the same process

Description

This command is designed to work with customized and advanced user interfaces based on forms. You can use it to display information coming from the database or other locations, or to provide data entry features. Unlike ADD RECORD or MODIFY RECORD, DIALOG gives you full control over the form, its contents and the navigation and validation buttons.

This command is typically called along with the Open form window to display sophisticated forms, as shown in the following example:

The DIALOG command can also be used instead of ALERT, CONFIRM or Request when the information to be presented or gathered is more complex than those commands can manage.

In the form parameter, you can pass:

• the name of a form (project form or table form) to use;
• the path (in POSIX syntax) to a valid .json file containing a description of the form to use;
• an object containing a description of the form to use.

Optionally, you can pass parameter(s) to the form using a "form data" object. Any properties of the form data object will then be available from within the form context through the Form command. For example, if you use a form data object containing {"version";"12"}, you will be able to get or set the value of the "version" property in the form by calling:

 $v:=Form.version //"12"
 Form.version:=13

To fill the "form data" object, you have two possibilities:

• use the formData parameter. Using a local variable for formData allows you to safely pass parameters to your forms, whatever the calling context. In particular, if the same form is called from different places in the same process, you will always be able to access its specific values by simply calling Form.myProperty. Moreover, since objects are passed by reference, if the user modifies a property value in the form, it will automatically be saved in the object itself.

• associate a user class to the form, in which case 4D will automatically instantiate an object of this class when the form will be loaded. The object properties and functions will be automatically available through the object returned by Form. You could write for example Form.myFunction().

:::note

• The formData parameter has priority over a form class (the class object is not instantiated if a formData parameter is passed).
• If you do not pass the formData parameter (or if you pass an undefined object) and no user class is associated to the form, DIALOG creates a new empty object bound to the form.

:::

The dialog is closed by the user either with an "accept" action (triggered by the ak accept standard action, the Enter key, or the ACCEPT command), or with a "cancel" action (triggered by the ak cancel standard action, the Escape key, or the CANCEL command). An accept action will set the OK system variable to 1, while a cancel action will set OK to 0.