The Object Group

Overview

The Object Group groups several (non-Object Group) objects into a tabular structure, changing the behavior of the grouped objects to columns within the group, having multiple values per grouped object (one value per object per line). The caption text associated with the grouped objects become the column headings for an object's values, and the properties on an object applies to the entire column. It is worthwhile to note that this behavior differs from typical grids in which each cell in a grid is usually a control in its own rights.

Properties

Object Groups support the following properties:

Behavior

Allow Adding

A Boolean value indicating whether a user may add lines to the Object Group. The user will be presented with a client-specific mechanism (typically a button) that will allow the addition of a pre-configured number of lines to the Object Group. The default value is True.

How do I get the Allow Adding value of an Object Group

Using C#:

var allowsAddition = columns.Group.CanAddRows;

Via VBScript:

allowsAddition = controlGroup.AllowAdd

How do I set the Allow Adding value of an Object Group

Using C#:

columns.Group.CanAddRows = true;

Via VBScript:

controlGroup.AllowAdd = True

In both cases the Object Group is referenced as described in the sections Reference a Column Group for Managed Code and Reference an Object Group for VBScript.

Allow Delete

A Boolean value indicating whether a user may remove lines from the Object Group. The user will be presented with a client-specific mechanism (usually a checkbox per line and a button at the group level) that will enable to removal of specific lines from the Object Group. The default value is True.

How do I get the Allow Delete value of an Object Group

Using C#:

var allowsRemoval = columns.Group.CanRemoveRows;

Via VBScript:

allowsRemoval = controlGroup.AllowDelete

How do I set the Allow Delete value of an Object Group

Using C#:

columns.Group.CanRemoveRows = true;

Via VBScript:

controlGroup.AllowDelete = True

In both cases the Object Group is referenced as described in the sections Reference a Column Group for Managed Code and Reference an Object Group for VBScript.

Lines To Add

An integer value indicating the number of lines that will be added to an Object Group by a user, when allowed. The default value is specified by the server setting ObjectGroupLinesToAdd.

How do I get the Lines To Add value of an Object Group

Using C#:

var linesToAdd = columns.Group.NumberOfRowsToAdd;

Via VBScript:

linesToAdd = controlGroup.LinesToAdd

How do I set the Lines To Add value of an Object Group

Using C#:

columns.Group.NumberOfRowsToAdd = 3;

Via VBScript:

controlGroup.LinesToAdd = 3

In both cases the Object Group is referenced as described in the sections Reference a Column Group for Managed Code and Reference an Object Group for VBScript.

Visible

A Boolean value indicating whether an Object Group should be displayed by a client. The default value is True.

How do I get the Visible value of an Object Group

Using C#:

var isVisible = columns.Group.Visible;

Via VBScript:

isVisible = controlGroup.Visible

How do I set the Visible value of an Object Group

Using C#:

columns.Group.Visible = true;

Via VBScript:

controlGroup.Visible = True

In both cases the Object Group is referenced as described in the sections Reference a Column Group for Managed Code and Reference an Object Group for VBScript.

Content Definition

Dynamic Content

The VBScript Script associated with the Object Group.

Identification

Description

The title (or short text description) to be displayed as the heading of the Object Group, preceding the actual content (rows).

How do I get the Description of an Object Group

Using C#:

var description = columns.Group.Caption.Text;

Via VBScript:

description = controlGroup.Description

How do I set the Description of an Object Group

Using C#:

columns.Group.Caption.Text = "Column Group";

Via VBScript:

controlGroup.Description = "Object Group"

In both cases the Object Group is referenced as described in the sections Reference a Column Group for Managed Code and Reference an Object Group for VBScript.

ID

Displays the (read-only) numeric identifier of this Object Group.

How do I get the ID of an Object Group

Using C#:

var id = columns.Group.Id;

Via VBScript:

id = controlGroup.ID

Where the Object Group is referenced as described in the sections Reference a Column Group and Reference an Object Group for Managed Code and VBScript, respectively.

Note

The id cannot be changed using VBScript.

Name

