E-mail
New in package 166
Common
Server calls and events:
- are not cancelable
- skipped if the corresponding Form event has been cancelled
- Server.calls() can be batched, i.e. multiple calls can be combined into one request to the server
In addition to specifying Server calls and events this proposal introduces the following changes to the existing specification:
- Red: compatibility:
- "meta_objectSaved" was fired from within the transaction, which is no longer an option with moving transactions server-side,
- "loadObject" was fired after "editingFinished", preventing proper batching
- Green: consistency:
- on new "editingStarted" was fired without prior "startEditing" etc
- there was no common event for specifying additional server calls for all objects created or loaded => "loadObject" is proposed to be called on New
Gray+ blue: applying object updates w/o reload:- user modifications and field focus were lost when an object was reloaded (by a script or as a result of a global update)
Expected Form events / request sequences
Creating a new object (New button)
Form.newObject()
| Form Events | Server Calls / Events | Notes | New in |
|---|---|---|---|
| ↪ "loadForm" | can be optimized away | ||
| |
Deferred: |
||
| ↪ "newObject" cancelable
|
Server.calls() are deferred | A. Golovanov: This event seems to be redundant: * "loadObject" is fired right after "newObject" * both "loadObject" and "newObject" are cancelable * Form.objectState can be used to distinguish new object loading vs. existing object loading Pasha: it can be kept for backward compatibility |
|
| ↪ "loadObject" to be implemened cancelable
|
Server.calls() are deferred Batch: |
Firing "loadObject" on New makes sure that the common Server.calls() are made for the newly created object (same grids, pop-ups etc as for the existing objects). |
|
| |
|||
| ↪ 'loadObject' | object.$isNew == true object.$isBeingEdited == true |
165.0.8233 ? | |
| ↪ 'objectLoaded' | The object is created by the server. | ||
| "newObject" Server.calls() | The created object is available via Server.$object. | ||
| "loadObject" Server.calls() | |||
| ↪ "objectLoaded" to be implemened | |||
| ↪ "objectSet" | The event is redundant, but can be kept for backward compatibility. | ||
| ↪ "editObject" to be implemened cancelable
|
|||
| ↪ "editingStarted" |
Changing properties of a new object (Properties button, object is not added to the database yet)
| Form Events | Server Calls / Events | Notes |
|---|---|---|
| ↪ "propertiesChanged" |
Adding newly created object to the database (Add button)
Form.saveObject()
| Form Events | Server Calls / Events | Notes | New in |
|---|---|---|---|
| ↪ "okEditing" cancelable
|
|||
| ↪ "saveObject" cancelable
|
Deferred: Server.calls() are deferred |
||
| ↪ "loadObject" cancelable
|
Server.calls() are deferred Batch: |
||
| "saveObject" Server.calls() | The object is updated by the server. | ||
| ↪ 'saveObject' | The transaction is started | ||
| ↪ 'objectSaved' | Changes to the object are saved to the database. object.$isNew == true |
165.0.8230 | |
| The object was not locked. The transaction is committed. |
|||
| ↪ 'loadObject' | object.$isBeingEdited == false | 165.0.8230 | |
| ↪ 'objectLoaded' | The object is reloaded before returning it to the Form. | ||
| "loadObject" Server.calls() | The loaded object is available via Server.$object. | ||
| |
|||
| ↪ "editingFinished" |
Newly added object is "reloaded" "refreshed":
| Form Events | Server Calls / Events | Notes |
|---|---|---|
| |
||
| |
||
| ↪ "objectLoaded" | Controls are updated w/o the "unload"/"reload" cycle. | |
| ↪ "objectSet" | The event is redundant, but can be kept for backward compatibility. |
Canceling creation of a new object (Cancel button)
Form.cancelEditing()
| Form Events | Server Calls / Events | Notes |
|---|---|---|
| ↪ "cancelEditing" cancelable
|
Deferred: Server.calls() are deferred Batch: |
|
| "cancelEditing" Server.calls() | ||
| The object is unlocked. | ||
| ↪ "editingFinished" |
↪ The object is unloaded and the previously loaded existing object is loaded anew:
Loading an existing object
| Form Events | Server Calls / Events | Notes | New in |
|---|---|---|---|
| ↪ "loadForm" | can be optimized away | ||
| ↪ "loadObject" cancelable
|
Deferred: Server.calls() are deferred Batch: |
||
| ↪ 'loadObject' | object.$isBeingEdited == false | 165.0.8230 | |
| ↪ 'objectLoaded' | The object is loaded by the server. | ||
| "loadObject" Server.calls() | The loaded object is available via Server.$object. | ||
| ↪ "objectLoaded" | |||
| ↪ "objectSet" | The event is redundant, but can be kept for backward compatibility. |
Unloading an object
| Form Events | Server Calls / Events | Notes |
|---|---|---|
| ↪ "objectUnloaded" |
Starting editing an existing object (Edit button)
Form.editObject()
| Form Events | Server Calls / Events | Notes | New in |
|---|---|---|---|
| ↪ |
Deferred: |
||
| ↪ "loadObject" cancelable
|
Server.calls() are deferred Batch: |
||
| |
|||
| ↪ 'loadObject' | object.$isBeingEdited == true | 165.0.8230 | |
| ↪ 'objectLoaded' | The object is loaded and locked by the server. | ||
| "loadObject" Server.calls() | The loaded object is available via Server.$object. | ||
| ↪ "objectLoaded" | Controls are updated w/o the "unload"/"reload" cycle. | ||
| ↪ "objectSet" | The event is redundant, but can be kept for backward compatibility. | ||
| ↪ "editObject" cancelable
|
|||
| ↪ "editingStarted" |
Changing properties of an existing object (Properties button, during editing)
| Form Events | Server Calls / Events | Notes |
|---|---|---|
| ↪ "propertiesChanged" |
Updating an existing object (Update button)
Form.saveObject()
| Form Events | Server Calls / Events | Notes | New in |
|---|---|---|---|
| ↪ "okEditing" | |||
| ↪ "saveObject" cancelable
|
Deferred: Server.calls() are deferred |
||
| ↪ "loadObject" cancelable
|
Server.calls() are deferred Batch: |
||
| "saveObject" Server.calls() | The object is updated by the server. | ||
| ↪ 'saveObject' | The transaction is started. | ||
| ↪ 'objectSaved' | Changes to the object are saved to the database. | 165.0.8230 | |
| The object is unlocked. The transaction is committed. | |||
| ↪ 'loadObject' | object.$isBeingEdited == false | 165.0.8230 | |
| ↪ 'objectLoaded' | The object is reloaded before returning it to the Form. | ||
| "loadObject" Server.calls() | The loaded object is available via Server.$object. | ||
| |
|||
| ↪ "editingFinished" |
The object is "reloaded" "refreshed":
| Form Events | Server Calls / Events | Notes |
|---|---|---|
| |
||
| |
||
| ↪ "objectLoaded" | Controls are updated w/o the "unload"/"reload" cycle. | |
| ↪ "objectSet" | The event is redundant, but can be kept for backward compatibility. |
Canceling editing an existing object (Cancel button)
| Form Events | Server Calls / Events | Notes | New in |
|---|---|---|---|
| ↪ "cancelEditing" cancelable
|
Deferred: Server.calls() are deferred |
||
| ↪ "loadObject" cancelable
|
Server.calls() are deferred Batch: |
||
| "cancelEditing" Server.calls() | |||
| The object is unlocked. | |||
| ↪ 'loadObject' | object.$isBeingEdited == false | 165.0.8230 | |
| ↪ 'objectLoaded' | The object is reloaded before returning it to the Form. | ||
| "loadObject" Server.calls() | The loaded object is available via Server.$object. | ||
| ↪ "editingFinished" |
The object is "reloaded" "refreshed":
| Form Events | Server Calls / Events | Notes |
|---|---|---|
| |
||
| |
||
| ↪ "objectLoaded" | Controls are updated w/o the "unload"/"reload" cycle. | |
| ↪ "objectSet" | The event is redundant, but can be kept for backward compatibility. |
Batch Attach/Modify
| Form Events | Server Calls / Events | Notes |
|---|---|---|
| ↪ "loadForm" | ||
| ↪ "loadObject" | New in form API version 2.2 | |
| ↪ "attach"|"modify" | Form.object is a template object. | |
| ↪ "objectLoaded" | New in form API version 2.2 | |
| ↪ "objectSet" | ||
| ↪ "startEditing" | New in form API version 2.2 | |
| ↪ "objectSet" | New in form API version 2.2 | |
| ↪ "editObject" | New in form API version 2.2 | |
| ↪ "editingStarted" | ||
| After pressing Attach/Modify button | ||
| ↪ "okEditing" | ↪ "cancelEditing" on cancel. | |
| ↪ "saveObject" | New in form API version 2.2 | |
| saveObjects(template, ids) | New in form API version 2.2 | |
| Begin for each object | Client side events kept for backward compatibility with form API version < 2.2. | |
| ↪ loadObject | New in form API version 2.2 | |
| ↪ objectSaved | New in form API version 2.2 | |
| ↪ "objectLoaded" (modify only) | ||
| ↪ "objectSet" | ||
| ↪ "saveObject" | ||
| ↪ "meta_objectSaved" (modify only) | ||
| ↪ "objectUnloaded" | ||
| End for each object | ||
| ↪ "editingFinished" | ||
| ↪ "objectUnloaded" |
Global update
The object is "reloaded" "refreshed":
| Form Events | Server Calls / Events | Notes | New in |
|---|---|---|---|
| |
|||
| ↪ "loadObject" cancelable
|
Deferred: Server.calls() are deferred Batch: |
||
| ↪ 'loadObject' | object.$isBeingEdited == false | 165.0.8230 | |
| ↪ 'objectLoaded' | The object is reloaded by the server. | ||
| "loadObject" Server.calls() | The loaded object is available via Server.$object. | ||
| ↪ "objectLoaded" | Controls are updated w/o the "unload"/"reload" cycle. | ||
| ↪ "objectSet" | The event is redundant, but can be kept for backward compatibility. |
See also
Server events: