Custom buttons are displayed on the toolbar and are used for manual execution of Fore units or JavaScript functions, opening repository objects and starting calculation algorithms.
Available operations:
Custom buttons can be set up using corresponding tabs in the Custom Button Settings dialog box.
Determine general button settings:
Button Name. Enter a custom button name. By default: Custom button N, where N - button number.
Custom button name can be saved in different languages depending on the current language selected in the login dialog box, or using the resource included in object. For details see the Setting Up Multilingual Options section.
Button Icon. Select a button icon that will be displayed on the toolbar. To do this, click the Load Icon button and select an image in the dialog box that opens. Available image formats: SVG, PNG, JPG, BMP and GIF. The icon is set for a button by default.
NOTE. It is recommended to use 16x16 pixels images as button icons. If the image is bigger than 16x16 pixels, it is automatically resized to fit the recommended size.
To reset the specified image and set a default icon, click the Reset Icon button.
Select 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. Select in the drop-down list the repository object that will open on button click:
NOTE. The object used in a custom button is included in the hierarchy of data entry form objects. To view the hierarchy of data entry form objects, use the Consists Of tab of the Object Properties window 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. Only one unit can be set for the button.
Select the checkbox if required:
Open in Modal Window. The checkbox is deselected by default. When the checkbox is selected, work with parent data entry form is locked during object opening.
Update After Dialog Box is Closed. The checkbox becomes available after the Open in Modal Window checkbox is selected. Select sheets that must be updated after object closing.
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 the parameter on opening the object.
Object Parameter. The data entry form or report parameter value is sent to the parameter on opening the object.
Dimension Attribute. Attribute value of the first element or of all elements of the selected dimension from selected area in the table is sent to parameter on opening the object.
Manually. The specified value is sent to the parameter on opening the object.
Value. The box contents depends on selected value sending method:
If the Do Not Send value sending method was selected, the box is unavailable.
If the Object Parameter value sending method was selected, select a parameter in the drop-down list. The list displays available data entry form parameters. The list of data entry form parameters is filtered by object parameter type. Only one parameter can be selected.
If the Dimension Attribute value sending method was selected, then select an attribute in the drop-down list. The list displays all available attributes of all table area dimensions in the data entry form. Only one attribute can be selected.
If the Manually value sending method was selected, then the Value field displays the editor corresponding to the parameter type. Only one element can be selected.
Selection Type. The drop-down list is available if the Dimension Attribute value sending method was selected. In the drop-down list select:
First Element. The parameter send the selected attribute of the first dimension element from selection.
All Elements. Selected attribute values of all dimension elements from selection are sent to the parameter.
If a web form opens on custom button click, the system registers th active regular report, with which the web form is linked, within the user session. The active report is returned by the PrxReport.ActiveReport static property that is available in the Fore language. If several web forms are selected, which are called from different reports, the active report will be the one, from which the last web form call was executed until its closing, within the same session.
If there are several simultaneously opened regular reports and web forms, the PrxReport.ActiveReport property can work incorrectly because it returns last report, from which the web form was opened. One can change the active report using the SetActiveReport operation.
To work with a report from web form, one should save the active report to the global variable declared at the web form class level. The active report is 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;
When the Algorithm Calculation type is selected, determine the additional settings:
Select Executable Object. Select in the drop-down list the calculation algorithm that will be executed on button click:
NOTE. The calculation algorithm used in a custom button is included in the hierarchy of data entry form objects. To view the hierarchy of data entry form objects, use the Consists Of tab of the Object Properties window 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. Only one unit can be set for the button.
Set parameters for calculation algorithms with parameters:
Value Type. Determine values that are used on calculation algorithms:
Object Parameter. Calculation uses object parameter value.
Constant Value. Calculation uses a constant value.
Selection Type. Depending on the selected value type:
If the Form Parameter type is selected, choose the selection type in the drop-down list. Available values: initial, first element, last element, initial+children, initial+children (recursive), children, children (recursive).
If the Constant Value type is set, the selection type is unavailable.
Dictionary Schema. Select selection schema of dictionary used as algorithm parameter in the drop-down list. If selection schema is not set for dictionary, the list will be empty.
NOTE. Dictionary selection schema has a greater priority than selection type.
Value. Depending on the selected value type:
If the Object Parameter type is selected, determine parameter or report parameter attribute by selecting it in the drop-down list.
If the Constant Value type is selected, set the constant value.
When the Fore/JS Function Unit type is selected, determine the additional settings:
Unit. Select the Fore unit in the drop-down list. Only one unit can be set for the 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. The regular report in the IPrxReport format is sent to the parameter. When working with this object, all properties and methods of the IPrxReport interface will be available.
NOTE. If the unit does not contain methods and functions satisfying the required signature, the Unit Method/Function list is disabled.
Function example:
Sub SubButtons(Report: IPrxReport);
Var
TSheet: ITabSheet;
Begin
TSheet := (Report.ActiveSheet As IPrxTable).TabSheet;
TSheet.Cell(0, 0).Value := DateTime.Now.ToString;
TSheet.Recalc;
End Sub SubButtons;
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 firstly executed and 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 operation.
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();
}
// Get data entry form name
async function getName(callback, args) {
const { moduleId } = args;
const openId = Platform.Managers.Prx(moduleId).selectors.openId();
const metadata = await Platform.Bi.execMethod('ASM_WEB_METHODS', 'GetMetadata', [openId]);
callback(metadata.Name);
}
After the Fore unit is set up, set up prehandler, posthandler, and button activity management.
The prehandler is used to display a text message with user-defined text on clicking the custom button. For example, a prehandler with a message about calculation start that may take long time can be set up for the button that starts calculation. In this case, clicking the button before the calculation displays the configured message.
TO set up 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:
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 list is disabled.
Parameters:
Report. The regular report in the IPrxReport format is sent to the parameter. When working with this object, all properties and methods of the IPrxReport interface will be available.
messageType. Optional parameter. It is used to determine displayed message format. If the parameter is not set, a confirmation dialog box is displayed. To hide the displayed message, set the returned value to Return. Available values:
0. Confirmation dialog box. Clicking the Yes button in the dialog box executes the operation specified for the button. Clicking the No button cancels the action selected for the button.
1. Error. Clicking the OK button in the dialog box does not execute the operation specified for the button.
2. Warning. Clicking the OK button in the dialog box does not execute the operation specified for the button.
3. Information message. Clicking the OK button in the dialog box does not execute the operation specified for the button.
Function example:
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 firstly executed and 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 operation.
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();
}
// Get data entry form name
async function getName(callback, args) {
const { moduleId } = args;
const openId = Platform.Managers.Prx(moduleId).selectors.openId();
const metadata = await Platform.Bi.execMethod('ASM_WEB_METHODS', 'GetMetadata', [openId]);
callback(metadata.Name);
}
The posthandler is used to execute required actions after finishing method work Only one posthandler can be set.
To set up 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 list is disabled.
Parameter:
Report. The 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.
Function example:
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 firstly executed and 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 operation.
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();
}
// Get data entry form name
async function getName(callback, args) {
const { moduleId } = args;
const openId = Platform.Managers.Prx(moduleId).selectors.openId();
const metadata = await Platform.Bi.execMethod('ASM_WEB_METHODS', 'GetMetadata', [openId]);
callback(metadata.Name);
}
Set up button activity management
To set up button activity management, set the Unit Method/Function parameter, in which select the 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. The regular report in the IPrxReport. When working with this object, all properties and methods of the IPrxReport interface will be available.
Available values:
True. The button is active.
False. The button is inactive.
NOTE. The condition execution check is permanently running, that is why Fore function must be executed quickly, otherwise the data entry form will not work.
See also: