Skip to content
Developerhome
Product homepage
Sage 200

Example - Contract Number/Special Instructions

  Less than to read

In this example, we'll explore how to enhance the Sales Order screens to provide more user interface options, this will be achieved by:

  • Adding specialised components, such as a "Contract Number" textbox as well as expanding an existing table with an "Special Instructions" column.
  • We'll show you how to leverage additional endpoint fields such as "spare_text_1" and "spare_number_1" to enrich your app's functionality.
  • Understand how your app can intelligently enable or disable components based on user actions. We'll demonstrate this feature across different screens.

Pages

The “pages” section specifies the screens on which the components will be used. There are three pages involved: “sop/view-sales-order,” “sop/amend-sales-order,” and “sop/new-sales-order.”

uiExtensions

The “uiExtensions” section defines additional UI components that will be added to the screens.

  • ContractNumberExt: This extension adds a disabled and read-only textbox labelled “Contract number” associated to the “spare_text_1” field on the sales_order endpoint.
{
  "id": "ContractNumberExt",
  "component": {
    "Textbox": {
      "id": "spare_text_1",
      "mt": 2,
      "label": "Contract number",
      "disabled": true,
      "readOnly": true
    }
  }
},
  • SpecialInstructionsColumnExt This extension extends the grid on these 3 screens by adding a column “Special instructions.” This column contains an enumSelect control type with predefined options. The value is assigned to the spare_number_1 field on the sales_order endpoint.
{
  "id": "SpecialInstructionsColumnExt",
  "component": {
    "GridColumn": {
      "index": "12",
      "headerName": "Special instructions",
      "field": "spare_number_1",
      "editable": true,
      "controlType": "enumSelect",
      "getItems": [
        {
          "id": 0,
          "value": 0,
          "text": ""
        },
        {
          "id": 1,
          "value": 1,
          "text": "Handle with care"
        },
        {
          "id": 2,
          "value": 2,
          "text": "Only despatch in full"
        }
      ]
    }
  }
}

Actions

The “actions” section defines specific actions that can be triggered within the schema.

  • setDisabled: This action sets the “disabled” and “readOnly” properties of the “spare_text_1” component to true, effectively disabling and making it read-only.
"setDisabled": [
  {
    "set": {
      "properties": {
        "spare_text_1": {
          "disabled": true,
          "readOnly": true
        }
      }
    }
  }
],
  • setEnabled: This action sets the “disabled” and “readOnly” properties of the “spare_text_1” component to false, enabling both editing and interaction.
"setEnabled": [
  {
    "set": {
      "properties": {
        "spare_text_1": {
          "disabled": false,
          "readOnly": false
        }
      }
    }
  }
],
  • setReadOnly: This action sets the “disabled” property of the “spare_text_1” component to false and the “readOnly” property to true, allowing interaction but making it read-only.
"setReadOnly": [
  {
    "set": {
      "properties": {
        "spare_text_1": {
          "disabled": false,
          "readOnly": true
        }
      }
    }
  }
]

Events

The “events” section defines the events associated with each page.

  • onLoad: This event triggers when the page loads. It performs the following actions:

    • Sets the “ContractNumberExt” UI extension to appear at the bottom panel of the “order_priority” component.
    • Adds the “SpecialInstructionsColumnExt” UI extension to the “lines” component, extending the grid.
    • Executes the “setDisabled” action, effectively disabling the “spare_text_1” textbox.
{
  "onLoad": [
    {
      "set": {
        "pageExtension": {
          "componentId": "order_priority",
          "panel": "bottom",
          "uiExtension": "ContractNumberExt"
        }
      }
    },
    {
      "set": {
        "componentExtension": {
          "componentId": "lines",
          "uiExtension": "SpecialInstructionsColumnExt"
        }
      }
    },
    {
      "action": "setDisabled"
    }
  ],
},
  • onClear: This event triggers when the page is cleared. It executes the “setDisabled” action, disabling the “spare_text_1” textbox.
 "onClear": [
    {
      "action": "setDisabled"
    }
  ]

  • onStateChange: There are separate onStateChange events for each page, accommodating the varied criteria for enabling or disabling components. These events ensure that the dynamic behaviour aligns with the individual requirements of “new-sales-order”, “view-sales-order”, and “amend-sales-order” pages.

    • “sop/amend-sales-order”: It watches the “document_no” state. If “document_no” is not empty, it triggers the “setEnabled” action; otherwise, it triggers the “setDisabled” action.
    {
  "pages": ["sop/amend-sales-order"],
  "onStateChange": [
    {
      "watchTarget": "document_no",
      "onChange": [
        {
          "if": {
            "ne": [
              {
                "get": {
                  "state": "document_no"
                }
              },
              {
                "string": {
                  "value": ""
                }
              }
            ],
            "then": [
              {
                "action": "setEnabled"
              }
            ],
            "else": [
              {
                "action": "setDisabled"
              }
            ]
          }
        }
      ]
    }
  ]
},
    • “sop/view-sales-order”: It watches the “document_no” state. If “document_no” is not empty, it triggers the “setReadOnly” action, making the “spare_text_1” component read-only.
    {
  "pages": ["sop/view-sales-order"],
  "onStateChange": [
    {
      "watchTarget": "document_no",
      "onChange": [
        {
          "if": {
            "ne": [
              {
                "get": {
                  "state": "document_no"
                }
              },
              {
                "string": {
                  "value": ""
                }
              }
            ],
            "then": [
              {
                "action": "setReadOnly"
              }
            ]
          }
        }
      ]
    }
  ]
},
    • “sop/new-sales-order”: It watches the “customer/id” state. If “customer/id” is greater than 0, it triggers the “setEnabled” action; otherwise, it triggers the “setDisabled” action.
    {
  "pages": ["sop/new-sales-order"],
  "onStateChange": [
    {
      "watchTarget": "customer/id",
      "onChange": [
        {
          "if": {
            "gt": [
              {
                "get": {
                  "state": "customer/id"
                }
              },
              {
                "string": {
                  "value": 0
                }
              }
            ],
            "then": [
              {
                "action": "setEnabled"
              }
            ],
            "else": [
              {
                "action": "setDisabled"
              }
            ]
          }
        }
      ]
    }
  ]
}