Skip to content
Developerhome
Product homepage
Sage 200

Understanding the schema

  Less than to read

Starting with the template provided when you add a new extension, lets take a look at the various sections within the schema:

{
  "version": "1.0",
  "pages": [],
  "uiExtensions": [],
  "actions": {},
  "validations": {},
  "events": []
}

Version

This represents the currently used version of the Sage 200 Web Extension schema. As we continue to make changes and updates to the schema design, we will increment the version number accordingly. This versioning system serves multiple purposes, allowing us to track future updates and enabling developers to assess functionality changes effectively.

It is important to note that newer major versions of the schema may not be backwards compatible. For instance, options introduced in version 2.0 will not be accessible to schemas utilising version 1.0.

When you create a new schema file, the current version number will be automatically set for you as the default value.

To ensure you stay informed about all updates and functionality enhancements, we will document these changes over time.

Please refer to the documentation for specific details on each version and its associated improvements. This will enable you to keep your implementation aligned with the latest updates and leverage the enhanced functionality offered by newer versions.

Pages

The pages section allows you to define which of the screens in the Sage 200 Web Portal you would like a given customisation to affect.

This promotes code reuse, as in instances of the same desired customisation to appear in multiple screens, you write the customisation once, and add the list of screens in the pages array.

For example, if we were adding a component to the new supplier screen, we simply state the module followed by the screen name:

{
  ...
  "pages": [
    "purchase/new-supplier"
  ],
  ...
}

You can easily identify the correct module and screen name from the URL of the associate screen in the Web Portal. The relevant page is always the last two elements of the URL, in this case purchase/new-supplier:

https://app.sage200.co.uk/Sage200WebPortal/app/purchase/new-supplier

You can easily add multiple screens to the array:

{
  ...
  "pages": [
    "purchase/new-supplier",
    "purchase/amend-supplier",
    "purchase/supplier-transaction-enquiry"
  ],
  ...
}

Any subsquent customisations you add to this schema file will appear on all of the screens listed.

UI Extensions

The UI Extensions section within our JSON Schema is a fundamental element for customising user interfaces on a set of screens. This section functions as an array, accommodating multiple UI extension objects.

Each UI extension object is defined by a unique identifier, like ‘Agent’ in this example. This identifier is later used in the events section to render the components on the screen. Within the UI extension object, there is a component array where individual components and their properties are specified. In this instance, we have configured two Textbox components.

Each component within the array is characterised by a set of properties, including a unique component ID. Notably, unlike traditional desktop window screens, you don’t need to specify a separate label component; it is treated as a property of the Textbox.

For example, let’s consider the ‘Agent’ UI extension:

 "uiExtensions": [
    {
      "id": "Agent",
      "component": [
        {
          "Textbox": {
            "id": "spare_text_1",
            "label": "Agent 1",
            "disabled" : true,
            "mt": 2
          }
        },
        {
          "Textbox": {
            "id": "spare_text_2",
            "label": "Agent 2",
            "disabled": true,
            "mt": 2
          }
        }
      ]
    }
  ]

In this example, ‘Agent’ comprises of two textbox components. Later, when you load this UI extension on a screen using the onLoad method, you use the ‘Agent’ ID, which will load all components associated with the ID.

To make any modifications to the properties of individual components, such as enabling or disabling them, you need to target the specific component’s ID, such as ‘spare_text_1’ or ‘spare_text_2.’ These component IDs can be set to any unique identifier you desire, but for components like textboxes, it’s often useful to associate them with an endpoint field. In this case, we are utilising the ‘spare_text_1’ or ‘spare_text_2’ fields on the customer endpoint to expand the information stored in a customer record.

To explore all the available components and their properties for extending the UI, please refer to the schema documentation.

Actions

The actions section allows you to create the equivalent of methods or functions that can be re-used across multiple pages or components.

For example, when adding the textbox earlier for a supplier Agent we set the property of disabled to true in the uiExtension. This means the text box will not be active.

We could create an action, triggered by an event or button click that enables it:

  "actions": {
    "enableField": [
      {
        "set": {
          "properties": {
            "spare_text_1": {
              "disabled": false
            }
          }
        }
      }
    ]
  },

In the above example, we have created an action called enableField, which simply sets the disabled property of the text field component (spare_text_1) to false.

We can then call this action in an event such as onLoad to ensure its available when we need it to be.

Some other examples of good usecases for actions are:

  • Button Clicks

  • UI Extensions

  • Error Handling

  • Flow Control

More can be found on these in the actions guide.

Validations

You can use the validations object to set validation on the components you define in the schema.

We can have validations that report either errors, warnings or information notifications.

The web extensions utilise Yup as a means to define rules and constraints for your data.

Yup is a JavaScript schema validation library, allowing developers to define and validate the structure and constraints of the data being interacted with in the web portal.

  "validations": {
    "errors": [],
    "warnings": []
  }

For example we can create a validation on the new text box we’ve added, setting a contraint on the maximum number of characters you can pass into the text box.

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

Events

Events are moments in the web screen lifecycle that you as a developer can hook into, and trigger actions or define changes when they occur.

"events": [
  {
    "onSubmit": [
      {
        "action": "somethingOnSave"
      }
    ],
    "onClear": [
      {
        "action": "somethingOnClear"
      }
    ],
    "onLoad": [
      {
        "action": "somethingOnLoad"
      }
    ],
    "onStateChange": [
      {
        "watchTarget": "code",
        "onChange": [
          ...
        ]
      }
    ]
  }
]

Currently we have defined 4 events you can hook into:

  • onSubmit
  • onClear
  • onLoad
  • onStateChange

Lets take a quick look at what each one is for.

onSubmit

When the user presses the Save button in a Sage 200 Web Screen, the onSubmit event is triggered after the data has been successfully saved. This allows you to perform actions or execute code.

onClear

The onClear event is triggered when the user clears a Sage 200 web screen, after the Sage 200 onclear code has been executed. This allows you to perform any additional steps needed after the screen has been cleared, such as disabling certain fields or resetting variables.

onLoad

The onLoad event plays a vital role in specifying actions that are activated when a page is loaded. This event enables you to define components or behaviours that should be displayed or take place when the page is first displayed. By using the onLoad event efficiently, you can customise the functionality and appearance of the web screens.

In the example we used earlier, we can use the onLoad event to add our UIextension component (Agent). We can do this by choosing an existing component on the screen, and placing our extension above, below or to either side of it:

  "events": [
    {
      "onLoad": [
        {
          "set": {
            "pageExtension": {
              "componentId": "short_name",
              "panel": "bottom",
              "uiExtension": "Agent"
            }
          }
        }
      ]
    }
  ]

onStateChange

The onStateChange event allows you to monitor for changes in the state of a web screen such as a given component. If a change occurs developers can hook into this event to call actions or set changes.

You should now have a better understanding of the web extensions schema file and what goes into creating one.

We have more detailed information available for everything mentioned in this section if you visit guides section.

Next - Deployment