Variable Definition

From Grooper Wiki
Revision as of 13:34, 20 October 2025 by Dgreenwood (talk | contribs) (→‎CSS_Class: Conditionally style Data Elements)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Variable Definitions define a variable with a computed value that can be called by various code expressions. Variable Definitions are added to Data Models, Data Sections and Data Tables using their "Variables" property

Used By: Data Model, Data Section, Data Table

You may download the ZIP(s) below and upload it into your own Grooper environment (version 2025). It contains one or more Projects with resources used in examples throughout this article.

Overview

Variable Definitions provide a powerful way to create named, reusable values that are calculated dynamically using code expressions. Variables can be referenced throughout your Data Model, Data Section, Data Table, and other configuration objects to drive logic, formatting, automation, and conditional behavior.

Variables are not static. They are computed at runtime based on the logic you define. This makes them ideal for scenarios where you need to calculate totals, derive values, perform conditional checks, or format data for display and export.

What are Variables for?

Variables serve several key purposes in Grooper:

  • Calculation: Compute values such as totals, differences, or derived fields based on other data elements.
  • Reusability: Define logic once and reference it in multiple places, reducing duplication and improving maintainability.
  • Conditional logic: Drive workflow, validation, or formatting based on dynamic conditions.
  • Formatting: Control how numbers or dates are displayed using custom format strings.

Key properties

A Variable Definition consists of several key properties:

  • Name: The unique identifier for the variable. This is how you reference the variable in expressions and throughout your configuration. Names must be code-friendly (letters, numbers, and underscores only, starting with a letter or underscore).
  • Type: The data type of the variable (e.g., Boolean, DateTime, Decimal, Double, Guid, Int16, Int32, Int64, Object, Single, String, or TimeSpan). The type determines how the value is evaluated and formatted.
  • Is Array: Indicates whether the variable represents a single value or a collection (array) of values.
  • Expression: The logic used to calculate the variable's value. Expressions can reference other fields, variables, or built-in functions, and can include arithmetic, string manipulation, and conditional logic.
  • Number Format: (Optional) Controls how numeric values are displayed. Use standard or custom .NET numeric format strings (e.g., c2 for currency, n0 for whole numbers).
  • Date Format: (Optional) Controls how date and time values are displayed. Use standard or custom .NET date/time format strings (e.g., yyyy-MM-dd for ISO dates).
  • Description: (Optional) A place to document the purpose and logic of the variable.

When Grooper processes a document, it evaluates each variable's expression in the context of the current data. The result is available for use in other expressions, validation rules, formatting, and automation.

How are Variables created?

Variable Definitions can be added to any Data Field Container using the "Variables" property. This includes:

To create a new Variable Definition:

  1. Select the Data Model, Data Section, or Data Table.
  2. Open the "Variables" editor (Press the "..." button).
  3. Press the Add button (add_circle) to create a new Variable.
  4. Fill in the required properties:
    • Name: Enter a unique, code-friendly name.
    • Type: Select the appropriate data type.
    • Is Array: Set to "True" if the variable should be an enumeration of multiple values. Otherwise, leave as "False".
    • Expression: Enter the logic to compute the variable's value. You can reference Data Elements in scope, other variables, and/or use built-in functions.
      • If you open the "Expression" editor, Grooper's code completion will assist you. As you type, members in scope will appear in the code completion list.
  5. (Optional) Set "Number Format" or "Date Format" to control how the value is displayed.
  6. (Optional) Enter a "Description" to document the variable's purpose.
  7. Click "OK" when finished.
  8. Press the Save button (save) to save your changes.

Example

Suppose you have a Data Table named "Line Items" with columns "Quantity" and "Unit Price". You can define a variable named TotalAmount with the following properties:

  • Name: TotalAmount
  • Type: Decimal
  • Expression:
(From row In Line_Items Select row.Quantity * row.Unit_Price).Sum
  • Number Format: c2 (to display as currency)

This variable will automatically calculate the total amount for all line items and display it in currency format.

What can use Variables?

Variables are referenced (or "called") in code expression editors. The Variables must be in scope in order to be called. The following is a comprehensive list of every object and property in Grooper that can reference (or "call") a variable.

