Skip to main content

tSM JEXL Basics

This chapter provides syntax basics of tSM JEXL language.

1. Introduction​

JEXL in tSM

  • JEXL (JavaScript Expression Language) in tSM is a lightweight, single-expression scripting tool that lets you customize and automate form behavior without deep programming skills.
  • It’s integrated into the tSM frontend, allowing you to manipulate data and control UI elements (e.g., show/hide fields or set default values).

Key Points to Remember

  • Single Expressions Only: tSM’s JEXL does not allow multiple statements or multiline scripts. You must fit all logic into one expression.
  • Simplified Conditionals: No traditional if blocks. Use comparison and logical operators (&&, ||, ==, etc.) to create conditions.
  • Context-Based: Most expressions rely on $context, which provides direct access to various form data and entity details.

2. Basic Syntax and Structure​

In tSM, a JEXL expression is one line and returns either a value or a boolean (true / false). Where you place the expression determines how tSM uses it:

  • Hidden Attributes: A return of true hides the component; false shows it.
  • Validation: A return of true means data is invalid; false is valid.
  • Default Values: The expression’s result becomes the field’s default value.
  • General Settings: Some attributes require a string/number; the expression’s return value is assigned directly.

2.1 Accessing $context Variables​

In tSM, the $context object is your main gateway to form inputs, entity details, user info, and more. There are two primary patterns you’ll see:

  1. $context.form

    • Used primarily in creation forms (when adding a new entity) or whenever you have a standard form open.
    • Standard or “built-in” fields might appear as $context.form.customerId, $context.entity.name, etc.
    • Custom fields—those a user or an admin has configured—live under chars:
      • $context.form.chars.myCustomField
      • $context.form.chars.discountValue

  2. $context.entity

    • Used primarily on entity detail pages (when viewing or editing an existing entity).
    • Standard or “built-in” entity fields might be $context.entity.customerSegment, $context.entity.key, etc.
    • Custom fields on the entity appear under chars:
      • $context.entity.chars.priorityLevel
      • $context.entity.chars.internalCode

The difference is simply where you are in tSM:

  • If you’re creating a new entity (e.g., new customer, new order), you typically find fields under $context.form.
  • If you’re on a detail page (e.g., a customer’s detail view), you typically find fields under $context.entity.

2.2 Operators​

You can use JavaScript-like operators inside your single-expression JEXL code:

  • Arithmetic: +, -, *, /, %
  • Comparison: ==, !=, >, >=, <, <=
  • Logical: && (AND), || (OR), ! (NOT)
  • String Concatenation: "Hello " + $context.form.name

3. Single-Expression Limitation​

No multi-line code or block statements are allowed. For instance, this is not allowed:

if ($context.form.age > 18) {
  return true;
} else {
  return false;
}

Instead, you must reduce it to one expression, such as:

$context.form.age > 18

For more complex scenarios, chain your logic:

($context.form.age >= 18 && $context.form.country == 'SK') || $context.form.hasConsent

4. Conditional Logic​

Conditional logic can be performed with:

  1. Logical AND/OR:
$context.form.customerSegment == 'B2B' && $context.form.purchaseAmount > 1000
  1. Ternary Operator (for an immediate choice):
$context.form.isNew ? 'New Registration' : 'Existing Registration'

5. Using Built-In Functions​

tSM provides a suite of built-in functions for date/time manipulation, arithmetic, data handling, and validation. You can call them directly in your JEXL expressions. Below are a few examples:

  • Date & Time: addTime(date, 1, 'days') adds a day to a given date.
  • Data: includes(array, value) checks if an array contains a value.
  • Arithmetic: sum(1,2,3) returns 6.
  • Validation: isValidEmail('user@example.com') returns true or false.

You can see the full list of functions (like compareDates, dateFormat, map, filter, etc.) in the Chapter III.

6. Debugging with the JEXL Console​

  1. Enable Debug Console: Turn it on in your user settings (if you have permission).
  2. Open the Console: A special icon appears on pages/forms that support the debug console. Click it to open.
  3. Real-Time Context: The console shows the current $context (including $context.form or $context.entity) so you can see exactly which fields exist.
  4. Test Expressions: Type a JEXL expression in the console to immediately see its evaluated result.

7. Best Practices​

  1. Keep Logic Brief: Since only one expression is allowed, avoid cramming too many conditions. Split complex logic across multiple fields or validations.
  2. Use Debug Console: Always test your expressions in the console to see $context.form, $context.entity, etc.
  3. Watch Validation Return Values: Remember that true in a validation context means “the input is invalid.”
  4. Handle Null/Empty: Check for null or empty values using built-in validators (e.g., isNullOrEmpty($context.form.chars.myField)).
  5. Name Fields Meaningfully: Descriptive field names (e.g., “customerSegment” vs. “custSeg1”) help you see at a glance what your expressions do.

8. Common Pitfalls​

  • Trying to Write Multiple Statements: Only one expression is allowed—no if { } blocks.
  • Confusing Validation Logic: A true return in validation means “show error.”
  • Ignoring .chars.: Remember that custom fields on forms or entities are often in $context.form.chars or $context.entity.chars.
  • Forgetting Where You Are: On creation forms, use $context.form; on detail pages, use $context.entity.

9. Conclusion​

By understanding how $context.form and $context.entity work (including their .chars. sub-fields), mastering single-expression logic, and leveraging tSM’s built-in functions, you can customize forms and pages for everything from simple hide/show rules to advanced data validation. Always keep these points in mind:

  1. One Line: Fit all logic into a single JEXL expression.
  2. Logical Operators: Combine conditions with && and ||.
  3. Built-In Functions: Use the robust date/time, data, arithmetic, and validation helpers.
  4. Debug Console: Your best friend for testing expressions in real time.
  5. Context Awareness: Know when to use $context.form vs. $context.entity, and don’t forget the .chars. structure for custom fields.