Lesson 12: Payments, Widget Visiblity
Widget Visibility
As mentioned in the scenario that accompanies this lesson, we will have multiple stages within the flow of the purchase feature. Despite this we will only be using one view. After each stage, more view components become visible to the user. This is achieved using visible function bindings. The following code snippet shows the functions that are used for these bindings:
// Once a shop has been selected, the stock items for this shop can be displayed
bool showStockTable() {
if(shop == null) {
return false;
}
return true;
}
// Once a stock item has been selected is can be displayed with a text field for the quantity to purchase
bool showPurchaseForm() {
if(showStockTable() == false || selectedStock == null) {
return false;
}
return true;
}
// Once the purchase quantity has been validated and the price calculated the cost summary can be displayed
bool showSummary() {
if(showPurchaseForm() == false || goodsCost == null) {
return false;
}
return true;
}
// In the case of a farmer with a government assistance certificate the discount related to this should
// also be shown as part of the final cost summary
bool governmentAssitanceApplicableAndSummary() {
if(showSummary() == false || farmer.governmentAssistanceCertificate == null) {
return false;
}
return true;
}
The screenshots below show the difference stages of widget visibility for the NewFarmerPurchase view:
Be careful when using visibility bindings on all your view components. If they all evaluate to false your view will fail to load instead of simply showing an empty view.
In cases where values are bound directly to primitive unit variables instead of model attributes, be sure to include manual validations using the Mez:alert functions seeing as data model validators cannot be used.
@OnPaymentUpdate Annotation for Payment Callback Functions
Helium processes payments asynchronously. This means that a result of a call to the pay function will not be immediately available.
Helium provides a mechanism whereby an app function can be declared as a callback that will be invoked once Helium has an update on the payment status. This is implemented by means of the @OnPaymentUpdate annotation. Such a callback for payments made without an additional reference is included in the app in the PaymentCallback unit under the services folder:
@OnPaymentUpdate
void paymentUpdate(uuid id, PAYMENT_STATUS status, string message){
// Find the associated purchase based on the internal Helium payment ID
// Ids should be unique so we are only expecting one purchase in the resulting collection
FarmerPurchase[] farmerPurchases = FarmerPurchase:equals(paymentId, id);
if(farmerPurchases.length() >= 0) {
FarmerPurchase farmerPurchase = farmerPurchases.first();
// Update the payment status maintained on the farmer purchase
farmerPurchase.paymentStatus = status;
// Record the time stamp of the update
farmerPurchase.paymentStatusUpdatedOn = Mez:now();
}
}
For payments that were made with an additional reference we can change the function signature as follows:
@OnPaymentUpdate
void paymentUpdateWithRef(uuid id, string reference, PAYMENT_STATUS status, string message){
.
.
}
The HistoricFarmerPurchases view shows the purchase details for historic purchases including payment statuses as updated using the callback functions above. The screenshot below demonstrates this:
The payment status, as updated using the callback function, is Failed_Validation in this case. This is to be expected though as no configuration for the routing of payments in our app has been set. A summary of the possible statuses and their meanings follows in the next section.