Download the PHP package offsite-solutions/tholos without Composer

Tholos Framework

Tholos is a PHP component-based GUI framework built on top of the Eisodos framework. It provides a server-rendered, database-driven component architecture for building HTML applications with AJAX capabilities, PDF generation, role-based access control, and data caching.

Applications are designed visually using TholosBuilder (a companion web app) and compiled into .tcd (Tholos Component Definition) cache files that the Tholos runtime loads and renders.

Requirements

• PHP >= 8.4
• Eisodos framework (offsite-solutions/eisodos)
• Database: Oracle or PostgreSQL (via Eisodos connectors)
• Redis (optional, for caching)
• Extensions: json, mbstring, bcmath, pcntl, simplexml, zip, openssl, curl, redis

Installation

Architecture Overview

Bootstrap Chain

Access singletons via Tholos::$app (TholosApplication) and Tholos::$logger (TholosLogger).

Application Structure

Every Tholos application follows this component hierarchy:

Request Flow

1. Route Resolution -- tholos_route parameter selects the TRoute component
2. Action Resolution -- tholos_action parameter selects the TAction (default: index)
3. Initialization -- all components' init() is called; TRoute optionally runs InitSessionProvider
4. Auto-Open -- TDataProviders with AutoOpenAllowed=true execute their queries/procedures
5. Rendering -- recursive tree walk: each component's render() returns HTML; children are rendered first, their output passed as $content to the parent
6. Response -- output finalized based on TAction's ResponseType property

Component System

All components extend TComponent. Components are defined in TholosBuilder and compiled into .tcd files. At runtime, TholosApplication loads these definitions, instantiates the PHP classes, and calls their lifecycle methods.

Component Lifecycle

Properties

Each component has typed properties defined in TholosBuilder:

Properties are accessed via $component->getProperty('Name', $default) which automatically parses dynamic expressions.

Property Expression Language

Property values support a dynamic expression syntax that is resolved at runtime:

Reference expressions (@)

Defaults (|) -- cascading fallback chain:

If the parameter doesn't exist, the value false is used. Multiple defaults can be chained: @comp.prop|@other.prop|literal.

Concatenation (++) -- joins multiple expressions:

Chained property access (.) -- navigate through COMPONENT-type properties:

If DBField is a COMPONENT property, it resolves to that component, then reads Value from it.

Callback (%) -- calls a template callback function:

Events

Components define two types of events:

PHP Events (type=PHP) -- server-side, called during rendering:

• Referenced as Application\EventClass::methodName
• Called via Tholos::$app->eventHandler($component, 'eventName')
• The handler receives the sender component and can modify properties/response
• Common: onBeforeRender, onAfterRender, onAfterInit, onBeforeCreate

GUI Events (type=GUI) -- client-side JavaScript:

• Value is a JavaScript function call or component method reference
• Rendered into the HTML template as event_eventname parameters
• Client-side dispatch: Tholos.eventHandler(senderID, targetID, componentType, methodName, routePath, eventData, userParameters)

Role-Based Access Control

TRoleManager (optional child of TApplication) controls access:

• Each component can set a FunctionCode property
• At render time, checkRole() verifies the current user has that function code
• Use # as FunctionCode to require login without a specific role
• CSRF protection: enabled via CSRFEnabled, token in csrf_token_value parameter, header name in csrf_header_name

Component Reference

For the full, detailed component type reference (all properties, events, methods, inheritance, and parent constraints), see:

docs/Tholos_Component_Types.md

Below is a functional overview of each component category.

Layout & Structure

Navigation & Routing

Form Controls

All form controls extend TFormControl which extends TControl. Common properties: DBField (data binding), Value, Label, LabelSize, ControlSize, Placeholder, Readonly, Required, Visible, Enabled.

Data Layer

Grid System

TGrid renders tabular data with filtering, sorting, pagination, transposing, and Excel/chart export.

Key TGrid Properties:

Grid Child Components:

Grid Filtering (client-side):

Filters are submitted as parameters in the format gridname_f_N=columnname:relation:value (slots 1-99). Relations: =, <>, <, >, <=, >=, LIKE, IN, BETWEEN.

Grid AJAX Refresh:

TGrid_submit(sender, target, urldata) posts form data to the action URL, receives {html: "..."} JSON, and replaces the grid DOM. Emits masterDataChange for detail grids.

Composite Components

Map Components

PDF & Signatures

Parameters

Template System

Templates are located in assets/templates/tholos/ and processed by the Eisodos template engine.

Naming Convention

Template Variables

Every component's generateProps() makes these available to templates:

• $prop_* -- all component properties (lowercased name)
• $prop_ID -- full element ID: {renderID}_{Name} (e.g., TRI8a3f_btnSave)
• $prop_name -- component name
• $prop_componenttype -- component type name
• $prop_datavalues -- generated data-* HTML attributes
• $prop_route -- route/action path
• $prop_parent_name / $prop_parent_id -- parent info
• $content -- rendered child content
• $sender -- sender component name
• $Tholos_renderID -- current render ID
• $Tholos_nonce -- CSP nonce for inline scripts

Template Syntax

Built-in Callback Functions (TholosCallback)

Base Template Fragments

These fragments are included by most component templates:

• TComponent.properties -- renders <input type="hidden" data-*> for component data
• TComponent.basedata -- generates style and data-* attributes (handles visibility)
• TComponent.labelicon -- renders label with optional icon
• TFormControl.labelsize / TFormControl.controlsize -- Bootstrap column classes
• TControl.baseevents -- standard control event scripts
• TControl.customevents -- custom event binding scripts
• TControl.helpblock -- validation/help text block
• TContainer.baseevents -- container event scripts

Client-Side JavaScript API

TholosApplication.js

The global Tholos object provides the client-side framework:

Core Methods:

Component Methods (called via eventHandler):

TGrid.js

Grid-specific functions:

Grid Events (jQuery custom events):

• masterDataChange -- emitted when master grid selection changes (for detail grids)
• masterRefresh -- emitted when master grid refreshes
• onAfterRefresh -- triggered after grid AJAX refresh completes
• leavingChartTab -- triggered when switching from chart to grid view

Client-Side Libraries

• jQuery + jQuery UI
• Bootstrap 5
• Select2 (dropdown/autocomplete)
• Tempus Dominus (date/time picker)
• Chart.js (grid chart view)
• jQuery Resizable Columns (grid column resize)
• jQuery AJAXQ (request queuing)
• RichTextEditor (THTMLEdit)

Response Types

TAction's ResponseType property determines how the rendered output is delivered:

Caching System

Tholos supports three caching backends configured via Tholos.CacheMethod:

Cache Scope

• Private -- scoped to the current session (file prefix: {sessionID}_{cacheID})
• Global -- shared across sessions

TQuery Caching

Set on TQuery via Caching property:

CacheValidity sets lifetime in minutes. CacheSQLConflict controls behavior when cached SQL doesn't match current query: ReadCache, RewriteCache, or DisableCaching.

Cache File Structure

• {prefix}_{cacheID}.cache -- cached data (JSON)
• {prefix}_{cacheID}.index -- metadata (partition, validity, SQL hash, item count)
• {prefix}_{cacheID}@{partition}.cache -- partitioned cache segment

Configuration Parameters

Key Eisodos parameters used by Tholos (typically set in application config):

Application

Data Providers

Caching

Boolean Handling

PDF

Security

Debugging

Grid Defaults

TholosBuilder

TholosBuilder is a companion web application used to visually design Tholos applications. It provides:

• Visual Component Tree -- JSTree-based hierarchy editor for building component structures
• Property Editor -- type-aware property editing with validation
• Event Editor -- configure PHP and GUI event handlers with method references
• Wizards -- auto-generate common patterns:
  • Query Wizard -- creates TQuery + TDBFields from a SELECT statement
  • Stored Procedure Wizard -- creates TStoredProcedure + TDBParams from procedure signature
  • Grid Wizard -- creates TGrid + TGridColumns from a data source
  • Edit Form Wizard -- creates TForm + form controls from field definitions
• Compilation -- compiles the component tree into .tcd cache files and _tholos.init
• Version Control -- task-based change tracking with user assignment

Compilation Output

The compiler (compile2()) generates:

1. _tholos.init -- PHP file containing:

   • $this->componentTypes[] -- type definitions with inheritance
   • $this->componentTypeIndex[] -- type ID to class path mapping
   • $this->componentIndex[] -- component ID to metadata mapping

2. {RouteName}.tcd -- PHP file per route containing:

   • $this->componentDefinitions[] -- array keyed by component ID with:
     • pid -- parent ID
     • h -- type hierarchy path (e.g., TStoredProcedure.TDataProvider.TComponent)
     • o -- component name
     • p -- JSON-encoded properties ({n, t, v, c, d})
     • e -- JSON-encoded events ({n, t, v, m, p, c, i, a})
3. {RouteName}.tcs -- human-readable source representation (for version control)

Naming Conventions

• All PHP component classes are prefixed with T (e.g., TComponent, TGrid, TAction)
• Constructor parameters use trailing underscore: $componentType_, $id_, $parent_id_
• Component property and event keys are lowercased internally
• Element IDs in rendered HTML: {renderID}_{ComponentName} (e.g., TRI8a3f_btnSave)
• Component definitions use compact JSON keys: n (name), t (type), v (value), c (component_id), d (nodata)
• Template files follow: ComponentType.purpose.template pattern
• Grid filter parameters: gridname_f_N (N = 1-99)
• Grid state parameters: TGrid_PropertyName_ prefix