The Reference Label
Overview
The Reference Label defines a title with a read-only text value to be displayed by a client.
Properties
Reference Labels support the following properties:
Attributes - Options
Style
A text value adding additional styles to be applied to the Reference Label by supporting clients. This is primarily CSS for web clients.
How do I get the Style of a Reference Label
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 Reference Label
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 Reference Label is referenced as described in the sections Reference a Label Control and Reference a Reference Label for Managed Code and VBScript, respectively.
Visible
A Boolean value indicating whether the Reference Label should be displayed by a client. An invisible Reference Label 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 Reference Label
Using C#:
var isVisible = control.Visible;
Via VBScript:
optionValue = control.Options.Item("Visible")
How do I set the Visible value of a Reference Label
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 Reference Label is referenced as described in the sections Reference a Label Control and Reference a Reference Label for Managed Code and VBScript, respectively.
Width
An integer value dictating the horizontal size of the Reference Label. This value is inherently measured in number of pixels, and the default value is client-specific.
How do I get the Width of a Reference Label
Using C#:
var width = control.Width;
Via VBScript:
optionValue = control.Options.Item("Width")
How do I set the Width of a Reference Label
Using C#:
control.Width = 100;
Via VBScript:
control.Options.Item("Width") = "100"
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 Reference Label is referenced as described in the sections Reference a Label Control and Reference a Reference Label for Managed Code and VBScript, respectively.
Behavior
Column
An integer value that specifies in which column a Reference Label 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 Reference Label 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 Reference Label 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 Reference Label
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 Reference Label
Using C#:
using FlowCentric.Engine.Entities.Classic;
//...
WebExtensions.SetColumnNumber(control, columnNumber);
// or
control.SetColumnNumber(columnNumber);
Via VBScript:
control.ColumnNo = 0
In both cases the Reference Label is referenced as described in the sections Reference a Label Control and Reference a Reference Label for Managed Code and VBScript, respectively.
Type
The type associated with the Reference Label; this value is typically set on dragging-and-dropping a specific object.
How do I get the Type of a Reference Label
Using Managed Code:
The type of a control in Managed Code is implicit (based on the control hierarchy), and in the case of a Reference Label the target control type is either LabelControl
or LabelColumnControl
depending on whether it is grouped.
Via VBScript:
controlType = control.Type
Where the Reference Label is referenced as described in the sections Reference a Label Control and Reference a Reference Label for Managed Code and VBScript, respectively.
Business Intelligence
BI Node
A Boolean value indicating whether the values of the Reference Label 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, the Reference Label 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 Reference Label.
Identification
ID
Displays the (read-only) numeric identifier of the Reference Label.
How do I get the ID of a Reference Label
Using C#:
var id = control.Id;
Via VBScript:
id = control.ID
Where the Reference Label is referenced as described in the sections Reference a Label Control and Reference a Reference Label for Managed Code and VBScript, respectively.
Parent
Displays the (read-only) numeric identifier of the activity containing (or parenting) the Reference Label.
How do I get the ID of a Reference Label’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 Reference Label becomes a member; the object is referred to as a grouped object when this value is set, and normal/un-grouped 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 un-grouped 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 Reference Label 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 Reference Label.
Note
Neither the ID nor the name of the Object Group can be changed.
Name
The unique (per activity name of the Reference Label 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 Reference Label
Using C#:
var name = control.Name;
Via VBScript:
name = control.Name
Where the Reference Label is referenced as described in the sections Reference a Label Control and Reference a Reference Label 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 Reference Label 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 Reference Label
Using C#:
var caption = control.Caption.Text;
Via VBScript:
caption = control.DisplayName
How do I set the Caption of a Reference Label
Using C#:
control.Caption.Text = "Control Caption";
Via VBScript:
control.DisplayName = "Object Caption"
In both cases the Reference Label is referenced as described in the sections Reference a Label Control and Reference a Reference Label for Managed Code and VBScript, respectively.
Tooltip Text
An optional narrative to be displayed by supporting clients to further describe the Reference Label, its expected value and/or its intent in the activity.
How do I get the Tooltip Text of a Reference Label
Using C#:
toolTipText = control.ToolTip.Text;
Via VBScript:
toolTipText = control.Description
How do I set the Tooltip Text of a Reference Label
Using C#:
control.ToolTip.Text = "Some narrative describing the object’s intent.";
Via VBScript:
control.Description = "Some narrative describing the object’s intent."
In both cases the Reference Label is referenced as described in the sections Reference a Label Control and Reference a Reference Label for Managed Code and VBScript, respectively.
Index
A unique (per activity) integer value that, firstly orders the script execution of the current Reference Label 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 Reference Label
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 Reference Label
Using C#:
using FlowCentric.Engine.Entities.Classic;
//...
Extensions.SetIndex(control, 130);
// or
control.SetIndex(130);
Via VBScript:
control.Index = 130
In both cases the Reference Label is referenced as described in the sections Reference a Label Control and Reference a Reference Label 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 Reference Labels, is shown here:
Reference a Label 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 Reference Label from within a sub-TaskForm
is accomplished with
var control = base.GetControl<LabelControl>("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 Reference Label from within a sub-ColumnsGroup
is accomplished with
var control = base.GetControl<LabelColumnControl>("NameOfGroupedControl");
Retrieve the value of a Label Control
From within the same activity implementation (TaskForm
)
a) To retrieve the value of a normal/un-grouped control, simply access it's Text
property, as in:
textValue = control.Text;
b) To retrieve the value of a grouped control, or column control, simply access it's Text
for some specific, valid, and 0-based row number, as in:
// Get the text value at the specified 0-based row:
textValue = LabelControlExtensions.GetText(control, rowNumber);
// alternatively:
textValue = control.GetText(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 Label Control
a) To set the value of a normal/un-grouped control, simply access it's Text
property, as in:
control.Text = "This is the Control’s value";
b) To set the value of a grouped control, or column control, simply access it's Text
for some specific, valid, and 0-based row number, as in:
// Updating a row number label control:
for(var rowNumber = 0; rowNumber < Group.NumberOfRows; rowNumber++)
{
LabelControlExtensions.SetText(control, rowNumber, (rowNumber + 1).ToString());
// or, simply:
control.SetText(rowNumber, (rowNumber + 1).ToString());
}
In both cases above, the specific control is retrieved as is illustrated in a preceding section.
How do I (in VBScript)
Reference a Reference Label
To reference a Reference Label that is not grouped (that is, belongs to the default Object Group), follow the hierarchy: current activity -> default Object Group -> Reference Label, 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 Reference Label to be referenced is grouped, the hierarchy changes slightly to take the (actual) Object Group into consideration: current activity -> specific Object Group -> Reference Label, 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 value of a Reference Label (the source object)
From within the Reference Label’s Dynamic Value
a) The simplest way to access the value of a Reference Label 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 Reference Label (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 Reference Label). 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 Reference Label is not grouped, use either options from the preceding section (From within the Reference Label’s Dynamic Value) irrespective of the grouping of the target object.
b) When the source Reference Label 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 Reference Label’s Dynamic Value)
grouped in another Object Group and all the values of the grouped source Reference Label 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 Reference Label’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 Reference Label’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 object is not grouped, access its value using the first option (aObjects) from the preceding section (From within the same (source) object’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 text value displayed in a Reference Label
Directly (grouped and ungrouped Reference Labels)
To set the text displayed in a Reference Label (that is, the value of the Reference Label), one assigns the text to the fcLabel contextual keyword in the Dynamic Value of the object, as can be seen here:
fcLabel = "This is the Reference Label’s value"
Tip
Even though this is the simplest way of setting the value, care should be taken since the Dynamic Value is executed on loading the activity, and on any and every post-back that might occur until the activity is finally submitted.
Indirectly from another (grouped or ungrouped) object
To set the text displayed in a Reference Label on the Dynamic Value
of another (whether grouped or ungrouped) object, one first need to reference the Reference Label (see Reference a Reference Label). Changing the text value on an ungrouped Reference Label is equivalent to changing the text on the first line number (0-based) of an actual grouped Reference Label, as shown here:
control.Item(0, False) = "Value set from another object"
Changing any of the values in a grouped Reference Label other than that on the first line, replace the 0 with the appropriate line number (remembering that it is 0 based).
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 = "This is the reference label’s default value"
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.
Property Compatibility Matrix
The following details the client support for the properties of Reference Labels