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