Skip to content
Developerhome
Product homepage
Sage 200

First Customisation - Extend Textbox to Amend Supplier

  Less than to read

Overview

In this guide we shall build on the New Supplier Textbox functionality by extending the Textbox to be included on the Amend Supplier screen. This involves adding the Amend Supplier page to the pages array, creating a new event for the Amend Supplier page, and adding some validation to the textbox.

Step 1: Add the Amend Supplier Page

First, we need to add the “purchase/amend-supplier” to the pages array. This ensures that our customisation applies to the Amend Supplier screen as well as the “purchase/new-supplier” screen.

1. Add the “purchase/amend-supplier” identifier to the array. Remember to include a comma , to close off the previous entry.

{
  "version": "1.0",
  "pages": [
    "purchase/new-supplier",
    "purchase/amend-supplier"
  ],
}

Step 2: Add a New Event for the Amend Supplier

Next, we’ll define the onStateChange event. This event will trigger when the state of the “name” field changes, allowing us to enable or disable the nickname textbox dynamically.

The onStateChange event is crucial because the amend supplier screen behaves differently from the new supplier screen. Previously, we enabled the textbox when the new supplier screen loaded, as all fields are enabled by default. However, on the amend supplier screen, only the “id” (Display name “code”) field is enabled initially, and all other fields remain disabled until a supplier code is selected. Currently, our textbox remains disabled with no way to enable it on the amend supplier screen.

This is where onStateChange comes in. It will monitor the “name” field and, once it is not blank, it will enable our textbox. While we could monitor the “id” field for changes, we wanted to demonstrate that you can monitor other fields as well.

To begin, we need to specify that this event is for the “purchase/amend-supplier”. This ensures that our customisation only applies to the Amend Supplier screen.

1. In the events section after the new supplier onLoad event we need to add a new pages section for “purchase/amend-supplier”.

"events": [
    {
      "onLoad": [
        {
          "set": {
            "pageExtension": {
              "componentId": "short_name",
              "panel": "bottom",
              "uiExtension": "Nickname"
            }
          }
        }
      ]
    },
    {
      "pages": [
        "purchase/new-supplier"
      ],
      "onLoad": [
        {
          "action": "enableNickname"
        }
      ]
    },
    { //New Page Event
      "pages": [
        "purchase/amend-supplier"
      ],
    }
  ]

2. Next, we will add the onStateChange event. This event will monitor changes to the “name” field and trigger actions based on those changes.

  • pages: Specifies that this event is for the “purchase/amend-supplier” page.
  • onStateChange: Defines the event that will trigger when the state of the specified target changes.
  • watchTarget: Indicates the state property to monitor, in this case, the “name” field.
  • onChange: An array where we will define the actions to take when the “name” field changes.

For more information on the onStateChange event, refer to the onStateChange guide.

{
  "pages": [
    "purchase/amend-supplier"
  ],
  "onStateChange": [
    {
      "watchTarget": "name",
      "onChange": []
    }
  ]
}

3. First, we need to add the basic structure of the if statement within the onChange array. This includes the ne condition, then, and else blocks.

The if statement allows you to conditionally execute actions based on specific conditions. Here’s the basic structure:

  • condition: Represents the condition that will be evaluated using the available operators.
  • then: Represents the actions that will be executed if the condition is true.
  • else: Represents the actions that will be executed if the condition is false.

In this guide, we use the ne (not equal) operator to check if the “name” field is not equal to an empty string. Other operators you can use include:

  • eq (equal): Checks if two values are equal.
  • lt (less than): Checks if the left value is less than the right value.
  • gt (greater than): Checks if the left value is greater than the right value.
  • ge (greater than or equal): Checks if the left value is greater than or equal to the right value.
  • le (less than or equal): Checks if the left value is less than or equal to the right value.

For more details, refer to the IF statement guide.

{
  "pages": [
    "purchase/amend-supplier"
  ],
  "onStateChange": [
    {
      "watchTarget": "name",
      "onChange": [
        {
          "if": {
            "ne": [],
            "then": [],
            "else": []
          }
        }
      ]
    }
  ]
}

4. Next, we need to specify what the ne (not equal) condition is comparing. We will add the get state for the “name” field and the string value as an empty string.

  • Get State: Retrieves the current state of the “name” field.
  • String Value: Compares the state to an empty string (“”).
{
  "pages": [
    "purchase/amend-supplier"
  ],
  "onStateChange": [
    {
      "watchTarget": "name",
      "onChange": [
        {
          "if": {
            "ne": [
              {
                "get": {
                  "state": "name"
                }
              },
              {
                "string": {
                  "value": ""
                }
              }
            ],
            "then": [],
            "else": []
          }
        }
      ]
    }
  ]
}

5. Now, we will define the actions to take based on the condition.

  • Then: If the “name” field is not empty, the enableNickname action is executed, enabling the nickname textbox.
  • Else: If the “name” field is empty, the else block sets the disabled property of spare_text_1 to true, ensuring the textbox remains disabled.

Note: We could create a new action to disable the textbox and call it in the else block, making it reusable. However, in this example, we directly set the disabled property to true to demonstrate different options.

{
  "pages": [
    "purchase/amend-supplier"
  ],
  "onStateChange": [
    {
      "watchTarget": "name",
      "onChange": [
        {
          "if": {
            "ne": [
              {
                "get": {
                  "state": "name"
                }
              },
              {
                "string": {
                  "value": ""
                }
              }
            ],
            "then": [
              {
                "action": "enableNickname"
              }
            ],
            "else": [
              {
                "set": {
                  "properties": {
                    "spare_text_1": {
                      "disabled": true
                    }
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

working field

Step 4: Add Validation

Finally, we’ll add validation to ensure the nickname does not exceed 10 characters. This prevents users from entering overly long nicknames.

1. First in the validation section lets add the errors array. There are two different types of validation that be used:

  • Errors: Displays a red prohibited sign and prevents the screen from being saved if validation fails. Ideal for critical data integrity checks.
  • Warnings: Displays a yellow warning triangle and allows saving of the screen despite the warning. Useful for issues that should be flagged to the user, but are not invalid.
{
  "validations": {
    "errors": []
  }
}

2. First, we need to define the onLoad event in the JSON schema. This event will trigger when the page loads, we shall be triggering a action.

  • Field: Specifies that the validation is targeting the spare_text_1 field, which is the nickname textbox.
  • Type: Specifies that the field under validation is of type string. This means that constraints such as max will check the string length.
  • Constraints: Ensures the field does not exceed 10 characters. You need to set a value (maximum length) and a message (error message to display). If this condition is violated, an error message “Max 10 characters!” will be displayed.

For more information please see the Validations guide and the Types and Constraints information.

{
  "validations": {
    "errors": [
      {
        "field": "spare_text_1",
        "type": "string",
        "constraints": {
          "max": {
            "value": 10,
            "message": "Max 10 characters!"
          }
        }
      }
    ]
  }
}

In this code, we define a validation rule for the spare_text_1 field to ensure it does not exceed 10 characters. This is an error validation, meaning it will prevent the form from being saved if the condition is not met. This validation enhances data integrity by ensuring that nicknames are kept within a reasonable length, improving the overall user experience.

error on the screen

Congratulations! You now have a working web extension that adds a textbox to multiple screens, writes back to the database using the a spare text field, utilising events, and even includes validation.

Next - Utilising the Sage 200 API