First Customisation - Add Textbox to New Supplier
Less than to read
Overview
Now we understand how to customise web screens, work with the schema and how to deploy extensions, lets start building a new customisation.
In this guide, we’ll add a new textbox to the New Supplier screen, allowing us to add a nickname to each supplier. The data will be stored in the spare_text_1 field of each supplier object.
Step 1: Create a New Extension
1. Navigate to the Web extensions screen. 2. Click Add to create a new extension. You will be presented with the new schema template:
{
"version": "1.0",
"pages": [],
"uiExtensions": [],
"actions": {},
"validations": {},
"events": []
}
3. Enter a meaningful Name for your extension. This Name will help you identify the extension in the future.
4. Ensure the Web Extension Enabled checkbox is ticked. This setting allows the extension to be active and function within Sage 200.
Step 2: Define the Version and Pages
1. At this stage we don’t need to change the version so leaving it at 1.0 is fine.
2. We need to add the page where the customisation will appear, you can navigate to the relavent screen in this case it will be the new supplier screen.
Note: The relevant page identifier is always the last two elements of the page URL, e.g., purchase/new-supplier.
3. For the New Supplier screen, add the identifier from the page URL to the page array as per below:
{
"version": "1.0",
"pages": [
"purchase/new-supplier"
],
}
Step 3: Define the UI Extension
In this step, we’ll walk through how to add a Textbox component to the New Supplier screen. The Textbox will be used to input a nickname for the supplier, with the data stored in the spare_text_1 field of the supplier record.
1. Set a Unique Identifier by creating a UI extension with a unique id. This id will be used to reference the entire extension throughout your customisation. Here, we’ll use nickname as the identifier but you can choose any meaningful identifier, just remember it for later.
{
"uiExtensions": [
{
"id": "nickname"
}
],
}
2. Define the Component Array within the UI extension. This array will contain the UI component(s) you want to include. For this example, we’re defining a single component, which will be a Textbox.
component: This array holds all the UI components that will be part of thenicknameextension.Textbox: We specify the component type here. At this point, theTextboxis just defined as a type without any properties.
{
"uiExtensions": [
{
"id": "nickname",
"component": [
{
"Textbox": {}
}
]
}
],
}
3. Add Properties to the Textbox Component, now that we’ve defined the Textbox component. The next step is to configure its properties. These properties will determine how the Textbox behaves and appears on the screen.
id: This is set to"spare_text_1", linking the Textbox to the corresponding field in the database (spare_text_1). When the form is saved, any input into this Textbox will be stored in thespare_text_1field of the supplier record.label: This is set to"Spare Text 1 Textbox", which is the text that will appear next to the Textbox on the screen, guiding users on what to enter.disabled: This is set totrue, meaning the Textbox will start in a disabled state. Users won’t be able to interact with it until it’s enabled by an action or event.mt: This is set to2, which sets the margin-top, adding 16 pixels of space above the Textbox. This ensures consistent alignment with other elements on the page.
{
"uiExtensions": [
{
"id": "nickname",
"component": [
{
"Textbox": {
"id": "spare_text_1",
"label": "Nickname",
"disabled": true,
"mt": 2
}
}
]
}
],
}
Step 4: Define the Events
We use the onLoad event to customise the behaviour and appearance of your application when a page loads. This guide will walk you through adding a component created in uiExtension to a page.
1. 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.
{
"events": [
{
"onLoad": [
{
// Actions to be defined here
}
]
}
]
}
2. Next, within the onLoad event, we will use the set action to configure the pageExtension property. This property allows us to add a component to a specific location on the page.
{
"events": [
{
"onLoad": [
{
"set": {
"pageExtension": {
// Properties to be defined here
}
}
}
]
}
]
}
3. Finally, we will define the properties within the pageExtension object. These properties specify the component to be added, its position, and the UI extension to be used.
componentId: This is set to"short_name", indicating that the UI extension component will be associated with theshort_namefield on the screen.panel: This is set to"bottom", meaning the UI extension component will be positioned below theshort_namefield.uiExtension: This is set to"nickname", referring to the ID of our UI extension defined in theuiExtensionssection.
{
"events": [
{
"onLoad": [
{
"set": {
"pageExtension": {
"componentId": "short_name",
"panel": "bottom",
"uiExtension": "nickname"
}
}
}
]
}
]
}
Current appearance of the New Supplier screen:
A disabled text field on a new supplier screen
Step 5: Create an Action to Enable the Textbox
At the beginning of this guide, we marked the UI extension as disabled. This means that when we load the New Supplier screen, the textbox will appear but will not be accessible. To enable the textbox, we need to create an action.
We could have left the textbox enabled by removing the disabled property, but when we move onto adding this textbox onto other screens such as Amend Supplier, we will require it to be disabled initially.
1. First, we need to define an action in the JSON schema. This action will set the disabled property of the spare_text_1 field to false. Lets create a new action called enableNickname
{
"actions": {
"enableNickname": [
]
}
}
2. Next, within the actions section, we define the enableNickname action. This action will enable the spare_text_1 textbox by setting its disabled property to false.
set: This action is used to modify the properties.properties: This object contains the properties to be set.spare_text_1: We when pass the ID of the fieldspare_text_1we want to enable.disabled: This is set tofalse, meaning the textbox will be enabled.
{
"actions": {
"enableNickname": [
{
"set": {
"properties": {
"spare_text_1": {
"disabled": false
}
}
}
}
]
}
}
Step 6: Call the Action on Page Load
We need to add the action to the existing onLoad event to call the action when the New Supplier screen loads. This involves adding a pages section and defining the onLoad event for that specific page.
1. Add to the existing onLoad event to call the action when the New Supplier screen loads:
{
"events": [
{
"onLoad": [
{
"set": {
"pageExtension": {
"componentId": "short_name",
"panel": "bottom",
"uiExtension": "Nickname"
}
}
}
]
},
{
"pages": [
"purchase/new-supplier"
],
}
]
}
2. Next, within the pages section, we will define the onLoad event. This event will only trigger for the specified page (purchase/new-supplier)
{
"events": [
{
"onLoad": [
{
"set": {
"pageExtension": {
"componentId": "short_name",
"panel": "bottom",
"uiExtension": "Nickname"
}
}
}
]
},
{
"pages": [
"purchase/new-supplier"
],
"onLoad": [
{
// Action to be defined here
}
]
}
]
}
3. Finally, we will add the action call within the onLoad event for the specified page. This ensures that the enableNickname action is triggered when the New Supplier screen loads.
pages: This specifies the screen where the action should be triggered.onLoad: This specifies that the action should be triggered when the page loads.action: This is set to “enableNickname”, referring to the action we defined in Step 5.
{
"events": [
{
"onLoad": [
{
"set": {
"pageExtension": {
"componentId": "short_name",
"panel": "bottom",
"uiExtension": "Nickname"
}
}
}
]
},
{
"pages": [
"purchase/new-supplier"
],
"onLoad": [
{
"action": "enableNickname"
}
]
}
]
}
When we load the screen, we now see the field enabled, consistent with the existing component behaviour. This setup ensures that the textbox is initially disabled but becomes enabled when the New Supplier screen loads, providing a seamless user experience.
An enabled text field on a new supplier screen