The Lookup
Overview
The Lookup groups a title with a list of selectable values.
Properties
The Lookup supports the following properties:
Attributes - Options
AutoPostBack
A Boolean value indicating whether a change in the Lookup’s value should cause the activity to be sent to the server for additional server-side computations. The default value is False.
How do I get the AutoPostBack value of a Lookup
Using C#:
var optionsValue = control.RefreshOnChange;
Via VBScript:
optionValue = control.Options.Item("AutoPostBack")
How do I set the AutoPostBack value of a Lookup
Using C#:
control.RefreshOnChange = false;
Via VBScript:
control.Options.Item("AutoPostBack") = "False"
Caution
The value assigned (as it relates to VBScript) must be a string value (enclosed with double quotes) and not the more natural Boolean equivalent as the latter can sometimes be incorrectly translated (due to localization/globalization).
In both cases the Lookup is referenced as described in the sections Reference a List Control and Reference a Lookup for Managed Code and VBScript, respectively.
Enabled
A Boolean value indicating whether the Lookup should allow user interaction. The default value is True.
How do I get the Enabled value of a Lookup
Using C#:
var optionsValue = control.Enabled;
Via VBScript:
optionValue = control.Options.Item("Enabled")
How do I set the Enabled value of a Lookup
Using C#:
control.Enabled = true;
Via VBScript:
control.Options.Item("Enabled") = "True"
Caution
The value assigned (as it relates to VBScript) must be a string value (enclosed with double quotes) and not the more natural Boolean equivalent as the latter can sometimes be incorrectly translated (due to localization/globalization).
In both cases the Lookup is referenced as described in the sections Reference a List Control and Reference a Lookup for Managed Code and VBScript, respectively.
Style
A text value adding additional styles to be applied to the Lookup by supporting clients. This is primarily CSS for web clients.
How do I get the Style of a Lookup
Using C#:
using FlowCentric.Engine.Entities.Classic;
//...
var optionsValue = WebExtensions.GetCssStyle(control);
// or
var optionsValue = control.GetCssStyle();
Via VBScript:
optionValue = control.Options.Item("Style")
How do I set the Style of a Lookup
Using C#:
using FlowCentric.Engine.Entities.Classic;
//...
WebExtensions.SetCssStyle(control, optionsValue);
// or
control.SetCssStyle(optionsValue);
Via VBScript:
control.Options.Item("Style") = "background-color:#CC0000;color:white;"
In both cases the Lookup is referenced as described in the sections Reference a List Control and Reference a Lookup for Managed Code and VBScript, respectively.
Visible
A Boolean value indicating whether the Lookup should be displayed by a client. An invisible Lookup is mostly not even rendered by a client and can therefore not be targeted on the client’s side (by, say, JavaScript on web clients). The default value is True.
How do I get the Visible value of a Lookup
Using C#:
var isVisible = control.Visible;
Via VBScript:
optionValue = control.Options.Item("Visible")
How do I set the Visible value of a Lookup
Using C#:
control.Visible = true;
Via VBScript:
control.Options.Item("Visible") = "True"
Caution
The value assigned (as it relates to VBScript) must be a string value (enclosed with double quotes) and not the more natural Boolean equivalent as the latter can sometimes be incorrectly translated (due to localization/globalization).
In both cases the Lookup is referenced as described in the sections Reference a List Control and Reference a Lookup for Managed Code and VBScript, respectively.
Width
An integer value dictating the horizontal size of the Lookup. This value is inherently measured in number of pixels, and the default value is client-specific.
How do I get the Width of a Lookup
Using C#:
var width = control.Width;
Via VBScript:
optionValue = control.Options.Item("Width")
How do I set the Width of a Lookup
Using C#:
control.Width = 200;
Via VBScript:
control.Options.Item("Width") = "200"
In both cases the Lookup is referenced as described in the sections Reference a List Control and Reference a Lookup for Managed Code and VBScript, respectively.
Behavior
Column
An integer value that specifies in which column the Lookup is to be rendered on supporting clients (e.g. a mobile client usually only has one column and all objects are rendered underneath each other). This value has no effect on grouped objects as the column in the containing Object Group is determined exclusively by the index of the grouped objects. A column number of 0 indicates that the un-grouped Lookup should span the entire line that it is on, while any other value specifies the actual column number. The default value of 1 positions the Lookup in the first column.
Note
The column number affects the rendition of the activity (on supporting clients) where, as an example, a maximum column number of 10 would result in all objects rendered in such a way as to populate 10 columns.
Tip
A maximum number of 4 columns should be considered the best (visual) practice.
How do I get the Column number of a Lookup
Using C#:
using FlowCentric.Engine.Entities.Classic;
//...
var columnNumber = WebExtensions.GetColumnNumber(control);
// or
var columnNumber = control.GetColumnNumber();
Via VBScript:
columnNumber = control.ColumnNo
How do I set the Column number of a Lookup
Using C#:
using FlowCentric.Engine.Entities.Classic;
//...
WebExtensions.SetColumnNumber(control, columnNumber);
// or
control.SetColumnNumber(columnNumber);
Via VBScript:
control.ColumnNo = 0
In both cases the Lookup is referenced as described in the sections Reference a List Control and Reference a Lookup for C# and VBScript, respectively.
Type
The type associated with the Lookup; this value is typically set on dragging-and-dropping a specific object.
How do I get the Type of a Lookup
Using Managed Code:
The type of a control in Managed Code is implicit (based on the control hierarchy), and in the case of a Lookup the target control type is either ListControl or ListColumnControl depending on whether it is grouped.
Via VBScript:
controlType = control.Type
Where the Lookup is referenced as described in the sections Reference a List Control and Reference a Lookup for Managed Code and VBScript, respectively.
Business Intelligence
BI Node
A Boolean value indicating whether the values of a Lookup are to be included in Business Intelligence Tools (such as QlikView, etc.). The default value is False.
BI Caption
An (optional) short text based description associated with, and overriding the default Caption for, an object in Business Intelligence Tools. Either captions are only included with all the object’s values based on the BI Node value for the object (as mentioned earlier).
Content Definition
Dynamic Value
The VBScript script to be executed at runtime as associated with the Lookup.
Control
Required Field
A Boolean value indicating that the Lookup requires input, that is evaluated at runtime preventing an activity from being submitted when such configured object is empty (without value). The default value is False.
How do I get the Required Field value of a Lookup
Using C#:
var required = control.IsRequired;
Via VBScript:
isRequired = control.Required
How do I set the Required Field value of a Lookup
Using C#:
control.IsRequired = false;
Via VBScript:
control.Required = False
Caution
Setting this value to True when the Lookup is hidden will prevent the associated activity from submitting.
In both cases the Lookup is referenced as described in the sections Reference a List Control and Reference a Lookup for Managed Code and VBScript, respectively.
Identification
ID
Displays the (read-only) numeric identifier of a Lookup.
How do I get the ID of a Lookup
Using C#:
var id = control.Id;
Via VBScript:
id = control.ID
Where the Lookup is referenced as described in the sections Reference a List Control and Reference a Lookup for Managed Code and VBScript, respectively.
Parent
Displays the (read-only) numeric identifier of the activity containing (or parenting) the Lookup.
How do I get the ID of an Lookup’s parent activity in VBScript
By directly referencing its parent, as in:
id = fcBusinessEvent.EventID
Object Group
The id-name pair of the Object Group of which the Lookup becomes a member; the object is referred to as a grouped object when this value is set, and normal/ungrouped when not set. From a VBScript Scripting point of view, all objects that do not (explicitly) form part of an Object Group (that is, all ungrouped objects excluding Command Options) belong to the (same) default Object Group (with id 0).
How do I get the ID of the Object Group to which a Lookup belongs in VBScript
Again, by directly referencing it, as in:
id = controlGroup.ID
The Object Group's name is accessed similarly, as in:
name = controlGroup.Name
In both cases, the Object Group is referenced as described in the section Reference a Lookup.
Note
Neither the ID nor the name of the Object Group can be changed.
Name
The unique (per activity name of the Lookup that can be used to reference the object at runtime (via VBScript). It is usually of the form ActivityNamePrefix_ObjectName, where ActivityNamePrefix usually denotes part of the activity name (and very often the activity's index in the process containing it). As an example, an object displaying the number of days some user has accrued for leave in an activity named LR10_ApplyForLeave (the first activity in a process called Leave Requisition) could be named LR10_NumberOfLeaveDaysAvailable.
How do I get the Name of a Lookup
Using C#:
var name = control.Name;
Via VBScript:
name = control.Name
Where the Lookup is referenced as described in the sections Reference a List Control and Reference a Lookup for Managed Code and VBScript, respectively.
Note
The name cannot be changed.
Caption
The title (or short text description) preceding (historically horizontally, while on more modern clients, vertically) the Lookup in a client specific fashion. In the case of a grouped object, the caption becomes the heading of the column containing the object’s (possibly many) values (as in one value per Object Group line).
How do I get the Caption of a Lookup
Using C#:
var caption = control.Caption.Text;
Via VBScript:
caption = control.DisplayName
How do I set the Caption of a Lookup
Using C#:
control.Caption.Text = "Control Caption";
Via VBScript:
control.DisplayName = "Object Caption"
Where the Lookup is referenced as described in the sections Reference a List Control and Reference a Lookup for Managed Code and VBScript, respectively.
Tooltip Text
An optional narrative to be displayed by supporting clients to further describe the Lookup, its expected value and/or its intent in the activity.
How do I get the Tooltip Text of a Lookup
Using C#:
toolTipText = control.ToolTip.Text;
Via VBScript:
toolTipText = control.Description
How do I set the Tooltip Text of a Lookup
Using C#:
control.ToolTip.Text = "Some narrative describing the object’s intent.";
Via VBScript:
control.Description = "Some narrative describing the object’s intent."
Where the Lookup is referenced as described in the sections Reference a List Control and Reference a Lookup for Managed Code and VBScript, respectively.
Index
A unique (per activity) integer value that, firstly orders the script execution of the current Lookup relative to all the other objects on the same activity (as in the script on object with index i will always be executed prior to the script on the succeeding object with index i+1), and secondly orders the rendering of the objects by a client (object with index i will be rendered before a object with index i+1, assuming both are visible).
When the Layout property on an activity is set to the value [GroupByControlIndex], the index indicates the location of the grouped object's associated Object Group relative to the other objects on that activity.
How do I get the Index of a Lookup
Using C#:
using FlowCentric.Engine.Entities.Classic;
//...
var index = Extensions.GetIndex(control);
// or
var index = control.GetIndex();
Via VBScript:
index = control.Index
How do I set the Index of a Lookup
using FlowCentric.Engine.Entities.Classic;
//...
Extensions.SetIndex(control, 130);
// or
control.SetIndex(130);
Via VBScript:
control.Index = 130
Where the Lookup is referenced as described in the sections Reference a List Control and Reference a Lookup for Managed Code and VBScript, respectively.
Warning
Object indexes must be unique within the activity, that is, two objects are not allowed to have the same index – this will result in runtime errors.
How do I (using Managed Code (.NET))
The class hierarchy in Managed Code, as it pertains to Lookups, is shown here:
Reference a List Control
Managed Code implementations of Processware activities must extend the type FlowCentric.Engine.Managed.TaskForm (located in the FlowCentric.Engine.Contracts assembly) to be considered by the engine for execution. This base type provides a single method for accessing (un-grouped/normal) controls, with the following signature:
protected TControl GetControl<TControl>(string controlName) where TControl : Control;
and in VB.NET
Protected Function GetControl(Of TControl As Control)(controlName As String) As TControl
Accessing a Lookup from within a sub-TaskForm is accomplished with
var control = base.GetControl<ListControl)("NameOfControl");
TaskForm defines an inner type, ColumnsGroup, representing an Object Group, that needs to be sub-classed in order to access the controls contained by the group. This inner type provides a single method for accessing the controls contained by it, with the following signature:
protected TControl GetControl<TControl>(string controlName) where TControl : ColumnControl;
and in VB.NET
Protected Function GetControl(Of TControl As ColumnControl)(controlName As String) As TControl
Accessing a Lookup from within a sub-ColumnsGroup is accomplished with
var control = base.GetControl<ListColumnControl)("NameOfGroupedControl");
Retrieve the value of a List Control
From within the same activity implementation (TaskForm)
a) To retrieve the value of a normal/un-grouped control, simply access it's SelectedItem property, as in:
selectedItem = control.SelectedItem;
b) To retrieve the value of a grouped control, or column control, simply access it's SelectedItem or SelectedValue for some specific, valid, and 0-based row number, as in:
// Get the item at the specified 0-based row:
selectedItem = ListControlExtensions.GetSelectedItem(control, rowNumber);
// Get the value at the specified 0-based row:
selectedValue = ListControlExtensions.GetSelectedValue(control, rowNumber);
// alternatively:
selectedItem = control.GetSelectedItem(rowNumber);
selectedValue = control.GetSelectedValue(rowNumber);
In both cases above, the specific control is retrieved as is illustrated in the preceding section.
From within a subsequent activity implementation (TaskForm)
To access the value of a control within a subsequent TaskForm, the specific control needs to be located from history. This requires looking up the specific TaskForm, and from it the specific control. Translating the aObjects construct requires finding the first such TaskForm instance in the branch originating from the current TaskForm implementation (and ending in the first activity that started the associated process instance):
var task = context.FirstParentOfCurrent(parent =>
StringComparer.Ordinal.Equals(parent.Name, "SomePrecedingTaskName"));
Where context is one of the FormXXXContext parameters from an appropriately overridden TaskForm method.
a) If the control of interest is a normal/un-grouped control, it's value is accessed as follows:
// Locate the field of interest:
var field = task?.Fields.OfType<IImmutableField>().FirstOrDefault(f =>
StringComparer.Ordinal.Equals(f.Name, "ControlName"));
// Get it's value:
var textValue = field?.Value;
b) For grouped/column controls, the associated value is accessed once the grouped field is retrieved, as in:
// Locate the field of interest:
var field = task?.Fields.OfType<IImmutableListFieldGroup>()
.Where(group =>
StringComparer.Ordinal.Equals(group.Name, "ContainingGroupName"))
.SelectMany(group => group.Fields)
.FirstOrDefault(f =>
StringComparer.Ordinal.Equals(f.Name, "GroupedControlName"));
// or, simply:
var field = task?
.ListFields(
group => StringComparer.Ordinal.Equals(group.Name, "ContainingGroupName"),
f => StringComparer.Ordinal.Equals(f.Name, "GroupedControlName"))
.FirstOrDefault();
// Get the value at some specific, 0-based, line number:
var textValue = field?[lineNumber];
Set the value of a List Control
a) To set the value of a normal/un-grouped control, simply access it's SelectedItem property, as in:
control.SelectedItem = selectedItem;
b) To set the value of a grouped control, or column control, simply access it's SelectedItem or SelectedValue for some specific, valid, and 0-based row number, as in:
ListControlExtensions.SetSelectedItem(control, rowNumber, selectedItem);
ListControlExtensions.SetSelectedValue(control, rowNumber, selectedValue);
// or, simply:
control.SetSelectedItem(rowNumber, selectedItem);
control.SetSelectedValue(rowNumber, selectedValue);
In both cases above, the specific control is retrieved as is illustrated in a preceding section.
Specifying List Control Items
Specifying the items associated with normal/un-grouped List Controls is similar to specifying the items on Drop Down Controls:
ListControlExtensions.SetItems(control, itemValues);
ListControlExtensions.SetItems(control, dataSet);
// or, simply:
control.SetItems(itemValues);
control.SetItems(dataSet);
// and:
control.Items = items;
With grouped List Controls, the items are set in a similar fashion, but per line:
ListControlExtensions.SetItems(control, rowNumber, itemValues);
ListControlExtensions.SetItems(control, rowNumber, dataSet);
// or, simply:
control.SetItems(rowNumber, itemValues);
control.SetItems(rowNumber, dataSet);
// and:
control.SetItems(rowNumber, items);
In both cases above, the specific control is retrieved as is illustrated in a preceding section.
How do I (in VBScript)
Reference a Lookup
To reference a Lookup that is not grouped (that is, belongs to the default Object Group), follow the hierarchy: current activity -> default Object Group -> Lookup, as in:
Set controlGroup = fcBusinessEvent.ObjectGroups.Item("0")
Set control = controlGroup.Items("ObjectName")
Or simply
Set control = fcBusinessEvent.ObjectGroups.Item("0").Items("ObjectName")
When the Lookup to be referenced is grouped, the hierarchy changes slightly to take the (actual) Object Group into consideration: current activity -> specific Object Group -> Lookup, as in
Set controlGroup = fcBusinessEvent.ObjectGroups.NamedItem("ObjectGroupName")
Set control = controlGroup.Items("ObjectName")
Or simply
Set control = fcBusinessEvent.ObjectGroups.NamedItem("ObjectGroupName").Items("ObjectName")
Retrieve the selected value of a Lookup (the source object)
From within the Lookup’s Dynamic Value
a) The simplest way to access the value of a Lookup from within itself is to use the aObjects VBScript placeholder construct, as in
textValue = "aObjects("ObjectName")"
Important
It is very important to note the quotation marks around the aObjects construct, as the entire placeholder (as in aObjects("ObjectName")) will be replaced at runtime with the actual value for the object with the specified name.
b) Another way to access the value of a Lookup (any object for that matter, when it is on the same activity) is to first reference the object (as described previously in the section Reference a Lookup). Retrieving the value in the resulting object depends, again, on whether it is:
an ungrouped object:
textValue = control.Item(0, False)or a grouped object:
textValue = control.Item(lineNumber, False)
where lineNumber falls in the valid range of line numbers in the containing group [0, controlGroup.Lines).
From within another object (the target)
a) When the source Lookup is not grouped, use either options from the preceding section (From within the Lookup’s Dynamic Value) irrespective of the grouping of the target object.
b) When the source Lookup is grouped and the target object is
either not grouped, or grouped in a different Object Group, use the latter option from the preceding section (From within the Lookup’s Dynamic Value)
grouped in another Object Group and all the values of the grouped source object is to be copied line by line to the target object`s values, the fcDataBlock VBScript construct provides a simpler mapping mechanism (when compared to the latter option from the preceding section From within the Lookup’s Dynamic Value)
With fcDataBlock .CurrentProcess = Process.ID .Company = Process.Company .ImportLineItems "ActivityName", "SourceObjectGroupName" .Filter = "//fcRecord" .Mapping.Add "SourceObjectName","TargetObjectName" fcLineItems = .LineItems End With
The benefit of using the above is that more than one source object`s values could be copied to target object values
- grouped in the same Object Group, use the first option (aObjects) from the preceding section (From within the Lookup’s Dynamic Value). This is necessary as access to the line number within the group is not available, and the target object can only reference the value of the source object on the same line.
From within another object in a subsequent activity
a) When the source Lookup is not grouped, access its value using the first option (aObjects) from the preceding section (From within the Lookup’s Dynamic Value)
b) When both objects are grouped, the simplest solution is to copy all source object values to a target object values using the fcDataBlock option from the preceding section (From within another object (the target)). In this case, the activity name will reference the last such instance in the branch preceding the current activity instance (at runtime). A branch is simply a directed graph from the current pending activity instance all the way to the first activity that started the process instance.
Set the selected value displayed in a Lookup
Indirectly from another (grouped or ungrouped) object
To set the selected value displayed in a Lookup on the Dynamic Value of another (whether grouped or ungrouped) object, one first need to reference the object (see Reference a Lookup). Changing the text value on an ungrouped Lookup is equivalent to changing the text on the first line number (0-based) of an actual grouped Lookup, as shown here:
control.Item(0, False) = "Value set from another object"
Changing any of the values in a grouped Lookup other than that on the first line, replace the 0 with the appropriate line number (remembering that it is 0 based).
Tip
The value must exist in the Lookup’s list of values.
Display a default value that may or may not change during runtime
The fcDefaultTo contextual VBScript keyword is available on supported object`s Dynamic Value, and is similar in usage to the fcLabel keyword shown earlier:
fcDefaultTo = "Item 2"
The difference between these keywords is that when a supporting object does not have a value, the default value is used – the object will therefore never be without a value. This is useful when object values might change due to user interactions, and a non-empty value is always required.
Tip
The value must exist in the Lookup’s list of values.
fcSQL
fcSQL is a VBScript string variable that is interpreted, in conjunction with fcConn, at runtime to specify the (possibly dynamic) list of selectable items for a Lookup. The result set following the execution of the fcSQL variable should be a one-dimensional collection of values, where the values can further be divided into plain\normal values, or key-value pairs separated by a colon, ‘:’. In both cases the resulting collection become the selectable list of items (as-is, that is with the : when used). The main reason for using the key-:-value pair comes into play when accessing the selected item, the result of which is the key (only) and not the value as is the case with the "normal" list of items. This aids greatly in scenarios where the key of an item is more important from a relational point of view, and another roundtrip to the database to retrieve this key from its value could be avoided. Unfortunately, some clients present this list as-is and the visual effect is often not desirable.
Tip
fcSQL can also be populated based on the value(s) of one or more objects, resulting in a dynamic collection. One of the benefits hereof is that, unlike its Drop Down and Team Select counterparts, a grouped Lookup object may have selectable items that differ per Object Group line.
Important
Keep in mind that the specific SQL dialect depends on the data store referenced by fcConn.
Property Compatibility Matrix
The following details the client support for the properties of Lookups
