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:

tip

Plain JSON is a valid JEXL expression. Object literals like { "key": "value" } and arrays like [1, 2, 3] can be used directly — there is no need to wrap them in jsonParse().

• 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

2. 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: array.includes(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.