Dialog Boxes: General Information

A dialog box is a screen configuration block that can be displayed to a user to provide particular field values when a user clicks an action (a button or a menu command). A dialog box is referred to in code as a form.

This chapter describes how to define a dialog box that can be used in a workflow by using Workflow API.

Learning Objectives

In this chapter, you will learn how to do the following:

Define a dialog box in a workflow
Specify a dialog box for an action
Assign values specified in the dialog box to the DAC fields

Applicable Scenarios

You define a dialog box in a workflow when you need a user to provide particular field values when the user clicks a button or a menu command that corresponds to an action. These field values can later be used in a transition that is triggered by this action.

Defining of a Dialog Box

To define a dialog box, you should do the following:

You define the dialog box in the Configure method by using the context.Forms.Create method. In the method parameters, you provide the internal name of the dialog box and its configuration. In the configuration, you provide a lambda expression where you specify the title of the dialog box in the Prompt method and the fields that should be displayed in the dialog box in the WithFields method. The following code shows an example of a dialog box definition.
```
public override void Configure(PXScreenConfiguration config)
{
  ...
  var formClose = context.Forms.Create("FormClose", 
    form => form.Prompt("Select Reason").WithFields(fields => {
      fields.Add("Reason", field => { … });      
  }));
}
```
In the code above, the FormClose dialog box with the Select Reason title is declared.
In the WithFields method, you add fields by using the Add method, as described above.
You register the dialog box in the screen configuration by specifying the dialog box name in the WithForms method. An example is shown in the following code.
```
.AddDefaultFlow(flow => flow
  ...
  .WithForms(forms => forms.Add(formClose)))
```

Every dialog box has the OK and Cancel buttons. You cannot modify the buttons of a dialog box.

Configuration of the Fields of a Dialog Box

A dialog box can contain the following types of fields:

A custom check box field, which is defined with the WithCheckBoxField method. An example is shown in the following code.
```
fields.Add("InspectionPassed", field => field.WithCheckBoxField());
```
A custom combo box field, which is defined with the WithComboBoxField method. The list of combo box values is defined with the ComboBoxValues method. An example is shown in the following code.
```
fields.Add("InspectionType", field => 
  field.WithComboBoxField().ComboBoxValues(("M", "Manual"),("A", "Auto")));
```
A field that copies its state from the specified DAC field. It is defined with the WithSchemaOf method. An example is shown in the following code.
```
fields.Add("Reason", 
  field => field.WithSchemaOf<RequestForInformation.reason>();
```
Tip:
You can add two dependent fields to a dialog box where the value selected in one field updates the available values in the other field such as two fields of PXSelector type. The relationship between them should be defined in the DAC where they are declared.
A rich text box field. It is defined using the WithRichTextEditorField method. An example is shown in the following code:
```
fields.Add("Reason", field => field
    .WithRichTextEditorField()    
    .Prompt("Reason")
    .DefaultValue(defaultValue));
```
Note:
The WithRichTextEditorField method must be the first method in the line of configuration methods. Also, you cannot use the WithSchemaOf method for the rich text box field.

You can configure the parts of a dialog box in the following ways:

Specify the label text for each field by calling the Prompt method
Specify that the value of any field is required unconditionally by calling the IsRequired that the field is required depending on a condition by calling the IsRequiredWhen method
Specify the default value of any field by calling one of the following methods:
- DefaultValue
- DefaultExpression
- DefaultValuefromSchemaField
Specify the location of a button on the dialog box by calling one of the following methods:
- PlaceBefore
- PlaceAfter
Hide any field by calling one of the following methods:
- IsHiddenWhen
  This method hides a field if a condition is met. When using this method, you provide a condition as a parameter.
  Note:
  The condition specified in the IsHiddenWhen method is not checked during the mass processing of records.
- IsHiddenAlways
  This method hides the field unconditionally. This method may be useful to hide a field in a dialog box of a custom workflow if this field is included in this dialog box in a predefined workflow.
An example of using these methods is shown in the following code.
```
.WithForms(forms => {
  forms.Update("FormOpen", form =>
    form.WithFields(fields =>
    {
      fields.Add("Reason", field => field.WithSchemaOf<CROpportunity.resolution>()
        .Prompt("Reason")
        .IsHiddenWhen(hideReason));

      fields.Update("Stage", field => field.WithPrompt("Stage ID").IsHiddenAlways());
    }
  ));						
})
```
In the code above, the FormOpen dialog box has been updated in the following ways:
- The Reason field of the FormOpen dialog box has been added; it will be hidden when the hideReason condition is True.
- The Stage field is always hidden.

For a combo box field, you can do the following:

Define a set of combo box values by calling the ComboBoxValues method
Specify that the set of combo box values of a dialog box field should be taken from a source or target state by calling the ComboBoxValuesSource method. In the method parameter, you should specify from where the values should be taken (a source state, a target state, or explicit values specified in the dialog box definition).
For example, suppose that in some state, a set of values for the CRLead.resolution field is specified. The workflow includes a transition where this state is a target state, and a dialog box that is shown during this transition. Further suppose that the dialog box includes the Reason field, whose configuration is provided by the CRLead.resolution field (through the use of the WithSchemaOf method). To specify that the values of the Reason field should be taken from the target state of a transition where the dialog box is used, you should use the following code in the dialog box.
```
.WithForms(forms => {
  forms.Add("FormOpen", form =>
    form.WithFields(fields =>
    {
      fields.Add("Reason", field => field
        .WithSchemaOf<CRLead.resolution>()
        .IsRequired()
        .Prompt("Reason")
        .ComboBoxValuesSource(ComboBoxValuesSource.TargetState));
    }
  ));						
})
```
Add a new value and its display name by calling the ComboBoxValue method.
You should use this method when updating a predefined dialog box field.
Restrict the set of predefined combo box values by calling the OnlyComboBoxValues method.

Linking a Dialog Box to an Action

To display a dialog box when a user clicks a button that corresponds to an action, you need to specify this dialog box in the action configuration. You do this by calling the WithForm method inside the lambda expression provided for the Add method.

To insert data specified by a user in a dialog box field in a DAC field, you need to call the WithFieldAssignments method. In the lambda expression provided for the method, you add the DAC field by calling the Add method. In the lambda expression for the Add method, you call the SetFromFormField method and provide the dialog box name and the dialog box field name as parameters.

An example of an action with a dialog box is shown in the following code.

actions.Add(g => g.close, c => c
  .WithForm(formClose)
  .WithFieldAssignments(fields =>
  {
    fields.Add<RequestForInformation.reason>(f => 
      f.SetFromFormField(formClose, "Reason"));
  }));

In the code above, the RequestForInformation.reason field has been updated with the value specified in the Reason field of the formClose dialog box.

Note:

The original code of the action is executed only after the dialog box is closed and field assignments are applied. If an action triggers a transition, the transition is performed only if a user clicks OK in the dialog box.