5 - Create a Validation

Last updated 15/12/2023

This documentation is to demonstrate how to add validation to a field to ensure the correct data is entered. The On Validate event can be used for this. The event executes on the client-side and performs accuracy checks on the data entered in the field.

Using the On Validate event, we can ensure the Quantity field on the Sells form cannot have a value larger than what we own in the stock.

When in Five's Code Editor you will be interacting with Five's API. In the

CheckStockQuantity()

function you will be using the following functions and properties:

field.<fieldID>

- is a property used on the

Five

object which gives the fields for the current form.

getMetadata()

- is a function used on the

Five

object that provides metadata from a field.

createError()

- is a function used on the

Five

object that returns an error with an optional message and notification parameters.

success()

- is a function used on the

Five

object that returns a

FiveError

indicating success.

Navigate to the Code Editor

1. Click Logic in the menu.

2. Click Code Editor in the sub-menu.

Figure 1 - Code Editor menu item

Add the CheckStockQuantity Function

info

The CheckStockQuantity function will use the metadata supplied in the CurrentStockHolding query that is attached to the Sell's Stock field. The function will use the Holding query field to know what we are currently holding in the stock.

1. Click the Add New Code button.

Figure 2 - Add New Code button

2. Type CheckStockQuantity in the Function ID field.

3. Click the lookup icon in the Language field and select TypeScript.

4. Click the OKAY button.

Figure 3 - Add the CheckStockQuantity function

5. Click the Copy button on the below code block.

CheckStockQuantity

function CheckStockQuantity(five: Five, context: any, result: FiveError) : FiveError {
    const qty: number = parseInt(five.field.Quantity);
    if (qty > five.getMetadata('Sells', 'StockKey', 'Holding')) {
        return five.createError(result, 'Stock quantity exceeds current holding');
    }

    return five.success(result, '');
}

6. Paste the code block over the template in the Code Editor.

7. Click the Save Current Tab button.

Figure 4 - Save Current Tab button

Navigate to Forms

info

The CurrentStockHolding function needs to be attached to the Quantity field on the Sells form. If the incorrect data is entered in the field the user will be enforced to change the quantity.

1. Click Visual in the menu.

2. Click Forms in the sub-menu.

Figure 5 - Forms menu item

Attach the CheckStockQuantity Function

Path: Sells form > General page > Quantity field > On Validate event

1. Select the Sells record in the list.

2. Click the Pages tab.

Figure 6 - Pages tab

3. Select the General record.

Figure 7 - General record

4. Click the Fields tab.

Figure 8 - Fields tab

5. Select the Quantity record.

Figure 9 - Quantity record

8. Click the Events tab.

Figure 10 - Events tab

9. Either click the Edit button in the form app bar, or click directly in the On Validate field.

10. Click the lookup icon in the On Validate field and select CheckStockQuantity.

Figure 11 - On Validate field

11. Click the Save button in the form app bar.

Figure 12 - Save button

12. Click the Save button in the form app bar above the list.

Figure 13 - Save button

Run the Portfolio Application

tip

This is a good time to run the Portfolio application to see how the CheckStockQuantity function works!

1. Click the Run button in Five's toolbar.

Figure 14 - Run button

2. Select the Growth Portfolio record in the list.

3. Click the Down button in the form app bar.

Figure 15 - Down button

Test the CheckStockQuantity Function

info

We can see on our Current Stock Holding data view that we own 5500 shares in the SUN (Suncorp) stock.

Figure 16 - Current Stock Holding data view

1. Select Sells in the Menu.

2. Click the Add Item button.

3. Click the lookup icon in the Stock field and select SUN.

4. Click the calendar icon in the Transaction Date field, select the current date and click the OK button.

5. Type 6000 in the Quantity field, press tab.

Figure 17 - Add a Sells record

info

The On Validate event is executed and causes an error as we do not own 6000 shares in the SUN stock.

6. Click the OK button.

Figure 18 - Validation error

7. Type 1000 in the Quantity field.

8. Type 1.00 in the Price field.

9. Type 10.00 in the Fees field, press tab.

10. Click the Add Allocations button.

Figure 19 - Add Allocations button

11. Click the lookup icon in the Buys field.

Problem

The Buy field lookup is showing us all the buy transaction dates. In Five, we can make it that we only see the transation dates for the stock selected on the Sells form.

Figure 20 - Buy field

12. Click the Cancel button in the form app bar.

Figure 21 - Cancel button

13. Close the browser tab and return to Five.