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 appear.

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 is arguably one of the most important, as it allows us to define a number of UI components that we’d like to add to a set of screens as part of our customisations.

This section is an array that contains a number of UI extension objects.

In order to create an extension object you must provide a unique id that can be anything meaningful that you choose. It must also contain a component array, where you can list out the components you wish to add, along with the desired properties and values.

For example, if we wanted to add a text box to store the agent associated with a supplier, we specify the id, ‘Agent’, and the component array that contains the component(s), which in this case is a Textbox. You don’t need to specify a seperate label component, as you would in a Windows screen, it is a property of the Textbox.

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

To see the other properties and components you can work with to extend the UI please check out 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": [],
    "infos": []
  }

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

The onSubmit event fires when a Save button has been clicked, submitting the data entered on a given web screen.

onClear

The event called “onClear” is activated when a screen or a particular page within a screen is cleared or reset. Its purpose is to specify actions or code that should be called when the screen is cleared.

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