Related Topics
This object represents a Form instance. An instance is a completed Form, or one that is currently being edited.
When developing Form scripts (in the various callback methods such as BP_Event) or Timeline scripts, you are automatically given an instance of the “current” Form with the CurrentForm variable.
This object is derived from the ContentObject class. All properties and methods from the ContentObject are supported for this object, plus the properties below.
Properties #
|
PROPERTY NAME |
DATA TYPE |
DESCRIPTION |
|---|---|---|
|
CloseOptions |
Code Enum |
This can be set in any form script. This property can be set to the following:
|
|
ControlFocus |
Form Control Object |
This property can be used to set the focus to a named control after the event returns. Set this property to null to prevent the focus from being set.
|
|
CreateTime |
DateTime |
The date/time of this specific form instance’s creation |
|
CreateUID |
String |
The User ID of the user which created this specific form instance |
| CustomOnLoad | JavaScript Function Name |
Enables you to specify a block of custom JavaScript to run in the OnLoad event of the Form. For example, in an HTML Code control on the Form, you might specify the JavaScript to run, then set the CustomOnload property as follows in the Raw HTML property of the control:
In this example, the code above will display the alert box when the form loads. |
|
DOCTYPE_HTML |
Boolean |
If set to true will use HTML rather than XHTML |
|
DOCTYPE_HTML5 |
Boolean | If set to true will use HTML rather than XHTML |
| FormCase | Case Instance Object |
Returns the Case instance associated with a Form instance, e.g.:
|
|
FORMID |
String |
The ID of the Form Definition for this instance |
|
FORMINSTID |
String |
The optional ID of the Form instance |
|
FormPartition |
Partition Object |
Set to the Partition object of the Forms partition |
|
ID |
String |
The ID of this specific form instance |
|
Name |
String |
The text name of this specific form instance |
|
PID |
String |
The Partition ID of the partition where this form resides |
|
ReturnNullsForErrors |
Boolean |
If set to true, APIs such as FormControl will return a null if the form control isn't found. Otherwise an empty class will be returned. The default is false. |
| SkipSetFocus | Boolean | Skips the set focus event. |
|
UpdateTime |
DateTime |
The most recent date/time that a user changed this specific form instance |
|
UpdateUID |
String |
The User ID of the user who most recently update this specific form instance |
As always, when using JavaScript, ensure the HTML Code control's name is blank, to prevent Process Director from trying to interpret the curly brackets as a system variable.Methods #
AddErrorMessage
This API will add an error message to the form which will be displayed to the user. If an error message is added, the user won't be able to submit the form. This is an overloaded method with the following possible declarations:
public void AddErrorMessage(FormMessageString pMessage,
params object[] pParams)
public void AddErrorMessage(string pFormat, params object[] pParams)
public T AddErrorMessage<T>(T ret, string pFormat, params object[] pParams)
public T AddErrorMessage<T>(T ret, FormMessageString pMessage,
params object[] pParams)
Parameters
pMessage: The error message to return (this can be a string or the FormMessageString class).
pFormat: The format string for the error message.
pParams: A parameters object containing the message parameters.
Returns
None
Example
// This example will be called in the validation event of a form script
protected override void BP_Validation()
{
// Display an error on the form if the Amount form field is > 100
// and place the focus on the form field “Amount”
If (CurrentForm.FormControl("Amount").Number > 100)
{
CurrentForm.AddErrorMessage(new FormMessageString("Must be < 100", "Amount"));
}
}
AddInfoMessage
This API will add an informational message to the form which will be displayed to the user. If an informational message is added, the user won't be able to submit the form. This is an overloaded method with the following possible declarations:
public void AddInfoMessage(FormMessageString pMessage,
params object[] pParams)
public void AddInfoMessage(string pFormat, params object[] pParams)
Parameters
pMessage: The error message to return (this can be a string or the FormMessageString class).
pParams: A parameters object containing the message parameters.
Returns
None
Example
// This example will be called in every event
protected override void BP_Event()
{
// Display a message on the form if the Amount form field is > 100
If (CurrentForm.FormControl("Amount").Number > 100)
{
CurrentForm.AddInfoMessage("The amount is > 100");
}
}
AddJavaScript
This API adds a block of JavaScript code to the form.
Parameters
JavaScript: The actual JavaScript code to add.
Returns
None
Examples
// We'll add our JavaScript in the initial load
protected override void BP_ViewStateiInit()
{
CurrentForm.AddJavaScript("alert('Please submit the form before
closing it.')");
}
AddTopHTML
This API adds a block of HTML code to the top of a form.
Parameters
pHTML: A string value containing the raw HTML code to add to the top of the page.
Returns
None
Examples
// We'll add our JavaScript in the initial load
protected override void BP_ViewStateiInit()
{
CurrentForm.AddTopHTML("<p>Hello, World!</p>");
}
AddBottomHTML
This API adds a block of HTML code to the bottom of a form.
Parameters
pHTML: A string value containing the raw HTML code to add to the top of the page.
Returns
None
Examples
// We'll add our JavaScript in the initial load
protected override void BP_ViewStateiInit()
{
CurrentForm.AddBottomHTML("<p>Hello, World!</p>");
}
ConvertSysVarsInString
This API converts system variables in a string.
Parameters
String: The string in which to find the system variables.
FormControl: (Optional) The form control to reference for control-specific system variables (e.g. "{ROW_NUM}")
Returns
String: The resultant string after converting every system variable.
Examples
// Returns "USER1 editing this form on 2008-01-01"
bp.log0(CurrentForm.ConvertSysVarsInString("{CURR_USER} editing this form
on {CURR_DATE}"));
var cText = CurrentForm.FormControl("Item", 2);
// Returns "Row number: 2"
string result2 = CurrentForm.ConvertSysVarsInString("Row number: {ROW_NUM}", cText);
CreateDummy
This API creates a dummy copy of an existing form, or of an Array Row, which can be filled with data attached to a Process Timeline via other APIs. This is an overloaded method with the following possible declarations:
public static FormControl CreateDummy(Form form)
public static FormControl CreateDummy(FormControl fcArray, int row)
Parameters
Form: The Form object to reproduce.
fcArray: An Array control.
row: An Array row.
Returns
None
Examples
Form myForm = CreateDummy(CurrentForm);
FindControlInForms (Static Method)
This API searches through each field of a given name containing a given value and returns a list of each form control that matches the query. This is an overloaded method with the following possible declarations:
public static List<FormControl> FindControlInForms(bp BP, string FCName,
string Value)
public static List<FormControl> FindControlInForms(bp BP, string FCName,
string FORMID,
string Value)
Parameters
BP: The BP Object.
FCName: The name of the form controls that will be returned.
FORMID (Optional): The FORMID of the form definition that contains the controls.
Value: The value of the form controls that will be returned.
Returns
List: A list object containing the form controls.
Example
List myList = FindControlInForms(bp, "ControlName", "ControlValue");
FormControl
This API will return a single form control. When using arrays, if you retrieve a form object without specifying a row number, you are acting on the entire column. This is an overloaded method with the following possible declarations:
public FormControl FormControl(string Name, int ArrayNum)
public FormControl FormControl(string pName, FormControl RefControl)
public FormControl FormControl(string pName, FormControl RefArray,
int ArrayNum)
Parameters
Name: The name of the form control to retrieve.
ArrayNum: (optional) Form controls in an array, the row number of the specific control
ReturnNullIfNotFound: (optional) If set to true, the API will return a null if the form control isn't found. If set to false (default), the API will return an empty FormControl object if it isn't found
Returns
FormControl: The form control instance.
Example
// Add 1 to the Count form control
CurrentForm.FormControl("Amount").Number += 1;
// Make the Item in row 2 required
CurrentForm.FormControl("Item", 2).Display.Required = eYNU.Yes;
// Make the entire Description column required
CurrentForm.FormControl("CodeComment").Display.Required = eYNU.Yes;
FormControlByID
This API will return a form control which corresponds to the ID you pass it. You would use this when you have a Form's ID (e.g. from a ControlPicker control). This is an overloaded method with the following possible declarations:
public FormControl FormControlByID(string FCID)
public FormControl FormControlByID(string FCID, int ArrayNum)
public FormControl FormControlByID(string pFCID, FormControl RefControl)
Parameters
ArrayNum: (optional) Form controls in an array, the row number of the specific control
FCID: The ID of the control to retrieve
pFCID: The ID of the control to retrieve
RefControl: Optional) The FormControl object to be retrieved
Returns
FormControl: The form control instance.
Examples
var cPicker = CurrentForm.FormControl("CodeComment").Value;
// If "ControlsPick" is a ControlPicker on the Form
// set the form control's text to "Add Another"
CurrentForm.FormControlByID(cPicker).Text = "Add Another";
var cPick2 = CurrentForm.FormControl("CodeComment2").Value;
// Increment the control's value by 1
CurrentForm.FormControlByID(cPick2).Number += 1;
// Disable the whole column of the control
CurrentForm.FormControlByID(cPick2).Display.Enabled = false;
FormNavigate
This API is an override for the base FormNavigate method, and enables you to create a custom Form Navigate method.
public virtual void FormNavigate(BPLogix.WorkflowDirector.SDK.bp bp, string URL)
Parameters
bp: The Process Director SDK handle.
URL: The string value containing the URL to which to navigate.
Returns
None.
Examples
public virtual void FormNavigate(BPLogix.WorkflowDirector.SDK.bp bp, string URL)
{
// Your custom page navigation code here.
}
GetErrorMessages
This API will get the list of all current error messages. The error messages may have been placed there from the built-in validation, or from messages added from script.
Parameters
None
Returns
List<FormMessageString>: The list of form error messages.
Example
// This example will be called after built-in validation has occurred
protected override void BP_Validation_Post()
{
var ErrorList = CurrentForm.GetErrorMessages();
// Check to see if there are more than 5 error messages
if (ErrorList.Count > 5)
{
CurrentForm.AddInfoMessage("More than 5 errors!");
}
}
GetFormByFORMID (Static Method)
This API will get a Form object based on the Form ID.
Parameters
BP: The BP environment.
FORMID: The ID of the form to retrieve.
Returns
Form: An instance of the form object, or null if it couldn't be found.
Example
// This example will get a form instance, and log its name
var OtherForm = Form.GetFormByFORMID(bp, "FORMID");
bp.log0("The form name is: " + OtherForm.Name);
GetFormByFORMINSTID (Static Method)
This API will get a Form instance object based on the ID.
Parameters
BP: The BP environment.
FORMINSTID: The ID of the form instance to retrieve
Returns
Form: An instance of the form object, or null if it couldn't be found.
Example
// This example will get a form instance, and log its name
var myForm = Form.GetFormByFORMINSTID(bp, "FORMINSTID");
bp.log0("The form instance name is: " + myForm.Name);
GetFormSchema
This API will get an list object containing the form's schema.
Parameters
None.
Returns
List: A list object containing the form's schema.
Example
// This example will get a form schema
List mySchema = Form.GetFormSchema();
GetInfoMessages
This API will get the list of all current informational messages. The info messages must have been previously added from script.
Parameters
None
Returns
List<FormMessageString>: The list of form error messages.
Example
// This example will be called immediately prior to displaying the form
protected override void BP_Display()
{
var InfoList = CurrentForm.GetInfoMessages();
foreach (var info in InfoList)
{
bp.log0("INFO MESSAGE: " + info);
}
}
Instantiate (Static Method)
This API will instantiate a new form instance. This is an overloaded method with the following possible declarations:
public static Form Instantiate(bp BP, string FORMID)
public static Form Instantiate(bp BP, string FORMID,
bool SkipDefaultValues)
Parameters
BP: The bp environment
FORMID: The ID of the form definition to instantiate
SkipDefaultValues: Optional Boolean parameter to tell the Form processor to skip setting default form values.
Returns
Form: An instance of the form object, or null if it couldn't be found.
Example
// This example will create a new form instance
var NewFormInstance = Form.Instantiate(bp, ContentObject.GetObjectByPathName(bp,
“Partition1”,
“/My Project/My Form Definition”).ID);
bp.log0("The form instance name is: " + NewFormInstance.Name);
SaveAndSubmit
This API will save a form instance (just like SaveForm does), but won't prevent a process from running if the form submission would normally trigger the start of a process.
Parameters
None
Returns
None
Example
CurrentForm.SaveAndSubmit();
SaveForm
This API will save the current form irrespective of whether it is being displayed. It will increment the form internal version number. If this is a new form instance, calling this API won't automatically start a Process Timeline instance associated with this form definition.
Parameters
None
Returns
None
Example
CurrentForm.SaveForm();
SynchronizeFields
This API will synchronize all form fields marked as synchronized fields to synchronize with other fields of the same name in the specified process. If no process ID is specified, the process returned by GetProcess() is used by default.
Parameters
pPROCINSTID: An optional parameter containing the string value of the Process Instance ID.
Returns
None
Example
CurrentForm.SynchronizeFields();
UnlockForm
This API will unlock a Form that has been locked for editing.
Use caution when using this API call! If a form is already locked for editing, and you unlock and edit the form, the locking user may save their version of the form later, and all of your changes will be overwritten.
Parameters
None
Returns
None
Example
CurrentForm.UnlockForm();
Events #
There are six main types of events that are initiated when using Forms, each of which will be discussed separately below. Each of these event types contains a series of individual events that occur in a specific order, called the order of operations. Developers and implementers have access to the order of operations for each event type in two different ways: via scripting, or via the use of Custom Tasks.
When each event fires, scripted event procedures are implemented first, then Custom Tasks associated with the event are implemented. As a result, event scripts can set values or perform other operations that, when the script is complete, are available for the Custom Task to use when it is implemented.
Event Types
New Form is opened
When a new form is opened, the following set of events are fired in the order shown below:
- BP_FormInitialize Script
- Form Creation Custom Task
- BP_ViewStateInit Script
- View State Init Custom Task
- BP_Rules Script
- Before Conditions Custom Task
- BP_Rules_Post Script
- After Conditions Custom Task
- BP_Display Script
- Form Display Custom Task
Existing Form is opened
When an existing Form is opened, the following set of events are fired in the order shown below:
- BP_ViewStateInit Script
- View State Init Custom Task
- BP_Rules Script
- Before Conditions Custom Task
- BP_Rules_Post Script
- After Conditions Custom Task
- BP_Display Script
- Form Display Custom Task
When an event is fired from a form control
When a control event is called, the following set of events are fired in the order shown below:
- BP_Event Script
- Event Custom Task
- BP_Rules Script
- Before Conditions Custom Task
- BP_Rules_Post Script
- After Conditions Custom Task
- BP_Display Script
- Form Display Custom Task
When a Form is closed from the OK or task completion button
When a Form is closed by the OK or other task completion button, the following set of events are fired in the order shown below:
- BP_Event Script
- Event Custom Task
- BP_Rules Script
- Before Conditions Custom Task
- BP_Rules_Post Script
- After Conditions Custom Task
- BP_Validation Script
- Before Validation Custom Task
- BP_Validation_Post Script
- After Validation Custom Task
- BP_Completed Script
- Form Completed Custom Task
When a Form is saved without closing
When a Form is saved, but not closed, the following set of events are fired in the order shown below:
- BP_Event Script
- Event Custom Task
- BP_Rules Script
- Before Conditions Custom Task
- BP_Rules_Post Script
- After Conditions Custom Task
- BP_Display Script
- Form Display Custom Task
When a Form is saved and closed without completing a task
When a Form is saved and closed without completing a task, the following set of events are fired in the order shown below:
- BP_Event Script
- Event Custom Task
- BP_Rules Script
- Before Conditions Custom Task
- BP_Rules_Post Script
- After Conditions Custom Task
Documentation Feedback and Questions
If you notice some way that this document can be improved, we're happy to hear your suggestions. Similarly, if you can't find an answer you're looking for, ask it via feedback. Simply click on the button below to provide us with your feedback or ask a question. Please remember, though, that not every issue can be addressed through documentation. So, if you have a specific technical issue with Process Director, please open a support ticket.