Data Field and Data Column properties that can call Variables:

  • "Calculated Value"
  • "Is Valid"
  • "Validate Message" (Available when "Is Valid" expression is configured)
  • "Is Required"

Data Rule properties that can call Variables:

  • "Trigger"
  • True and False Data Actions can also call Variables:
    • "Calculate Value > Value Expression"
    • "Append > Trigger"
    • "Copy > Trigger"
    • "Remove > Trigger"
    • "Concat > Trigger"
  • BE AWARE: Access to Variables is determined by the Data Rule's "Scope" assignment, the Append action's "Source Element" assignment, the Copy action's "Source Element" assignment, the Concat action's "Collection" assignment and/or the Remove action's "Collection" assignment.

Export Definition properties that can call Variables:

  • File Export properties:
    • "Relative Path"
  • Data Export properties:
    • "Table Mappings > Column Mappings > ColumnName > Expression" (Access to Variables is determined by the Table Mapping's "Source Scope" assignment)
    • "Custom Statements > Statement" (Access to Variables is determined by the Custom Statement's "Source Scope" assignment)
  • CMIS Export properties:
    • "Subfolder Path"
    • Read Mapping expressions
    • Write Mapping expressions
  • BE AWARE: Only Data Model Variables are accessible.

Lookup Specification properties that can call Variables:

  • "Trigger" (when "Trigger Mode" is set to Custom)
  • Database Lookup
    • "SQL Query" (Variables can be called with "@VariableName" in the WHERE clause)
  • CMIS Lookup
    • "CMIS Query" (Variables can be called with "@VariableName" in the WHERE clause)

Fill Method properties that can call Variables:

  • "Trigger"

Variable Definitions themselves can reference other Variables in scope (including those defined earlier in the same container).

Best practices

  • Use descriptive, code-friendly names to avoid conflicts and make your configuration easy to understand.
  • Test your expressions thoroughly to ensure they produce the expected results.
  • Use the formatting properties to control how values appear in the UI or exported data.
  • Document each variable's purpose using the "Description" property.
  • Reference variables in other expressions to build complex logic in a maintainable way.

CSS_Class: Conditionally style Data Elements

You may download the ZIP(s) below and upload it into your own Grooper environment (version 2025). It contains one or more Projects with resources used in examples throughout this article.

This ZIP contains the two examples detailed in this section.


"CSS_Class" is a reserved Variable name that serves a special purpose.

It allows you to dynamically style "container" elements (Data Models, Data Sections, and Data Tables) at runtime, using CSS class names defined in their Style Sheets. By defining a Variable with the name CSS_Class, you can control the visual styling of data elements in the user interface based on data values, extraction results, or other custom logic.

  • Typically an If expression is used.
    • Example: If(condition,"css-class-assigned-if-true","")
    • Example: If(condition,"css-class-assigned-if-true","css-class-assigned-if-false")
    • Do I have to use an If expression? No. As long as the expression evaluates to a class name, it will be added to the container.

This enables powerful, data-driven UI customization—such as highlighting sections with errors, flagging important records, or applying conditional formatting—without hardcoding class names.

Common examples:

  • Conditionally show/hide Data Fields based on Data Field values.
  • Visually distinguish records or sections that meet/don't meet certain criteria.
  • Highlight date fields past a certain date, such as overdue invoices.

Example

Style Sheet entry CSS_Class Variable expression Data Viewer result 
.highlighter .Total input {
  background-color: yellow;
  color: black;
}

If(Total > 9000, "highlighter", "")
If expression's condition is false
  • false condition = ""
  • No class is added to the container.

If expressions's condition is true

  • true condition = "highlighter"
  • highlighter class is added to the container.


How does it work?

When a variable named CSS_Class is defined in the "Variables" collection of a Data Field Container, Grooper evaluates its expression for each instance of that container. The resulting value (a string) is used as an additional CSS class for that element and its descendants in the Data Viewer and related UI components.

  • The value of the CSS_Class variable can be a single class name or a space-separated list of class names.
  • The variable's expression can reference any fields, variables, or logic available in the current context.
  • The assigned class(es) are combined with any static class names set in the Data Element's "CSS Class" property and those defined by the Data Element's type (Data Model, Data Section, Data Table, etc.) or name.

How to define the "CSS_Class" variable

Prerequisites

  1. All Data Elements (Data Fields etc.) that are referenced must be added to the Data Model.
  2. Data Fields and Data Columns must have their "Value Type" properly configured.
    • This will ensure conditions will evaluate correctly when performing numeric, date, or string comparisons.
  3. The CSS class and associated rules are already present in the target Data Model, Data Section, or Data Table's "Style Sheet" (or the Data Model's referenced "Included Style Sheets").
    • Example: If the CSS_Class variable is conditionality highlighting a "Total" Data Field, using a class named highlighter the Style Sheet might have a rule like this:
.highlighter .Total input {
  background-color: yellow;
  color: black;
}

Add the CSS_Class variable

  1. Select the Data Model, Data Section, or Data Table you want to add the CSS_Class variable to.
  2. Open the "Variables" editor (Press the "..." button).
  3. Press the Add button (add_circle) to create a new Variable.
  4. Set the Name property to CSS_Class (case-sensitive, must match exactly).
  5. Set the Type to String.
  6. Using the Expression property, enter a code expression that returns the desired class name(s). This can reference fields, other variables, and use If expressions to define the conditional logic.
    • Example: Apply the highlighter class if the "Total" Data Field's value is over 9,000. Otherwise, don't apply a class.
If(Total > 9000, "highlighter", "")
  2. (Optional) Add a "Description" to document your logic.
  3. Click "OK" when finished.
  4. Press the Save button (save) to save your changes.

Example: Hide a field based on another field's value

Conditionally displaying fields can assist users performing Review tasks. If they don't need to verify Field A because the value of Field B makes it irrelevant, save them some eye strain and just get it off the screen.

In this example, we will hide a "Spouse Name" field if a "Marital Status" field's value is "Single".

  1. Add CSS rules for a hide-me class in the Data Model's Style Sheet.
.hide-me .Spouse_Name {
  display: none;
}
  2. Select the Data Model (or Data Section) that contains the "Marital Status" and "Spouse Name" Data Fields.
  3. Open the Variables editor and add a new Variable.
  4. Configure the following:
    • Name: CSS_Class
    • Type: String
    • Expression: If(Marital_Status = "Single","hide-me","")

With this configuration, "Spouse Name" will be hidden if "Marital Status" is "Single". Otherwise, it will be visible.

When "Marital Status" is "Married", "Spouse Name" is visible.
No class is added to the container

When "Marital Status" is "Single", "Spouse Name" is hidden.
The hide-me class is added to the container.

Example: Highlighting a section with missing required fields

Grooper can set Data Fields and Data Columns to be "Required". They will be highlighted in the Data Viewer if they are missing.

Imagine you want to go a step further and highlight the entire Data Section with the missing field. You can do that with the CSS_Class variable.

In this example, we will add a red border around an "Email" Data Field's parent Data Section if the field is empty.

  1. Add CSS rules for a missing-email class in the Data Model's Style Sheet.
.missing-email {
  border: 4px solid #ed2330 !important;
  border-radius: 4px;
  padding: 8px;
}
  2. Select the Data Section that contains the "Email" Data Field.
  3. Open the Variables editor and add a new Variable.
  4. Configure the following:
    • Name: CSS_Class
    • Type: String
    • Expression: If(String.IsNullOrWhiteSpace(Email), "missing-email", "")

With this configuration, the Data Section will be given a red border when the Email field is empty.

When "Email" has a value, no border.
No class is added to the container

When "Email" is missing, red border.
The missing-email class is added to the container.

What if I want to apply multiple CSS classes?

Just make sure the class names are separated by a space character.

Example: 

If(condition, "class1 class2", "")

What if I want to execute multiple conditions?

To execute multiple conditions, you just need to make sure the expression evaluates to the right string. You will:

  • Concatenate multiple If expressions.
  • Ensure class names are buffered by space characters on either side. This will ensure multiple class names are added with spaces separating each name.
  • You may need to use the ToString method to properly satisfy the expression.

Example: 

If(condition1, " class1 ", "").ToString + 
If(condition2, " class2 ", "").ToString + 
If(condition3, " class3 ", "").ToString +
Retrieved from "https://wiki.grooper.com/index.php?title=Variable_Definition&oldid=31445"