Zoomed Image
USA
800 691 9120
UK
01225 704844

XCS Client Scripting

xAssets Configuration Guide
Integration and Data Operations with Transformations

XCS Client Scripting

XCS (xAssets Client Script) is the client-side scripting language for xAssets forms. Every form can have an associated XCS script that handles user interactions, field validation, and dynamic behaviour in the browser. This page provides an overview of XCS and explains how it fits into the transformation and scripting ecosystem.

Prerequisites

  • Familiarity with xAssets forms (see Forms Overview)
  • Understanding of the difference between client-side and server-side scripting
  • Access to the XCS source folder and the XCSLoad service

How XCS Fits In

Each form in xAssets can have up to three scripting layers:

Layer Language Runs Purpose
Form definition XDML Server Defines the layout and fields of the form
Form script AMSX Server Prepares data when the form loads (e.g., populating calculated fields, loading reference data)
Client script XCS Browser Handles user interactions after the form is displayed (e.g., button clicks, field validation, show/hide logic)

XCS scripts are stored as .vb files in the XCS source folder. The XCSLoad service compiles them into the database. The browser loads XCS scripts from the database when a form opens.

Important: XCS uses VB.NET-like syntax but it is not standard VB.NET. It is transpiled to JavaScript at runtime. See the syntax rules below for key differences.

Script Structure

Every XCS script follows this pattern:

Option Explicit On

Friend Class MyFormName
    Inherits XCSForm

    Private MyVariable As String

    Public Sub OnLoad()
        ' Runs when the form opens
        ' Register event handlers here
        EventHandler.On("click", "#mybutton", "OnButtonClick")
    End Sub

    Sub OnButtonClick()
        ' Handle button click
    End Sub

End Class

Key elements:

  • Option Explicit On is required at the top of every script
  • The class name must match the form name
  • Inherits XCSForm provides access to form APIs (field access, server calls, dialog management)
  • OnLoad() is called when the form first displays -- register all event handlers here
  • Event handlers are defined as Sub routines within the class

Working with Fields

Access form fields using Me.Fields:

' Read a field value
Dim c As XCSField = Me.Fields("AssetDesc")
Dim sValue As String = c.Value

' Set a field value
c.Value("New Value")

' Show or hide a field
c.Hide()
c.Show()

Event Handling

Register handlers for user interactions in the OnLoad subroutine:

' Click events
EventHandler.On("click", "#savebutton", "OnSave")

' Field change events
EventHandler.On("change", "StatusID", "OnStatusChanged")

' Table row selection
EventHandler.On("selectionchanged", "MyQuery", "OnRowSelected")

Supported event types include click, change, selectionchanged, pagechanged, keyup, RecordsDeleted, and searchrequery.

Server Communication

XCS can make server calls to refresh data, execute API commands, and open dialogs:

' Refresh a query embedded in the form
Server.Query("MyQueryName", True, True)

' Call an API method
Dim sResult As String = Server.API("apicommand", arg1, arg2)

' Open a dialog
Dim u As URL = URL.Build("a", "form", "MyDialogForm", "title", "Edit Record")
Server.Get("dialog", "", u, False)

' Close the current dialog
Server.CloseDialog()

Working with Queries

XCS can interact with query results displayed in tables on the form:

' Get a reference to a query
Dim q As XCSQuery = Me.Queries("AssetList")

' Get selected row IDs
Dim aIDs As Array = q.SelectedIDs("AssetID")

' Get a value from the last clicked row
Dim sDesc As String = q.LastRow.Value("AssetDesc")

Important Syntax Rules

XCS has specific syntax constraints that differ from standard VB.NET. Violating these rules will cause compilation errors or unexpected behaviour:

  1. No end-of-line comments. Comments must be on their own line, not after code on the same line.
  2. No single-line If statements. Always use the multi-line If / End If block syntax.
  3. No inline expressions. Resolve expressions to variables before using them in conditions.
  4. Dynamic field references. Use f.Value(x) method syntax, not f.Value = x assignment syntax, when the field name is in a variable.

Deployment

XCS files are deployed through the XCSLoad service:

  1. Save the .vb file to the XCS source folder
  2. XCSLoad detects the file change and pushes the script to the database
  3. Refresh the browser to pick up the updated script

Both XCSLoad and the xAssets web application must be running for XCS changes to take effect.

Tip: If your XCS change does not appear to take effect, check that XCSLoad is running and that the file was saved to the correct folder. A hard browser refresh (Ctrl+F5) may also be needed to clear cached scripts.

When to Use XCS vs. AMSX

Use Case Approach
React to a user clicking a button XCS event handler
Validate field values before save XCS change event
Show/hide fields based on user selections XCS with field.Hide() / field.Show()
Load data when a form opens AMSX form script (server-side)
Import data from external systems AMSX transformation (server-side)
Complex data processing or integration AMSX (see The AMSX Programming Language)

XCS handles client-side behaviour only. For server-side operations like database queries, data processing, and external API calls, use AMSX scripts.