How-to: NEWSESSION
Example 1
Task
We have an order with a number and a posted/not posted flag.
CLASS Order 'Order';
isPosted 'Completed' = DATA BOOLEAN (Order);
number 'Number' = DATA INTEGER (Order);
FORM orders
OBJECTS o = Order
PROPERTIES(o) READONLY isPosted, number
;
We need to create an action that will post this order in a separate change session and then will add it to the form containing the list of orders.
Solution
post 'Complete' (Order o) {
NEWSESSION {
isPosted(o) <- TRUE;
APPLY;
}
}
EXTEND FORM orders
PROPERTIES(o) post TOOLBAR
;
If you do not "wrap" the action that sets the isPosted
property in the NEWSESSION
operator, then the APPLY
operator will also write other changes (including those made on the orders
form) to the database.
Example 2
Task
Similar to Example 1, except that the dedicated edit form is available for the order.
FORM order
OBJECTS o = Order PANEL
PROPERTIES(o) isPosted, number
EDIT Order OBJECT o
;
We need to create an action that creates a new order and open the edit form for it. This action must be added to the form containing the list of orders.
Solution
newOrder () {
NEWSESSION {
NEW o = Order {
number(o) <- (GROUP MAX number(Order oo)) (+) 1;
SHOW order OBJECTS o = o;
}
}
}
EXTEND FORM orders
// Option 1
PROPERTIES() newOrder DRAW o TOOLBAR
// Option 2
PROPERTIES(o) NEWSESSION NEW
;
If you do not use the NEWSESSION
operator, then the object for the new order will be created in the change session of the orders
form. And if the user closes the form without saving, then all the changes "will remain" in the change session for the form, and the created order will be displayed in the form containing the list of orders.
Example 3
Task
Similar to Example 2, except that the order can be marked.
selected 'Mark' = DATA LOCAL BOOLEAN (Order);
EXTEND FORM orders
PROPERTIES(o) selected
;
We need to create an action that will delete the marked orders and immediately save the changes to the database (so that the user does not need to click "Save").
Solution
deleteSelectedOrders 'Delete marked orders' () {
NEWSESSION NESTED(selected) {
DELETE Order o WHERE selected(o);
ASK 'You are about to delete ' + (GROUP SUM 1 IF DROPPED(o IS Order)) + ' orders. Continue?' DO {
APPLY;
}
}
}
EXTEND FORM orders
PROPERTIES() deleteSelectedOrders DRAW o TOOLBAR
;
By default, a new session ignores changes made in the "upper" session. To make the selected property available in the new session, use the NESTED
block of operators. Otherwise, the selected
property will always be NULL
. Alternatively, you can use the NESTED LOCAL
block instead of specifying particular properties. In this case, changes made to all local properties in the upper session will be visible.
Example 4
Task
Similar to Example 2, except that the payment logic for the order has been added.
CLASS Payment 'Payment';
date 'Date' = DATA DATE (Payment);
sum 'Amount' = DATA NUMERIC[14,2] (Payment);
order 'Order' = DATA Order (Payment);
We need to create a button on the form for opening a separate edit form for payments in this order.
Solution
FORM orderPayments 'Order payments'
// Not adding properties so that this object is not visible on the form at all
OBJECTS o = Order PANEL
OBJECTS p = Payment
PROPERTIES(p) date, sum, NEW, DELETE
FILTERS order(p) == o
;
editPayments 'Edit payments' (Order o) {
NESTEDSESSION {
SHOW orderPayments OBJECTS o = o;
}
}
EXTEND FORM order
PROPERTIES(o) editPayments
;
If you use the NESTEDSESSION
operator, then all the changes made in the "upper" change session will be available in the nested session. If the user closes the form without clicking OK, then all changes made directly in the form will be lost. If the user clicks OK, then the changes will be written to the "upper" change session rather than to the database. They will be written to the database along with the changes made in the main orders
form.
It is not allowed to use NEWSESSION
here simply because the orderPayments
form will not be able to see the newly created order which has not yet been added to the database (since changes made in the "upper" session are not visible in the nested one), and thus the behavior will be unpredictable.
If we do not use any session management operator at all, then if the user make any changes in the orderPayments
form and clicks the Close button, the changes will still be "saved", though the user might not expect that.