The unique (per activity) name of an Object Group that can be used to reference it at runtime (via VBScript). It is usually of the form ActivityNamePrefix+ObjectGroupIndex_ObjectGroupName, where ActivityNamePrefix usually denotes part of the activity name (and very often the activity's index in the process containing it), and ObjectGroupIndex represents the index of the group in the activity. As an example, the (first) Object Group displaying order details in an activity named PO10_PurchaseRequisition could be named PO1010_OrderDetails.

Scripting

Using C#:

var name = columns.Group.Name;

Via VBScript:

How do I get the Name of an Object Group?

name = controlGroup.Name

Where the Object Group is referenced as described in the sections Reference a Column Group and Reference an Object Group for Managed Code and VBScript, respectively.

Note

The name cannot be changed.

Parent

Displays the identity of the activity containing (or parenting) an Object Group.

How do I get the ID of an Object Group’s parent activity in VBScript

By directly referencing its parent, as in:

id = fcBusinessEvent.EventID

Performance

Add Lines Script Execution Mode

Either 0, 1, or 2 indicating whether the addition of lines should execute all scripts on the activity, only scripts of objects (on all lines) in the current Object Group, or no scripts at all, respectively. The default value is 0.

Delete Lines Script Execution Mode

Either 0, 1, or 2 indicating whether the removal of lines should execute all scripts on the activity, only scripts of objects (on all lines) in the current Object Group, or no scripts at all, respectively. The default value is 0.

Post Back Script Execution Mode

Either 0, 1, or 2 indicating whether the post-back on a grouped object should execute all scripts on the activity, only scripts of objects (on all lines) in the current Object Group, or only the scripts for the objects on the same line as the object from which the post-back originates (and in the current Object Group), respectively. The default value is 0.

How do I (using Managed Code (.NET))

The class hierarchy in .NET, as it pertains to Object Groups, is shown here:

Reference a Column Group

Managed Code implementations of Processware activities must extend the type FlowCentric.Engine.Managed.TaskForm to be considered by the engine for execution. TaskForm defines an inner type, ColumnsGroup, that must be extended per associated Object Group in order to access the backing Column Group and related column controls (grouped by the Column Group). The encapsulating TaskForm is exposed to the implementation via a property with the same name, while the backing Column Group is exposed via the Group property.

Manage the loading of a ColumnsGroup implementation

One of two methods exposed by ColumnsGroup to its encapsulating TaskForm implementation enables the loading of it as well as the controls associated with it, and has the following signature:

protected virtual System.Threading.Tasks.Task LoadAsync(
    ColumnsGroupLoadContext context,
    System.Threading.CancellationToken cancellationToken);

and in VB.NET

Protected Overridable Function LoadAsync(
    context As ColumnsGroupLoadContext,
    cancellationToken As System.Threading.CancellationToken)
        As System.Threading.Tasks.Task

This is typically the new destination for the classic Dynamic Content.

Manage the refreshing of a ColumnsGroup implementation

The second method exposed by the ColumnsGroup to its encapsulating TaskForm implementation allows for refreshing the associated Column Group and related column controls, with the following signature:

protected virtual System.Threading.Tasks.Task RefreshAsync(
    ColumnsGroupRefreshContext context,
    System.Threading.CancellationToken cancellationToken);

and in VB.NET

Protected Overridable Function RefreshAsync(
    context As ColumnsGroupRefreshContext,
    cancellationToken As System.Threading.CancellationToken)
        As System.Threading.Tasks.Task

All the dynamic values of grouped/column controls would typically end up here, as this method could be called for every page refresh from a client. ColumnsGroup also exposes methods for calling the implementation of the aforementioned method, allowing it to be called when loading, etc.

Access a grouped/column control

The custom ColumnsGroup implementation has access to a method with the following signature, for accessing controls grouped by it:

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

How do I (in VBScript)

Reference an Object Group

To reference an (actual) Object Group, follow the hierarchy: current activity -> Object Group, as in:

Set controlGroup = fcBusinessEvent.ObjectGroups.NamedItem("ObjectGroupName")

The default and trigger Object Group can be referenced by index, as in (respectively):

Set controlGroup = fcBusinessEvent.ObjectGroups.Item("0")

and

Set controlGroup = fcBusinessEvent.ObjectGroups.Item("-1")

Iterate through the lines in an (actual) Object Group

Once the Object Group is referenced (see Reference an Object Group), it can be iterated as shown here:

For lineNumber = 0 To controlGroup.Lines - 1
    ' Perform some action.
Next

Sum the values of a grouped object in an Object Group

There are two ways of summing the numeric values of some grouped object in an Object Group, the more intuitive of which simply iterates through the lines as described in the preceding section (Iterate through the lines in an Object Group). The other way uses an extended version of the aObjects VBScript construct, as in:

fcLabel = aObjects("Sum.ObjectName")

Where ObjectName is the name of a grouped object.

Add lines to an (actual) Object Group

Once the Object Group is referenced (see Reference an Object Group), lines can be added as shown here:

controlGroup.AddLines numberOfLines

Remove lines from an (actual) Object Group

Once the Object Group is referenced (see Reference an Object Group), lines can be removed as shown next. Removing a specific (0-based) line number within an Object Group:

controlGroup.RemoveLine lineNumber

Removing all lines from an Object Group:

controlGroup.PurgeLines

Caveats

For historical reasons, grouped objects are persisted differently from their non-grouped counterparts. The value of a non-grouped object is always persisted, together with a partial representation (Options-only) of the state that the specific object was in at that stage. This is not the case for grouped objects, where only those with non-empty values are persisted together with the partial representation of the state of these objects. This means that if a column object does not have a single value in any of the lines in its parenting Object Group, no partial state for that object will be persisted, and hence the runtime must fall back to the design-time properties for that object when rendering that grouped object in history (or when inheriting values). Therefore, if any of the properties that form part of the partial state were changed (e.g. object was made visible/hidden, enabled/disabled, etc.) this would not reflect in history.

Furthermore, an entire line in an Object Group is empty if the first grouped object (by index) is empty; this results in the entire line getting purged. This first grouped object rule excludes any Browse Pages configured with hidden textboxes; the first grouped object that is either a Browse Page with a visible textbox, or any of the other objects determine the purge-ability of that line.