Both VaultUI and VaultCore modules can access VaultEntry object. The VaultEntry is the handler object for all document vault related operations. It acts as a model for all UI in M-Files Client, and from application modules' point of view it is the last step before the object or vault operation is delegated for M-Files server.
VaultEntry object allows VaultUI and VaultCore modules to handle various events that are triggered by object or vault related operation. The event handler may be allowed to change the operation parameters, and can cancel the operation. A separate event is triggered after the operation takes place, to allow the handling of the actual outcome of the operation.
If the event can be targeted for multiple objects, a separate event is sent to identify each single object, and again collectively for all objects that participate to the operation. The application may choose whether to handle single object or collective event. The single-object version is more convenient to implement, the collective version may receive some performance benefit. But it should not handle both, because that would lead to double-processing of objects.
For example, when the 'Undo checkout' operation is performed in UI for two objects, these events are triggered:
|
Event |
Explanation |
|
Event_UndoObjectCheckout |
Triggered twice before the operation takes place (once for each object) |
|
Event_UndoObjectCheckouts |
Triggered once before the operation (identifies a collection of affected objects) |
|
Event_ObjectCheckoutsUndone |
Triggered once after the operation (identifies a collection of affected objects) |
|
Event_ObjectCheckoutUndone |
Triggered twice after the operation (once for each object) |
Events that trigger before the actual operation can request the operation cancellation. For pre-event handlers the cancellation can be requested by returning false from the event handler.
{
// the vaultEntry variable refers to VaultEntry object.
vaultEntry.Events.OnUndoObjectCheckout = function( objVer ) {
// Validate the operation.
if( /*validation rule here*/ )
return false; // Prevent the undo checkout.
else
return true; // Allow the undo checkout.
};
}
Similarly any error in pre-operation event handler prevents the operation.
Events that trigger before the actual operation may allow the application to affect the operation parameters. The rule of a thumb is that operation target must not be changed, but operation parameters can be changed. For example, the event CheckInObject receives two parameters, object version and property values. The object version is the operation target and it cannot be modified. The property values are the operation payload data, and they can be changed by the application module.
The code below checks and removes known property definition from object properties before the object is checked in.
{
// the vaultEntry variable refers to VaultEntry object.
vaultEntry.Events.OnCheckInObject = function( objVer, propertyValues ) {
// Remove single property.
var inded = propertyValues.IndexOf( 1234 );
if( index != -1 )
propertyValues.Remove( index );
};
}
An event handler that gets triggered after the server operation can perform logging and maintenance tasks, and further processing.
{
// the vaultEntry variable refers to VaultEntry object.
vaultEntry.Events.OnObjectsCheckedIn = function( objVer, objectVersions ) {
// All object versions in objectVersions collection are now checked in.
// Check out again.
for( var i = 0; i <= objectVersions.Count i++ )
vaultEntry.Vault.Checkout( objectVersions.Item( i ).ObjVer.ObjID );
};
}
In order to have more control over the whole operation, the application module can request post-event handling in pre-handler by returning an object that handles the post-event. With this technique it is possible to trace error situations, too.
{
// the vaultEntry variable refers to VaultEntry object.
vaultEntry.Events.OnDestroyObject = function( objID ) {
// This is called before the object is destroyed.
return {
OnSuccess: function() {
// This is called after the object is destroyed.
},
OnError: function( errorCode, errorMessage, errorStack ) {
// This is called if the object destroying failed due an error.
},
Finally: function() {
// This is called after all anyway.
}
};
};
}