Розширення панелі інструментів елемента керування
"Before" and "after" Action Events
A file or table controls have standard actions and may have custom ones. The script module allows to execute something before or after some of these actions or pass additional actions.
form_<nodeId>_beforeAction_<actionCode>form_<nodeId>_actionExecuted_<actionCode>
The code of the action we can get from the prop editor for the file and table actions.
As for Document Actions, every control action event handler could be async or return a promise!
It does not have to, but it might if needed. In such a case, code will await for the event handler to complete.
The "before" handlers also have the cancelAction method, which allows not calling the action.
Useful for validations.
const {showErrorWindow} = require('@unitybase/ub-pub')
module.exports = {
form_4_beforeAction_storeAsCAdESContainer(event) {
const fileAttr = event.document.getFileAttribute('customFileAttrCode')
if (!fileAttr.isUploaded) {
event.cancelAction()
showErrorWindow('errors.fileMustBeUploaded')
return
}
if (!fileAttr.isSigned) {
event.cancelAction()
showErrorWindow('errors.fileMustBeSigned')
return
}
if (fileAttr.fileInfo.contentType !== 'application/pdf') {
event.cancelAction()
showErrorWindow('errors.fileMustBePdf')
}
},
form_4_actionExecuted_storeAsCAdESContainer(event) {
const fileControl = event.document.getNodeControl(4)
fileControl.downloadFile()
}
}
Extending additional actions in the script module
It is possible to extend File or Table control with additional actions.
In order to do that, use form_<nodeId>_additionalActions event handler method.
The method MUST be a synchronous function that returns an array of control extension configs.
The following is an example of how to make it:
const {Repository} = require('@unitybase/ub-pub')
module.exports = {
// register additional actions for a table attribute
form_3_additionalActions(event) {
return [
{
code: 'custom-toolbar-table-action-from-sm',
label: 'Toolbar table action from the script module',
icon: 'u-icon-key',
sortOrder: 0,
handler() {
},
toolbar: true
},
{
code: 'custom-context-menu-table-action-from-sm',
label: 'Context menu table action from the script module',
icon: 'u-icon-key',
handler() {
},
contextMenu: true,
availableInReadonlyMode: true
},
{
code: 'custom-selecteRow-table-action-from-sm',
label: 'Table action for the selected row from the script module',
icon: 'u-icon-key',
handler({rowID}) {
// const entry = await Repository(...).attrs(...).selectById(rowID)
// ...
},
showForSelectedRow: true
}
]
},
// register additional actions for a file attribute
form_4_additionalActions(event) {
return [
{
code: 'custom-file-action-from-sm',
label: 'File action from the script module',
icon: 'u-icon-key',
handler() {
}
}
]
},
// register additional actions for the attachment control
form_4_additionalActions(event) {
return [
{
code: 'custom-attachment-action-from-sm_for-carousel',
label: 'File action from the script module for the carousel mode',
icon: 'u-icon-key',
handler() {
},
carousel: true
},
{
code: 'custom-attachment-action-from-sm_for-dialog',
label: 'File action from the script module for the dialog mode',
icon: 'u-icon-key',
handler() {
},
dialog: true,
availableInReadonlyMode: true
}
]
}
}
Disabling and hiding control buttons
For controls with buttons, such as file controls or table controls, it is possible
to manage button state at runtime: control button visibility and/or availability.
First, use the getNodeControl method to get the control accessor object.
Then, use the getButton method of the control accessor, to get the button accessor object.
Button accessor object has the following methods:
hidden- boolean value that indicates if this button is hidden;hide()- function that hides this button if it is not hidden;show()- function that shows this button if it is hidden;disabled- boolean value that indicates if this button is disabled; Note: the button can be disabled by own logic (cannot remove signature if it is absent for example) not only from the script moduleenable()- function that enable this button if it is not hidden and disabled;disable()- function that disables this button is it is not hidden and not disabled.click()- function that call button handler if it is not disabled
hidden, hide(), show(), disabled, enable(), disable() are inherent for file and table controls.
disabled, enable(), disable() are inherent only for file controls.
click() is inherent only for file control and works even if the button is hidden
Examples:
const DOC_IMAGE_CONTROL_ID = 1
module.exports = {
form_1_mounted(event) {
const docImageFile = event.document.getNativeFileAttribute()
const docImageControl = event.form.getNodeControl(DOC_IMAGE_CONTROL_ID)
// Hide the create version button to prevent several versions
if (docImageFile.versions.length === 1) {
const createVersionButton = docImageControl.getButton('createVersion')
createVersionButton.hide()
}
// Hide the sign button to prevent double-signing
if (docImageFile.signatures.length === 1) {
const signButton = docImageControl.getButton('signDoc')
signButton.hide()
}
},
async beforeSave(event) {
const docImageFile = event.document.getNativeFileAttribute()
const docImageControl = event.form.getNodeControl(DOC_IMAGE_CONTROL_ID)
// Validate if the document image is uploaded. If not - open modal for uploading the file
if (!docImageFile.isUploaded) {
event.cancelSave()
docImageControl.openUploadFileWindow()
return
}
// Validate if the document image is signed. If not - open modal for signing the file
if (!docImageFile.isSigned) {
await docImageControl.openSignWindow()
// If file still not signed, it means user closed the sign window without signing it, cancel save
if (!docImageFile.isSigned) {
event.cancelSave()
} else {
// *MAIN LOGIC* Disable the sign button to prevent double-signing
const signButton = docImageControl.getButton('signDoc')
signButton.disable()
}
}
},
document_docImage_versionCreated(event) {
const docImageControl = event.form.getNodeControl(DOC_IMAGE_CONTROL_ID)
// allow only a single version for the document
const createVersionButton = docImageControl.getButton('createVersion')
createVersionButton.disable()
// show and enable the remove version button
const removeVersionButton = docImageControl.getButton('removeVersion')
if (removeVersionButton.hidden) {
removeVersionButton.show()
}
if (removeVersionButton.disabled) {
removeVersionButton.enable()
}
},
document_docImage_versionRemoved(event) {
const docImageControl = event.form.getNodeControl(DOC_IMAGE_CONTROL_ID)
const createVersionButton = docImageControl.getButton('createVersion')
// enable the create version button to recreate this single version disabled in the above method
if (createVersionButton.disabled) {
createVersionButton.enable()
}
if (createVersionButton.hidden) {
createVersionButton.show()
}
}
}
Hiding Table Columns
For table controls it is possible to manage column state at runtime: control its visibility.
First, use the getNodeControl method to get the control accessor object.
Then, use the getColumn method of the control accessor, to get the column accessor object.
Column accessor object has the following methods:
hidden- boolean value that indicates if this column is hidden;hide()- function that hides this column if it is not hidden;show()- function that shows this column if it is hidden.
Examples:
const TABLE_NODE_ID = 54
module.exports = {
// as soon the table column control is rendered we should check document state and hide the column
form_54_mounted(event) {
if (event.document.state === 'reworking') {
hideColorColumn(event)
}
},
// when specific action that changes document state to `reworking` is executed we need hide the color column
action_executed_someAction(event) {
hideColorColumn(event)
}
}
function hideColorColumn(event) {
const tableControl = event.form.getNodeControl(TABLE_NODE_ID)
const colorColumn = tableControl.getColumn('attrValues.color')
colorColumn.hide()
}