The Normal and Advanced Browse Pages
Overview
A Browse Page defines a title, an optional read-only text value and some client-specific way (usually a button) to open a single page of data rendered in tabular form with navigational, ordering and filtering elements to allow for the selection of pre-configured values. The text value for these objects, as well as other objects in the same Object Group, can be populated based on the selection (and configuration). The key difference between the (simple/normal) Browse Page and the Advanced Browse Page lies in the population of the data page (as in the retrieval of the associated data): the Browse Page retrieves all data at once, while the Advanced Browse Page is more efficient in its data retrieval.
Properties
Browse Pages support the following properties:
Attributes - Options
AutoPostBack
A Boolean value indicating whether a change in the Browse Page’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 Browse Page
Using C#:
var optionsValue = control.RefreshOnChange;
Via VBScript:
optionValue = control.Options.Item("AutoPostBack")
How do I set the AutoPostBack value of a Browse Page
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 Browse Page is referenced as described in the sections Reference a Browse Control and Reference a Browse Page for Managed Code and VBScript, respectively.
EditPage
This section defines the data to be displayed within the Browse Page.
Note
None of these properties are accessible via VBScript.
See Data Page for more details pertaining to this section.
How do I access the page definition in Managed Code
The data page definition for normal/un-grouped browse controls is directly accessible on these controls:
var pageDefinition = control.PageDefinition;
For grouped controls, or column controls, a single, global, data page definition is available using the following:
using FlowCentric.Engine.Entities.Classic;
//...
var pageDefinition = Extensions.GetPageDefinition(control);
// or
var pageDefinition = control.GetPageDefinition();
This implements the VBScript compatible access to the a single, shared, data page. With Managed Code, however, it is now possible to access a per-line data page definition, allowing the pages to be modified accordingly:
// Get the page definition at the specified, 0-based, row number.
var pageDefinition = control.GetPageDefinition(rowNumber);
Height
An integer value dictating the vertical size of a Browse Page’s data page. This value is inherently measured in number of pixels, and the default value is 600.
How do I get the Height of a Browse Page’s data page
Using C#:
var height = pageDefinition.Height;
Via VBScript:
optionValue = control.Options.Item("Height")
How do I set the Height of a Browse Page’s data page
Using C#:
pageDefinition.Height = 600;
Via VBScript:
control.Options.Item("Height") = "600"
The page definition (for Managed Code) is retrieved as described in the section How do I access the page definition in Managed Code, and the Browse Page (in the case of VBScript) as described in the section Reference a Browse Page.
Resizable
A Boolean value indicating whether the Browse Page’s data page can be resized by a user. The default value is False.
How do I get the Resizable value of a Browse Page
Using C#:
var isResizable = pageDefinition.IsResizable;
Via VBScript:
optionValue = control.Options.Item("Resizable")
How do I set the Resizable value of a Browse Page
Using C#:
pageDefinition.IsResizable = true;
Via VBScript:
control.Options.Item("Resizable") = "True"
The page definition (for Managed Code) is retrieved as described in the section How do I access the page definition in Managed Code, and the Browse Page (in the case of VBScript) as described in the section Reference a Browse Page.
Show TextBox
A Boolean value indicating whether a (read-only) text box should be available for the Browse Page. The default value depends on whether the Browse Page is grouped, in which case the text box is hidden (False), or not grouped, in which case the text box is shown (True).
How do I get the ShowTextBox value of a Browse Page
Using C#:
using FlowCentric.Engine.Entities.Classic;
//...
var optionsValue = Extensions.DisplayTextControl(control);
// or
var optionsValue = control.DisplayTextControl();
Via VBScript:
optionValue = control.Options.Item("ShowTextBox")
How do I set the ShowTextBox value of a Browse Page
Using C#:
using FlowCentric.Engine.Entities.Classic;
//...
Extensions.DisplayTextControl(control, true);
// or
control.DisplayTextControl(true);
Via VBScript:
control.Options.Item("ShowTextBox ") = "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 Browse Page is referenced as described in the sections Reference a Browse Control and Reference a Browse Page for Managed Code and VBScript, respectively.
Visible
A Boolean value indicating whether the Browse Page should be displayed by a client. An invisible object 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 Browse Page
Using C#:
var isVisible = control.Visible;
Via VBScript:
optionValue = control.Options.Item("Visible")
How do I set the Visible value of a Browse Page
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 Browse Page is referenced as described in the sections Reference a Browse Control and Reference a Browse Page for Managed Code and VBScript, respectively.
Width
An integer value dictating the horizontal size of the Browse Page’s data page. This value is inherently measured in number of pixels, and the default value is 800.
How do I get the Width of a Browse Page’s data page
Using C#:
var width = pageDefinition.Width;
Via VBScript:
optionValue = control.Options.Item("Width")
How do I set the Width of a Browse Page’s data page
Using C#:
pageDefinition.Width = 800;
Via VBScript:
control.Options.Item("Width") = "800"
The page definition (for Managed Code) is retrieved as described in the section How do I access the page definition in Managed Code, and the Browse Page (in the case of VBScript) as described in the section Reference a Browse Page.
Obsolete
Popup
A Boolean value indicating whether the Browse Page’s data page should be displayed inline or in a new window.
Scrollbars
A Boolean value indicating whether the Browse Page’s data page should have scrollbars.
Behavior
Column
An integer value that specifies in which column the Browse Page object 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 indexes of the grouped objects. A column number of 0 indicates that the un-grouped Browse Page object 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 Browse Page 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 Browse Page object
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 Browse Page object
Using C#:
using FlowCentric.Engine.Entities.Classic;
//...
WebExtensions.SetColumnNumber(control, columnNumber);
// or
control.SetColumnNumber(columnNumber);
Via VBScript:
control.ColumnNo = 0
In both cases the Browse Page object is referenced as described in the sections Reference a Browse Control and Reference a Browse Page for Managed Code and VBScript, respectively.
Type
The type associated with the Browse Page object; this value is typically set on dragging-and-dropping a specific object.
How do I get the Type of a Browse Page object
Using Managed Code:
The type of a control in Managed Code is implicit (based on the control hierarchy), and in the case of a Browse Page the target control type is either BrowseControl or BrowseColumnControl depending on whether it is grouped.
Via VBScript:
controlType = control.Type
Where the Browse Page object is referenced as described in the sections Reference a Browse Control and Reference a Browse Page for Managed Code and VBScript, respectively.
Business Intelligence
BI Node
A Boolean value indicating whether the values of the Browse Page object 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 Browse Page 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.
Content Definition
Dynamic Value
The VBScript script to be executed at runtime as associated with the Browse Page object.
Control
Required Field
A Boolean value indicating whether the Browse Page object 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 Browse Page object
Using C#:
var required = control.IsRequired;
Via VBScript:
isRequired = control.Required
How do I set the Required Field value of a Browse Page object
Using C#:
control.IsRequired = false;
Via VBScript:
control.Required = False
Caution
Setting this value to True when the Browse Page object is hidden will prevent the associated activity from submitting.
In both cases the Browse Page object is referenced as described in the sections Reference a Browse Control and Reference a Browse Page for Managed Code and VBScript, respectively.
Identification
ID
Displays the (read-only) numeric identifier of the Browse Page.
How do I get the ID of a Browse Page object
Using C#:
var id = control.Id;
Via VBScript:
id = control.ID
Where the Browse Page object is referenced as described in the sections Reference a Browse Control and Reference a Browse Page for Managed Code and VBScript, respectively.
Parent
Displays the (read-only) numeric identifier of the activity containing (or parenting) the Browse Page object.
How do I get the ID of a Browse Page object’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 Browse Page object 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 Browse Page object 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 Browse Page.
Note
Neither the ID nor the name of the Object Group can be changed.
Name
The unique (per activity) name of the Browse Page object 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 Browse Page object
Using C#:
var name = control.Name;
Via VBScript:
name = control.Name
Where the Browse Page object is referenced as described in the sections Reference a Browse Control and Reference a Browse Page 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 Browse Page object 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 Browse Page object
Using C#:
var caption = control.Caption.Text;
Via VBScript:
caption = control.DisplayName
How do I set the Caption of a Browse Page object
Using C#:
control.Caption.Text = "Control Caption";
Via VBScript:
control.DisplayName = "Object Caption"
Where the Browse Page object is referenced as described in the sections Reference a Browse Control and Reference a Browse Page for Managed Code and VBScript, respectively.
Tooltip Text
An optional narrative to be displayed by supporting clients to further describe the Browse Page object, its expected value and/or its intent in the activity.
How do I get the Tooltip Text of a Browse Page object
Using C#:
toolTipText = control.ToolTip.Text;
Via VBScript:
toolTipText = control.Description
How do I set the Tooltip Text of a Browse Page object
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 Browse Page object is referenced as described in the sections Reference a Browse Control and Reference a Browse Page for Managed Code and VBScript, respectively.
Index
A unique (per activity) integer value that, firstly orders the script execution of the current Browse Page object 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 Browse Page object
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 Browse Page object
using FlowCentric.Engine.Entities.Classic;
//...
Extensions.SetIndex(control, 130);
// or
control.SetIndex(130);
Via VBScript:
control.Index = 130
Where the Browse Page object is referenced as described in the sections Reference a Browse Control and Reference a Browse Page 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 Browse Pages, is shown here:
Reference a Browse Page 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 Browse Page from within a sub-TaskForm is accomplished with
var control = base.GetControl<BrowsePageControl)("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 Browse Page from within a sub-ColumnsGroup is accomplished with
var control = base.GetControl<BrowsePageColumnControl)("NameOfGroupedControl");
Retrieve the value of a Browse Page 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 value for some specific, valid, and 0-based row number, as in:
// Get the value at the specified 0-based row:
textValue = BrowsePageControlExtensions.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 Browse Page Control
a) To set the value of a normal/un-grouped control, simply access it's Text property, as in:
control.Text = "Some Value";
b) To set the value of a grouped control, or column control, simply access it's Text value for some specific, valid, and 0-based row number, as in:
BrowsePageControlExtensions.SetText(control, rowNumber, "Some Value");
// or, simply:
control.SetText(rowNumber, "Some Value");
In both cases above, the specific control is retrieved as is illustrated in a preceding section.
Provide the Data Page Content
The FlowCentric.Engine.Managed.TaskForm provides, as one of its life-cycle related methods, the method with the following signature:
protected virtual System.Threading.Tasks.Task<DataPage> GetDataAsync(
FormDataContext context,
System.Threading.CancellationToken cancellationToken);
and in VB.NET
Protected Overridable Function GetDataAsync(
context As FormDataContext,
cancellationToken As System.Threading.CancellationToken)
As System.Threading.Tasks.Task(Of DataPage)
The FormDataContext-based context instance specifies the name of the Browse Page Control for which data is to be retrieved, together with an optional row number in case the specific control is grouped, with a DataQuery instance shaping the expected data - all of which are typically requested by a client. The FormContextExtensions and FormContextClassicExtensions adds as extension methods the functionality required to build the resulting DataPage instances.
A typical implementation of this method typically looks as follows (assuming multiple Browse Page Controls):
/// <inheritdoc />
protected override async Tasks.Task<DataPage> GetDataAsync(
FormDataContext context,
CancellationToken cancellationToken)
{
...
DataPage dataPage = null;
switch (context.ControlName)
{
case ... // One or more control names specified using the generated
// Fields and Groups classes.
dataPage = await context.GetDataPageAsync(
..., // Scenario specific parameters
cancellationToken);
break;
...
default:
// Results in an empty Data Page.
dataPage = await base.GetDataAsync(context, cancellationToken);
break;
}
return dataPage;
}
and in VB.NET
'''<inheritdoc/>
Protected Overrides Async Function GetDataAsync(
context As FormDataContext,
cancellationToken As CancellationToken) As Tasks.Task(Of DataPage)
...
Dim dataPage As DataPage = Nothing
Select context.ControlName
Case ... ' One or more control names specified using the generated
' Fields and Groups classes.
dataPage = Await context.GetDataPageAsync(
..., ' Scenario specific parameters
cancellationToken)
Exit Select
...
Case Else
' Results in an empty Data Page.
dataPage = Await GetDataAsync(context, cancellationToken)
Exit Select
End Select
Return dataPage
End Function
The remainder of this section introduces the scenarios enabled via the extension methods.
Backward and designer compatible content provision
The simplest possible implementation falls back to the Browse Page Definition specified in the designer, in which case all but the Data Source is evaluated by the engine. To use this approach, the implementation would look similar to the following:
...
DataPage dataPage = null;
switch (context.ControlName)
{
case ... // One or more control names specified using the generated
// Fields class.
dataPage = await context.GetDataPageAsync(
browsePageControl,
oleDbConnectionString,
cancellationToken);
break;
case ... // One or more control names specified using the generated
// Groups class.
dataPage = await context.GetDataPageAsync(
ColumnsGroup.BrowsePageControl,
oleDbConnectionString,
cancellationToken);
break;
...
}
return dataPage;
}
In VB.NET
...
Dim dataPage As DataPage = Nothing
Select context.ControlName
Case ... ' One or more control names specified using the generated
' Fields class.
dataPage = Await context.GetDataPageAsync(
browsePageControl,
oleDbConnectionString,
cancellationToken)
Exit Select
Case ... ' One or more control names specified using the generated
' Groups class.
dataPage = Await context.GetDataPageAsync(
ColumnsGroup.BrowsePageControl,
oleDbConnectionString,
cancellationToken)
Exit Select
...
End Select
Return dataPage
The first case handles one or more normal/un-grouped Browse Page Controls, and the second handles one ore more grouped Browse Page Controls. The OLEDB connection string can be retrieved from custom settings, as is available on the context instance.
Classic content provision
The second implementation still requires the engine to execute database-related functionality, by specifying OLEDB-specific connection and query strings to the FormContextClassicExtensions method with the following signature:
public static System.Threading.Tasks.Task<DataPage> GetDataPageAsync(
this FormDataContext context, // Extension method
string oleDbConnectionString,
string dataQuery, // SELECT or EXEC[UTE]...
string primaryKeyColumn, // null for Simple/Normal Browse Pages.
string countQuery, // null for Simple/Normal Browse Pages.
string whereClauses, // ignored for Simple/Normal Browse Pages.
string orderByClauses, // ignored for Simple/Normal Browse Pages.
System.Threading.CancellationToken cancellationToken);
<Extension>
Public Shared Function GetDataPageAsync(
context As FormDataContext,
oleDbConnectionString As String,
dataQuery As String, ' SELECT or EXEC[UTE]...
primaryKeyColumn As String, ' Nothing for Simple/Normal Browse Pages.
countQuery As String, ' Nothing for Simple/Normal Browse Pages.
whereClauses As String, ' ignored for Simple/Normal Browse Pages.
orderByClauses As String, ' ignored for Simple/Normal Browse Pages.
cancellationToken As System.Threading.CancellationToken)
As System.Threading.Tasks.Task(Of DataPage)
Using this approach differs from that of the previous section in that none of the properties set for the Browse Page Definition specified in the designer is used. It is still possible to specify custom settings as parameters, that are maintained via the designer.
Managed Code and modern content provisioning
One of the many benefits enabled via Managed Code includes the use of any Microsoft.NET related framework or library, including ADO.NET. The DataSet and DataTable types in the System.Data namespace, can be used to specify the content of a resulting data page, calling one of the appropriate FormContextExtensions methods:
public static System.Threading.Tasks.Task<DataPage> GetDataPageAsync(
this FormDataContext context,
DataSet dataSet,
System.Threading.CancellationToken cancellationToken);
public static System.Threading.Tasks.Task<DataPage> GetDataPageAsync(
this FormDataContext context,
DataTable dataTable,
System.Threading.CancellationToken cancellationToken);
<Extension>
Public Shared Function GetDataPageAsync(
context As FormDataContext,
dataSet As System.Data.DataSet,
cancellationToken As System.Threading.CancellationToken)
As System.Threading.Tasks.Task(Of DataPage)
<Extension>
Public Shared Function GetDataPageAsync(
context As FormDataContext,
dataTable As System.Data.DataTable,
cancellationToken As System.Threading.CancellationToken)
As System.Threading.Tasks.Task(Of DataPage)
Finally, the interface FlowCentric.Engine.Extensibility.IDataPageProvider (with base implementation, DataPageProvider in the same namespace) located in the FlowCentric.Engine.Contracts assembly, defines the final extension point in providing content for Browse Page Controls - with an instance of this type provided to the FormContextExtensions method with signature:
public static System.Threading.Tasks.Task<DataPage> GetDataPageAsync(
this FormDataContext context,
IDataPageProvider dataPageProvider,
System.Threading.CancellationToken cancellationToken);
<Extension>
Public Shared Function GetDataPageAsync(
context As FormDataContext,
dataPageProvider As Extensibility.IDataPageProvider,
cancellationToken As System.Threading.CancellationToken)
As System.Threading.Tasks.Task(Of DataPage)
See the article on the Custom Browse Page Data Provider for more details pertaining to this final provisioning mechanism.
How do I (in VBScript)
Reference a Browse Page
To reference a Browse Page that is not grouped (that is, belongs to the default Object Group), follow the hierarchy: current activity -> default Object Group -> Browse Page, 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 Browse Page to be referenced is grouped, the hierarchy changes slightly to take the (actual) Object Group into consideration: current activity -> specific Object Group -> Browse Page, 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 Browse Page (the source object)
From within the Browse Page’s Dynamic Value
a) The simplest way to access the value of a Browse Page 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 Browse Page (any object for that matter, when it is on the same activity) is to first reference the object (as described in the section Reference a Browse Page). Retrieving the value in the resulting object depends, again, on whether it is:
an un-grouped 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 Browse Page is not grouped, use either options from the preceding section (From within the Browse Page’s Dynamic Value) irrespective of the grouping of the target object.
b) When the source Browse Page 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 Browse Page’s Dynamic Value)
grouped in another Object Group and all the values of the grouped source Browse Page 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 same (source) Browse Page’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 Browse Page’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 Browse Page is not grouped, access its value using the first option (aObjects) from the preceding section (From within the Browse Page’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 of a Browse Page
Directly (grouped and un-grouped Browse Pages)
To set the text value of a Browse Page, one assigns the value to the fcLabel contextual keyword in the Dynamic Value of the object, as can be seen here:
fcLabel = "This is the Browse Page’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 value of a Browse Page on the Dynamic Value of another (whether grouped or ungrouped) object, one first needs a reference to the Browse Page (see Reference a Browse Page). Changing the text value on an ungrouped Browse Page is equivalent to changing the value on the first line number (0-based) of an actual grouped Browse Page, as shown here:
control.Item(0, False) = "Value set from another object"
To change any of the values in a grouped Browse Page other than on the first line, replace the 0 with the appropriate line number (keeping in mind 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 Browse Page’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.
Specify the data for Browse Pages
SQL Queries
The simplest technique to provide data for the data page(s) of a Browse Page is by specifying direct SQL SELECT statements with the select list (column names or aliases) mapping to Sources on associated Browse Objects.
Important
The SQL dialect depends on the data store backing the configured Data Source). The fcConn VBScript string variable must be initialized with an OLEDB-based connection string.
Normal Browse Pages
As the Normal Browse Pages only have a single Query field, the default filtering (WHERE clauses) and ordering (ORDER BY clauses), when applicable, need to be specified with the query. Any paging, and further filtering and ordering is performed by the engine over the results that will be produced by this base query. This is mainly performed in memory by the engine, making the normal Browse Pages very inefficient where the base query returns huge result sets.
Advanced Browse Pages
The Advanced Browse Pages includes several query-related properties to augment the base Query, as well as, and including, the equally important CountQuery. These include the WhereClause to filter both base and count query, OrderBy indicating the primary ordering and the PrimaryKeyColumn designating a unique column (and default ordering if not explicitly specified) in the result set.
When a client requests a specific data page, the total number of entries is calculated first by amending the CountQuery with the (optional) WhereClause and any filters requested by the client. The specific data page is then calculated based on this result and the configured Page size, executing for this page, the Query amended with the (optional) WhereClause and client filters, ordered by the (optional) OrderBy (or PrimaryKeyColumn) and any ordering requested by the client.
Stored Procedures
The data pages for Browse Pages can be populated using Stored Procedures, by prefixing the procedure name with the text value, "EXEC ". The execution and population is equivalent to simply specifying SQL Queries on Normal Browse Pages (even though the PrimaryKeyColumn needs to be specified on Advanced Browse Pages).
fcBrowseDataSource
The fcBrowseDataSource VBScript variable, available on the Data Source of Browse Pages, can be used in place of the fcConn-Query pair to directly provide the data for a data page as Microsoft.NET DataSet or DataTable (from the System.Data namespace).
Property Compatibility Matrix
The following details the client support for the properties of Browse Pages
