Custom buttons are displayed on the toolbar and are used for manual execution of Fore units or JavaScript functions, opening repository objects or starting calculation algorithms.
Available operations:
Custom button settings can be determined on the corresponding tabs of the Custom Button Settings dialog box.
Determine general settings for a button:
Button Name. Enter custom button name. The default name: Custom button N, where N is button number.
Button Icon. Set button icon that will be displayed on the toolbar. To do this, click the Load Icon button and select image in the dialog box that opens. Supported image formats: SVG, PNG, JPG, BMP and GIF. The default button icon is .
NOTE. It is recommended to use images with the size 16x16 pixels as button icons. If image size is large than 16x16 pixels, it is automatically resized to fit the recommended size.
To reset the specified image and set the default icon, click the Reset Icon button.
Select the button type in the Select Type drop-down list.
Set up repository object opening
When the Open Repository Object type is selected, determine additional settings:
Open Repository Object. In the drop-down list select the repository object to be opened on button click:
NOTE. The object used in a custom button is included in the hierarchy of objects, of which the report consists. To view the report object hierarchy, use the Consists Of tab of the Object Properties dialog box in the object navigator.
Unit. If required, select the Fore unit in the drop-down list. The unit can be used for prehandler, posthandler, for managing button activity, which can be set up on the Advanced tab. A single unit can be set for a button.
Select the checkbox if required:
Open in Modal Window. The checkbox is deselected by default. If the checkbox is selected, parent report work is locked during opening the object.
Update after Window Closing. The switch becomes active after the Open in Modal Window checkbox is selected. In the drop-down list select the sheets to be updated after closing the object.
NOTE. Saving data in the opened modal dialog window is mandatory for updating sheets after closing the object.
Set parameters for objects with parameters:
Setting Method. In the drop-down list select:
Do not Send. Default value. Nothing is sent to parameter on object opening.
Object Parameter. Report parameter or data entry form parameter is sent to parameter on object opening.
Dimension Attribute. Value of the first element attribute or all elements of the selected dimension from the selected table area is sent to parameter on object opening.
Manually. The specified value is sent to parameter on object opening.
Value. Box contents depends on the selected value transfer method:
If the Do not Send value transfer method is selected, the box is disabled.
If the Object Parameter value transfer method is selected, select the parameter in the drop-down list. The list displays available report parameters. The list of report parameters is filtered by object parameter type. Only one parameter can be selected.
If the Dimension Attribute value transfer method was selected, select the attribute in the drop-down list. The list displays all available attributes of all dimensions of all report table areas. Only one attribute can be selected.
If the Manually value transfer method was selected, the Value box displays the editor corresponding to parameter type. Only one element can be selected.
Selection Type. The drop-down list is available if the Dimension Attribute value transfer method was selected. In the drop-down list select:
First Element. The selected attribute of the first dimension element from selection is sent to the parameter.
All Elements. Values of the selected attribute of all dimension elements from selection are sent to the parameter.
If a web form opens on custom button click, an active regular report is registered in the system within the custom session. The active report is returned by the PrxReport.ActiveReport static property available in the Fore language. If several web forms are used that were opened from different reports, the active report within the session will be considered the one, from which the web form was last called and until its closing.
If there are several simultaneously opened regular reports and web forms, the PrxReport.ActiveReport property can wok incorrectly because it will return the last report, from which the web form was opened. The active report can be changed using the SetActiveReport operation.
To work with a report from web form, it is recommended to save the active report to the global variable declared on the web form class level. The active report should be written to the variable in the onShow event:
Class TESTWebForm: WebForm
activeRep: IPrxReport;
activeSheet: IPrxSheet;
Sub TESTWebFormOnShow;
Begin
activeRep := PrxReport.ActiveReport;
activeSheet := activeRep.ActiveSheet;
// Further work with report
End Sub TESTWebFormOnShow;
End Class TESTWebForm;
If the Algorithm Calculation type is selected, determine additional settings:
Select Executable Object. In the drop-down list select the calculation algorithm to be executed on button click:
NOTE. The calculation algorithm used in a custom button is included in the hierarchy of objects, of which the report consists. To view report object hierarchy, use the Consists Of tab of the Object Properties dialog box in the object navigator.
Unit. If required, select the Fore unit in the drop-down list. The unit can be used for prehandler, posthandler, for managing button activity, which can be set up on the Advanced tab. A single unit can be set for a button.
Set parameters for calculation algorithms with parameters:
Value Type. Specify values used on algorithm calculation.
Object Parameter. Calculation uses object parameter value.
Constant Value. Constant value is used in calculation.
Selection Type. Depending on the selected value type:
If the Object Parameter type is set, select selection type in the drop-down list. Available values: Source, First Element, Last Element, Source+Child, Source+Child (recursive), Child, Child (recursive).
If the Constant Value type is set, selection type is unavailable.
Dictionary Schema. Select in the drop-down list selection schema of the dictionary used as an algorithm parameter. If selection schema is not set up for the dictionary, the list is empty.
NOTE. Dictionary selection schema has a higher priority than selection type.
Value. Depending on the selected value type:
If the Object Parameter type is set, select report parameter or report parameter attribute in the drop-down list.
If the Constant Value type is selected, set value of constant.
If the Fore/JS Function Unit type is selected, determine additional settings:
Unit. Select a Fore unit in the drop-down list. Only one unit can be set for a button.
Unit Method/Function. Select unit method or function in the drop-down list. The function should have the required signature:
Public Sub <Function name>(<Report>: IPrxReport);
Begin
…
End Sub <Function name>;
Parameter:
Report. A regular report in the IPrxReport format is sent to the parameter. When working with this object, all properties and methods of the IPrxReport interface are available.
NOTE. If the unit does not contain methods and functions satisfying the required signature, the Unit Method/Function box is disabled.
JS-Function. Specify function name in the JavaScript language that should be started after the button action is executed. The signature to enter function name:
javascript:<Function name (custom parameters, callback, args)>
NOTE. Using angle brackets when specifying function name with parameters is mandatory.
Parameters:
custom parameters. Custom button values according to the signatures of the called function. Optional parameter.
callback. Callback function. Mandatory parameter.
args. Function arguments generated by the platform. Optional parameter that allows for getting access to the object, from which JS function was executed.
The examples of specifying function name:
javascript:<Test(callback)> - simple JS function call without sending parameters to it.
javascript:<CalculateAB(100, "200", callback)> - JS function call with sending two values of different types.
javascript:<Check(callback, args)> - JS function call with the ability to access the object, from which the function was called.
If JS-function and Fore function are specified, Fore function is executed first, then JS-function.
To call the JS function, one should connect the function, in which the function is implemented, in the externalJs field in the config.json field, for example:
"externalJs": [
{"src": "./assets/js/calculate.js"},
{"src": "./assets/js/settings.js"}
]
The web application contain various resources that can be used in JS function code.
The args parameter has the moduleId field, which returns unique identifier of the opened object instance, from which the JS function is called. This identifier is used by the Platform.Managers object methods described below.
Platform.Bi - object containing methods for interaction with BI server by means of JSON queries. The list of methods and their signatures:
execMethod('Repository ID', 'Assembly ID', 'Method', ['Parameter 1','Parameter 2',…]) - to execute queries by means of the ForeExec file.
sendRequest({parameters}, Json query 1, Json query 2,…) - to execute a batch of JSON queries. Each query executes one of the available operations of BI server. As parameters of the current implementation, one can specify the batched: boolean parameter, which determines whether the specified queries should be executed as a batch.
putBin('moniker', FormData) - to upload an image to a document by means of the PutBin operation.
getBin('moniker', indicates whether 'file name' is downloaded) - to get an image from a document by means of the GetBin operation.
Platform.Notification - object containing methods for displaying notifications in the platform style. The list of methods and their signatures:
error('Title', 'Text'). Display error message.
warning('Title', 'Text'). Display warning.
success('Title', 'Text'). Display success message.
info('Title', 'Text'). Display information message.
Platform.Managers - object that allows access to opened repository objects, from which JS functions are called. In the current implementation, this object has the Prx and DataEntryForm objects, which allow access to a regular report and a data entry form. To get access to an object instance, from which JS function is called, send the moduleId unique identifier to the designer of specified objects. Each object has two fields:
selectors. It contains selectors for getting information about opened object:
name() - object name.
key() - object key.
id() - object identifier.
openId(): - moniker of opened object instance.
actions. It contains the refresh() method for refreshing an opened object.
The examples of functions:
// Display various notifications
async function showNotifications(callback) {
Platform.Notification.error('Error', Error saving data. Invalid value type.');
Platform.Notification.warning('Warning', 'Calculation may take a long time.');
Platform.Notification.success('Successful', Calculation is finished.');
Platform.Notification.info('Information', 'A new report version is available.');
callback();
}
// Refresh regular report
async function refreshPrx(callback, args) {
const { moduleId } = args;
const refresh = Platform.Managers.Prx(moduleId).actions.refresh();
callback();
}
// Send JSON query
async function closeControlPanel(callback, args) {
const { moduleId } = args;
const openId = Platform.Managers.Prx(moduleId).selectors.openId();
const closeControlPanel = {
request: {
SetPrxMeta: {
mon: openId,
tArg: {
meta: {
options: {
controlPanelVisible: false,
},
},
},
},
},
handleResult: (response) => response?.SetPrxMetaResult,
};
const response = await Platform.Bi.sendRequest({}, closeControlPanel);
callback();
}
// Batch query execution
async function batchRequests(callback, args) {
// Queries
const request1 = {
request: {
// First query
},
};
const request2 = {
request: {
// Second query
},
},
};
const response = await Platform.Bi.sendRequest({batched: true}, request1, request2);
callback();
}
// Call method in repository assembly
async function saveDataChanges(callback, args) {
const { moduleId } = args;
const openId = Platform.Managers.Prx(moduleId).selectors.openId();
await Platform.Bi.execMethod(
'TEST_REPO',
'ASM_CALC',
'CalculateAB',
[100, 200],
);
callback();
}
After a Fore unit is set, set up prehandler, posthandler and button activity management.
The prehandler is used to display a text message with a custom text on custom button click. For example, a prehandler can be set up for a button, which starts calculation, with a message warning that calculation may take long time. In this case, clicking the button before the calculation displays the configured message.
To set up prehandler, set the parameters:
Unit Method/Function. Select unit method or function in the drop-down list. The box is available only after the unit is selected.
The list contains all methods and functions of the selected unit corresponding to the signature:
Function <Function name> (<Report>: IPrxReport; [Var messageType: Integer]): String;
NOTE. If the unit does not contain methods and functions satisfying the required signature, the Unit Method/Function box is disabled.
Parameters:
Report. A regular report in the IPrxReport is sent to the parameter. When working with this object, all properties and methods of the IPrxReport interface are available.
messageType. Optional parameter. It is used to determine displayed message format. If the parameter is not set, a confirmation dialog box is used. To hide the displayed message, remove the returned value to Return. Available values:
0. Confirmation dialog box. Clicking the Yes button in the dialog box executes the specified button action. Clicking the No button in the dialog box cancels execution of the specified button action.
1. Error. Clicking the OK button in the dialog box does not execute the specified button action.
2. Warning. Clicking the OK button in the dialog box does not execute the specified button action.
3. Information message. Clicking the OK button in the dialog box does not execute the specified button action.
The example of function:
Function MessageInformationBox(Report: IPrxReport; Var messageType: integer): String;
Begin
messageType := 3;
Return "Operation will be available when all data will be entered";
End Function MessageInformationBox;
JS-Function. Specify function name in the JavaScript language that should be started after the button action is executed. The signature to enter function name:
javascript:<Function name (custom parameters, callback, args)>
NOTE. Using angle brackets when specifying function name with parameters is mandatory.
Parameters:
custom parameters. Custom button values according to the signatures of the called function. Optional parameter.
callback. Callback function. Mandatory parameter.
args. Function arguments generated by the platform. Optional parameter that allows for getting access to the object, from which JS function was executed.
The examples of specifying function name:
javascript:<Test(callback)> - simple JS function call without sending parameters to it.
javascript:<CalculateAB(100, "200", callback)> - JS function call with sending two values of different types.
javascript:<Check(callback, args)> - JS function call with the ability to access the object, from which the function was called.
If JS-function and Fore function are specified, Fore function is executed first, then JS-function.
To call the JS function, one should connect the function, in which the function is implemented, in the externalJs field in the config.json field, for example:
"externalJs": [
{"src": "./assets/js/calculate.js"},
{"src": "./assets/js/settings.js"}
]
The web application contain various resources that can be used in JS function code.
The args parameter has the moduleId field, which returns unique identifier of the opened object instance, from which the JS function is called. This identifier is used by the Platform.Managers object methods described below.
Platform.Bi - object containing methods for interaction with BI server by means of JSON queries. The list of methods and their signatures:
execMethod('Repository ID', 'Assembly ID', 'Method', ['Parameter 1','Parameter 2',…]) - to execute queries by means of the ForeExec file.
sendRequest({parameters}, Json query 1, Json query 2,…) - to execute a batch of JSON queries. Each query executes one of the available operations of BI server. As parameters of the current implementation, one can specify the batched: boolean parameter, which determines whether the specified queries should be executed as a batch.
putBin('moniker', FormData) - to upload an image to a document by means of the PutBin operation.
getBin('moniker', indicates whether 'file name' is downloaded) - to get an image from a document by means of the GetBin operation.
Platform.Notification - object containing methods for displaying notifications in the platform style. The list of methods and their signatures:
error('Title', 'Text'). Display error message.
warning('Title', 'Text'). Display warning.
success('Title', 'Text'). Display success message.
info('Title', 'Text'). Display information message.
Platform.Managers - object that allows access to opened repository objects, from which JS functions are called. In the current implementation, this object has the Prx and DataEntryForm objects, which allow access to a regular report and a data entry form. To get access to an object instance, from which JS function is called, send the moduleId unique identifier to the designer of specified objects. Each object has two fields:
selectors. It contains selectors for getting information about opened object:
name() - object name.
key() - object key.
id() - object identifier.
openId(): - moniker of opened object instance.
actions. It contains the refresh() method for refreshing an opened object.
The examples of functions:
// Display various notifications
async function showNotifications(callback) {
Platform.Notification.error('Error', Error saving data. Invalid value type.');
Platform.Notification.warning('Warning', 'Calculation may take a long time.');
Platform.Notification.success('Successful', Calculation is finished.');
Platform.Notification.info('Information', 'A new report version is available.');
callback();
}
// Refresh regular report
async function refreshPrx(callback, args) {
const { moduleId } = args;
const refresh = Platform.Managers.Prx(moduleId).actions.refresh();
callback();
}
// Send JSON query
async function closeControlPanel(callback, args) {
const { moduleId } = args;
const openId = Platform.Managers.Prx(moduleId).selectors.openId();
const closeControlPanel = {
request: {
SetPrxMeta: {
mon: openId,
tArg: {
meta: {
options: {
controlPanelVisible: false,
},
},
},
},
},
handleResult: (response) => response?.SetPrxMetaResult,
};
const response = await Platform.Bi.sendRequest({}, closeControlPanel);
callback();
}
// Batch query execution
async function batchRequests(callback, args) {
// Queries
const request1 = {
request: {
// First query
},
};
const request2 = {
request: {
// Second query
},
},
};
const response = await Platform.Bi.sendRequest({batched: true}, request1, request2);
callback();
}
// Call method in repository assembly
async function saveDataChanges(callback, args) {
const { moduleId } = args;
const openId = Platform.Managers.Prx(moduleId).selectors.openId();
await Platform.Bi.execMethod(
'TEST_REPO',
'ASM_CALC',
'CalculateAB',
[100, 200],
);
callback();
}
The posthandler is used to execute required operations after finishing method work A single posthandler can be set.
To set up a posthandler, set the parameters:
Unit Method/Function. Select unit method or function in the drop-down list. The box is available only after the unit is selected.
The list contains all methods and functions of the selected unit corresponding to the signature:
Sub <Method name>(<Report>: IPrxReport);
NOTE. If the unit does not contain methods and functions satisfying the required signature, the Unit Method/Function box is disabled.
Parameter:
Report. A regular report in the IPrxReport is sent to the parameter. When working with this object, all properties and methods of the IPrxReport interface are available.
The example of function:
Sub UpdateData(Report: IPrxReport);
Var
SheetT: IPrxTable;
ItemIndex: Integer;
Begin
ItemIndex := Report.ActiveSheet.Index;
SheetT := Report.Sheets.Item(ItemIndex) As IPrxTable;
SheetT.TabSheet.CellValue(10,10) := 1000000;
End Sub UpdateData;
JS-Function. Specify function name in the JavaScript language that should be started after the button action is executed. The signature to enter function name:
javascript:<Function name (custom parameters, callback, args)>
NOTE. Using angle brackets when specifying function name with parameters is mandatory.
Parameters:
custom parameters. Custom button values according to the signatures of the called function. Optional parameter.
callback. Callback function. Mandatory parameter.
args. Function arguments generated by the platform. Optional parameter that allows for getting access to the object, from which JS function was executed.
The examples of specifying function name:
javascript:<Test(callback)> - simple JS function call without sending parameters to it.
javascript:<CalculateAB(100, "200", callback)> - JS function call with sending two values of different types.
javascript:<Check(callback, args)> - JS function call with the ability to access the object, from which the function was called.
If JS-function and Fore function are specified, Fore function is executed first, then JS-function.
To call the JS function, one should connect the function, in which the function is implemented, in the externalJs field in the config.json field, for example:
"externalJs": [
{"src": "./assets/js/calculate.js"},
{"src": "./assets/js/settings.js"}
]
The web application contain various resources that can be used in JS function code.
The args parameter has the moduleId field, which returns unique identifier of the opened object instance, from which the JS function is called. This identifier is used by the Platform.Managers object methods described below.
Platform.Bi - object containing methods for interaction with BI server by means of JSON queries. The list of methods and their signatures:
execMethod('Repository ID', 'Assembly ID', 'Method', ['Parameter 1','Parameter 2',…]) - to execute queries by means of the ForeExec file.
sendRequest({parameters}, Json query 1, Json query 2,…) - to execute a batch of JSON queries. Each query executes one of the available operations of BI server. As parameters of the current implementation, one can specify the batched: boolean parameter, which determines whether the specified queries should be executed as a batch.
putBin('moniker', FormData) - to upload an image to a document by means of the PutBin operation.
getBin('moniker', indicates whether 'file name' is downloaded) - to get an image from a document by means of the GetBin operation.
Platform.Notification - object containing methods for displaying notifications in the platform style. The list of methods and their signatures:
error('Title', 'Text'). Display error message.
warning('Title', 'Text'). Display warning.
success('Title', 'Text'). Display success message.
info('Title', 'Text'). Display information message.
Platform.Managers - object that allows access to opened repository objects, from which JS functions are called. In the current implementation, this object has the Prx and DataEntryForm objects, which allow access to a regular report and a data entry form. To get access to an object instance, from which JS function is called, send the moduleId unique identifier to the designer of specified objects. Each object has two fields:
selectors. It contains selectors for getting information about opened object:
name() - object name.
key() - object key.
id() - object identifier.
openId(): - moniker of opened object instance.
actions. It contains the refresh() method for refreshing an opened object.
The examples of functions:
// Display various notifications
async function showNotifications(callback) {
Platform.Notification.error('Error', Error saving data. Invalid value type.');
Platform.Notification.warning('Warning', 'Calculation may take a long time.');
Platform.Notification.success('Successful', Calculation is finished.');
Platform.Notification.info('Information', 'A new report version is available.');
callback();
}
// Refresh regular report
async function refreshPrx(callback, args) {
const { moduleId } = args;
const refresh = Platform.Managers.Prx(moduleId).actions.refresh();
callback();
}
// Send JSON query
async function closeControlPanel(callback, args) {
const { moduleId } = args;
const openId = Platform.Managers.Prx(moduleId).selectors.openId();
const closeControlPanel = {
request: {
SetPrxMeta: {
mon: openId,
tArg: {
meta: {
options: {
controlPanelVisible: false,
},
},
},
},
},
handleResult: (response) => response?.SetPrxMetaResult,
};
const response = await Platform.Bi.sendRequest({}, closeControlPanel);
callback();
}
// Batch query execution
async function batchRequests(callback, args) {
// Queries
const request1 = {
request: {
// First query
},
};
const request2 = {
request: {
// Second query
},
},
};
const response = await Platform.Bi.sendRequest({batched: true}, request1, request2);
callback();
}
// Call method in repository assembly
async function saveDataChanges(callback, args) {
const { moduleId } = args;
const openId = Platform.Managers.Prx(moduleId).selectors.openId();
await Platform.Bi.execMethod(
'TEST_REPO',
'ASM_CALC',
'CalculateAB',
[100, 200],
);
callback();
}
Set up button activity management
To set up button activity management, set the Unit Method/Function parameter, in which select unit method or function in the drop-down list. The box is available only after the unit is selected.
The list contains all methods and functions of the selected unit corresponding to the signature:
Function <Function name>(<Report>: IPrxReport): Boolean;
NOTE. If the unit does not contain methods and functions satisfying the required signature, the Unit Method/Function list is disabled.
Parameter:
Report. A regular report in the IPrxReport format is sent to the parameter. When working with this object, all properties and methods of the IPrxReport interface.
Available values:
True. The button is active.
False. The button is inactive.
NOTE. The condition is checked permanently that is why Fore function should be executed quickly otherwise regular report will not work correctly.
See also: