Data Field Container

Overview

The CSS property allows you to define custom styles for this Data Field Container and all of its descendant data elements. Styles are written using standard CSS syntax, enabling you to control the appearance and layout of data elements in the Data Viewer and related UI components.

• Styles are defined as a series of rules, each consisting of a selector and a declaration block.
• Selectors target data elements by type or name, using class selectors (e.g., .DataField, .First_Name).
• Declaration blocks specify CSS properties and their values.

Relationship to Included Style Sheets

The final appearance of data elements is determined by combining:

• The 'Included Style Sheets' property on the Data Model, which specifies one or more global style sheets to be applied to all elements in the model.
• The 'CSS' property on each Data Element (including containers, fields, sections, and tables), which allows for local, element-specific styles or overrides.

At runtime, all style sheets listed in 'Included Style Sheets' are loaded and concatenated in the order specified. The local 'CSS' from each Data Element is then appended, producing a single block of qualified CSS. This ensures that both global and element-specific styles are applied.

• Use 'Included Style Sheets' for global or reusable styles that should apply across multiple Data Models or Content Types.
• Use the 'CSS' property for targeted customization or overrides on specific elements.
• The cascade and order of these sources determine the final appearance, with later and more specific rules taking precedence.

Selector Syntax

Selectors in this context are relative: they apply to descendants of this container. You can reference elements by their type name (e.g., .DataField, .DataSection) or by their element name (e.g., .First_Name).

• To select all descendant fields:
  .DataField
• To select a specific field by name:
  .First_Name
• To select immediate children only:
  self > .DataField
• To select this element itself:
  self

Selector Examples

Usage Guidance

• Use the CSS property to customize the appearance of data elements for improved clarity, accessibility, or branding.
• Combine selectors to target specific elements or groups of elements within complex, nested document schemas.
• You can use variables (such as the special variable CSS_Class) to dynamically assign CSS classes based on data values, enabling conditional formatting.
• For consistent branding and layout, define shared styles in 'IncludedStyleSheets' and use the 'CSS' property for exceptions or local adjustments.

Additional Resources

• See CSS Builder for more information on how included style sheets are combined the local CSS defined on Data Elements.
• CSS Reference on MDN
• CSS Syntax Guide
• CSS Properties Reference

Class names defined here may be used from style sheets, to set CSS properties for multiple elements using a single selector.

Example Use Cases

• Highlighting Required Fields: Assign a class such as required-field to visually distinguish fields that must be completed by the user.
• Conditional Formatting: Use dynamic class assignment to flag fields with missing or invalid data, or to indicate extraction confidence.
• Section or Table Styling: Apply a class to a Data Section or Data Table to style entire groups of fields, rows, or columns.
• Custom Themes and Branding: Combine 'CSSClass' with global or local style sheets to implement organization-specific branding, accessibility adjustments, or dark mode support.
• Workflow Indicators: Use class names to visually indicate workflow states, such as approved, pending-review, or rejected.

Best Practices

• Consistency: Define reusable class names in your style sheets to promote consistent appearance and behavior across your solution.
• Separation of Concerns: Use 'CSSClass' for presentation and UI logic, not for storing business data.
• Avoid Conflicts: Choose class names that do not conflict with built-in Grooper or third-party CSS to prevent unintended side effects.
• Dynamic Logic: Leverage dynamic class assignment for data-driven UI changes, such as highlighting based on extraction results or user actions.

Additional Notes

• The 'CSSClass' property is available on all Data Elements, including Data Fields, Data Sections, Data Tables, and Data Models.
• CSS class names are case-sensitive and must conform to standard CSS naming conventions.
• For more information and advanced scenarios, see the documentation for "CSS Data Viewer Styling".
• Use the 'CSS' property on a Data Field Container to define custom style rules that reference your class names, or include external style sheets at the Data Model or Content Type level for broader styling control.
• In addition to static class names, you can assign dynamic CSS classes to containers by including a string variable named "CSS_Class" on a Data Model, Data Section, or Data Table. This enables conditional styling based on data values, extraction results, or business logic. For example, you might highlight fields with validation errors or flag rows based on extracted content.

Overview

The 'Visible' property determines if a Data Element—such as a Data Field, Data Section, Data Table, or Data Model—is displayed in the Grooper Data Grid and other user interface components. When set to false, the element is hidden from the UI, but it remains part of the data model and can still participate in extraction, validation, and automation processes.

Behavior and Inheritance

• UI Presentation: If 'Visible' is set to false, the element and its children are not shown in the data entry or review panels. This is useful for fields that are used for internal calculations, lookups, or automation but should not be exposed to end users.
• Data Processing: Hidden elements are still included in extraction, validation, and export operations unless explicitly excluded by other configuration.
• Inheritance: The visibility of a parent element (such as a Data Section or Data Table) affects its descendants. If a container is hidden, all child elements are also hidden in the UI, regardless of their individual 'Visible' settings.
• Overrides: The 'Visible' property can be overridden for specific Content Types using property overrides, allowing you to tailor the UI for different document types or business scenarios.

Example Use Cases

• Internal Fields: Hide fields used for intermediate calculations, lookups, or automation that do not require user review.
• Conditional UI: Use property overrides to show or hide fields based on the Content Type or document classification.
• Simplified Data Entry: Hide advanced or rarely used fields to streamline the user experience for most users, while making them available for administrators or special workflows.
• Section and Table Visibility: Hide entire Data Sections or Data Tables to control the visibility of groups of related fields.

Best Practices

• Use the 'Visible' property to reduce UI clutter and focus user attention on relevant data.
• Combine with property overrides to create context-sensitive user interfaces for different document types.
• Remember that hidden elements are still processed during extraction and validation unless excluded by other means.

> Note: The 'Visible' property only affects user interface presentation. It does not remove the element from the data model or prevent it from being used in automation, scripting, or export.

Can be one of the following types:

The 'Display Label' property allows you to specify a custom label for this Data Field that will be shown in the user interface instead of the default field name.

This is especially useful for presenting user-friendly or context-specific labels, supporting localization, or providing dynamic labeling based on label sets.

How It Works

• If set, the display label appears in the UI (such as data entry forms and review screens) in place of the field's code name.
• If left blank, the field's name is used as the label.
• Enter /auto to enable dynamic labeling based on label sets, allowing the label to change depending on the document context or user selection.
• The display label is primarily used in the web client and may not affect all UI components.

Usage Notes

• The display label does not affect the field's code name, data binding, or extraction logic.
• This property is for presentation only and is ignored by backend processes.
• If label sets are not configured, /auto will fall back to the default field name.

The Fill Methods property specifies one or more Data Fill Methods that control how data is populated into the child elements of this container during extraction.

How Fill Methods Work

• Each fill method represents a strategy for populating Data Fields, Data Sections, or Data Tables, such as running extractors, performing lookups, or applying custom logic.
• Fill methods are executed in the order they appear in the list. The order can affect the final data values, especially if multiple methods target the same fields.
• The execution of each fill method can be made conditional using its 'Trigger' property, allowing for context-sensitive or event-driven population.
• If a fill method's 'Overwrite' property is enabled, it will replace existing values; otherwise, it will only populate empty elements.

Usage Guidance

• Use fill methods to automate extraction or implement custom data population logic for complex document schemas.
• Multiple fill methods can be combined to support advanced extraction workflows, such as running standard extractors first, then applying lookups or custom logic as needed.
• For most scenarios, configure fill methods on the Data Model, Data Section, or Data Table where the extraction logic should apply.

Related Concepts

• Data Fill Method: The object defining the extraction or population strategy.
• Data Model, Data Section, Data Table: Containers that can host fill methods.
• Lookup Specification, Data Rule: Additional mechanisms for data population and validation.

Each Lookup Specification defines a lookup operation, where the value of one or more Grooper fields will be used to query an external data source, such as a database. The results of the query can be used to validate existing field values or populate additional field values.

Lookup Specifications are executed at the following times:

• Immediately after Extract runs, all lookup specifications in the Data Model will be executed.
• When the value of a field is changed by a user, all lookup specifications referencing that field will be executed.
• When a user manually triggers a lookup to resolve a case where duplicate results were returned.

Purpose and Usage

• Use lookups to integrate external data sources for validation or population of Data Fields.
• Each Lookup Specification can be configured to run automatically, conditionally, or manually, depending on the extraction workflow.
• Lookups can enforce data integrity, auto-populate fields, or provide reference data for downstream processes.

Configuration Guidance

• Attach lookup specifications to a Data Model, Data Section, or Data Table to control which fields are available as criteria and targets.
• Specify criteria fields and target fields for each lookup, and configure trigger modes and error handling as needed.
• Multiple lookups can be configured and will be executed in the order they appear in the list.

Best Practices

• Use lookups to reduce manual data entry and ensure field values match authoritative sources.
• Carefully select trigger modes to balance automation and user control.
• Review error handling options to provide a smooth user experience.

Related Concepts

• Lookup Specification: Defines the lookup operation and its configuration.
• Data Field: The fields used as criteria or targets for lookups.
• Data Model, Data Section, Data Table: Containers that can host lookup specifications.

Variables are computed values which can be leveraged from expressions.

Purpose and Usage

• Variables provide dynamic, computed values that can be referenced in expressions throughout the data extraction and validation process.
• They can be used to drive conditional logic, calculations, or UI behaviors for this container and its descendants.
• Variables are especially useful for encapsulating reusable logic or values that may change based on document content or extraction results.

Defining and Using Variables

• Define variables by adding Variable Definition objects to this property.
• Each variable can reference other fields, variables, or expressions, and is evaluated in the context of the current data instance.
• Variables can be referenced in property expressions, validation rules, fill methods, and lookups using their name.

Special Variable Names and Dynamic Behaviors

• The special variable name CSS_Class can be used to dynamically assign CSS classes to this element, enabling UI customization based on data values.
• Variables can interact with extraction, validation, and UI logic, allowing for advanced scenarios such as dynamic field visibility, calculated values, or conditional formatting.

Practical Example

• Define a variable IsHighValue that returns true if the "Amount" field is greater than 1000, and use it to trigger a validation rule or highlight the field in the UI.

Related Concepts

• Variable Definition: The object defining the variable's logic and value.
• Data Model, Data Section, Data Table: Containers that can host variables.
• Expressions, validation rules, fill methods: Features that can reference variables for dynamic behavior.

The Validate Rule property allows you to attach a Data Rule that will be executed whenever this container or its descendants are validated.

How It Works

• The rule is triggered automatically during validation events, such as when a user edits a field, when extraction completes, or when validation is performed programmatically.
• The rule can be used to enforce business logic, perform cross-field validation, or trigger additional data actions based on the state of the container and its child elements.
• If the rule's 'Scope' does not match this container, a validation error will be reported.

Usage Guidance

• Use this property to centralize complex validation logic that involves multiple fields, sections, or tables within the container.
• The Data Rule can include conditional logic, custom error messages, and data actions to correct or flag invalid data.
• For simple, field-level validation, use the 'Validate Expression' property on individual Data Fields instead.

Related Concepts

• Data Rule: Defines the validation or data manipulation logic to be executed.
• Data Model, Data Section, Data Table: Types of containers that can host a validation rule.

Overview

The 'Rubberband OCR Profile' property specifies the OCR Profile to use when performing "rubberband" OCR operations on this Data Element. Rubberband OCR refers to user-initiated or programmatic extraction of text from a specific, interactively selected region of a document image—typically by drawing a rectangle ("rubberbanding") around the area of interest in the Grooper Data Grid or other UI components.

Behavior and Inheritance

• Profile Selection: If set, this property determines which OCR Profile is used for OCR processing when a user selects a region for ad-hoc text extraction. If not set, the system will use the parent element's 'RubberbandOcrProfile', or fall back to a default profile if none is specified in the hierarchy.
• Granular Control: Assigning different OCR Profiles to individual Data Fields, Data Sections, or Data Tables allows for fine-tuned OCR settings based on the content, language, or expected quality of specific document regions.
• Overrides: The 'RubberbandOcrProfile' property can be overridden for specific Content Types using property overrides, enabling document-type-specific OCR strategies.

Example Use Cases

• Mixed-Language Documents: Assign a different OCR Profile to fields or sections that contain text in a different language or script.
• Specialized Zones: Use a custom OCR Profile for regions with unique formatting, such as barcodes, handwriting, or low-quality print.
• User-Driven Extraction: When users manually select a region for OCR in the UI, the specified profile ensures the most accurate recognition for that context.

Best Practices

• Assign a OCR Profile only when the default or inherited profile is not optimal for the specific data element.
• Use property overrides to adapt OCR settings for specialized document types or scenarios.
• Test the effectiveness of different profiles on representative samples to ensure optimal extraction accuracy.

> Note: The 'Rubberband OCR Profile' property only affects OCR operations performed via region selection (rubberbanding) in the UI or automation. It does not impact standard extraction logic unless that logic explicitly invokes rubberband OCR.