Environment Variables
Architecture
Page instance “Environment variables” are stored per page instance. One or more (variable-value) pair can be set programmatically in the config for a page instance. Most importantly, (variable-value) pairs are automatically passed from one page to another when clicked on Details icon or a linked page hyperlink is clicked. The (Menu Parameter Name/Field Name - Field value) will be the environment(variable-value) pair for the landing page instance.
The following example illustrates the flow of (variable-value) from one page to another.
Purpose
The page variables defined will be used as request parameters, when explicit request parameters are not supplied. This will also be used as field Default values, overriding fixed Default values and computed Default values.
This can be also used as Breadcrumbs of the page flow, and can be used for breadcrumb navigation, which is essential for a large website like ours. The breadcrumb (variable-value) will be determined automatically based on if the field is a primary key.
All custom code related to setting a field value with JavaScript page variables can be eliminated.
Entity Events for handling Environment Variables
A "GroupEntityEvent": "33554432" (SetEnvironment), is available to set, delete, read Environment variables for a Page instance. The following json sample sets a single environment (value-pair) = (AddressTypeId, 10).
{
"LanguageCode": "en-US",
"PageId": 46586357628380,
"PageName": "Modules/Setup/Types/AddressType.html",
"MenuId": 497,
"PageEnvironment": {
"PageEnvironmentOperation": 0,
"PageEnvironmentFieldValues": [
{
"FieldName": "AddressTypeId",
"FieldValue": 10
}
]
},
"GroupEntityEvent": "33554432",
"IsDisconnected": false
}
Four different “PageEnvironmentOperation” are available.
- Set: 0 – Sets one or more environmental fields for the instance
- Delete: 1 – Removes a list of specified environmental fields available for the instance.
- DeleteAll: 2 – Remove all environmental fields available for the instance
- Read: 3 - Reads the previously set environment fields, for a page instance. Returns a List<PageEnvironmentFieldValue>
The above Event is fully implemented and tested, as of writing this document.
Examples in AdventureWorks
Entities – AdventureWorks Entities
Url - https://web1.mclsystems.com/AWv32/#/Home
Menu Path – HumanResources -> New Employee ->New Department
In that page, “New Department(Environment 1)” grid has command button(which created using Related pages. see more about Related Pages with its properties and Examples), when click that details button in “New Department”, page will redirect to “Child Department(Environment 2)” page.
Goal
Based on the selected department from “New Department” page, Child Department must be shown, that should be done with Environment Variables concept.
Steps to do:
a) Create the Related page “Child Department” for the menu “New Department” to make details button in grid’s row.
b) After created related page under “New Department”, details button will be shown in grid’s row as below
c)Add the related page parameter “DepartmentID” for “Child Department”.
Clicking on Details button in New Department (Environment 1) page will set DepartmentID in Child Department (Environment 2)
You can check Environment details in every tab, you will find “Show Current Tab’s Debug Info”. If you open it will see what environment variables are passed.
What config need to set in Html page?
We don’t want to use any custom codes to use environment values as request parameter. autoProcessDefaultValuesFromContainer: true, this property is enough to set in page config.
This config only works, when Environment variable name should be same as Request Parameter Name.In our case Environment variable is “DepartmentID” and the read method(ChildDepartmentRead) request table(ChildDepartmentRequest) has “DepartmentID” field so this should be working fine as expected.
With the *SEARCH* control, it sets the implicit filter for the grid attached to the search control. Below codes used for search config
$("#ChildDepartmentPanel").MCL_DemandAccordion({
controlName: "ChildDepartmentPanel",
groupEntity: groupEntity,
items: [{
controlName: "ChildDepartmentPane",
title: "Child Department",
expanded: true,
items: [{
groupEntity: groupEntity,
itemType: MCL.Controls.ItemType.Search,
controlName: "ChildDepartment_Search",
entityName: "ChildDepartment",
methodName: "ChildDepartmentRead",
tableName: "ChildDepartment",
targetControls: "ChildDepartment_grid",
autoProcessDefaultValuesFromContainer: true, /// this property has to add
},
After you set property autoProcessDefaultValuesFromContainer: true in search config you can see that in “Show Current Tab’s Debug Info” ,it will show how “ChildDepartmentRead” method is called, with request parameter “DepartmentID”
The way we currently process Default value is
a) Get the static DefaultValue
b) If the container already has a value for the field, override it with the container value
c) If there is a DefaultValueComputed, override the previous DefaultValue.
With the *FORM*, it populates Default values with Environment value. This config only works when Environment variable name should be same as Field name that would be set Default value. Below codes used in form config,
formConfig: {
controlName: "ChildDepartment_form",
CreateAutoGnerateGroup: true,
autoProcessDefaultValuesFromContainer: true, // this property has to add
items: [{
itemType: MCL.Controls.ItemType.AutoGenerate, colCount: [1, 1, 1, 1], itemcolCount: [1, 1, 2, 2], title: "Child Department",
}]
},
After set the property autoProcessDefaultValuesFromContainer: true in form config Default value will be shown in Department Id field in form, you will see that Default value with clicking the “Add new Record” button in form.