Implementing Custom Template Variable (TV) Input Types in MODX Revolution

The Problem: Standard TV Inputs Are Not Enough

MODX Revolution provides a robust set of Template Variables (TVs) for resource metadata, but standard inputs like text fields, lists, and checkboxes often fall short for complex data needs. For example, if you need a specialized color picker, a Google Maps coordinate selector, or a structured JSON editor, the default options force users to enter raw strings, increasing the risk of data entry errors and breaking frontend layouts.

The solution is to implement a custom TV input type. This allows you to define a specific UI component for the MODX Manager (backend) while controlling how that data is stored and rendered on the frontend.

Prerequisites

• MODX Revolution installed (Version 2.x or 3.x).
• Administrator access to the MODX file system via SSH or FTP.
• Basic proficiency in PHP and JavaScript for the Manager UI.

Developing the Custom TV Input

To create a custom TV type, you must define how the input is rendered in the Manager and how the value is processed. Avoid modifying core files; instead, place your logic within a custom component or a plugin directory to ensure updates do not overwrite your changes.

1. Define the Input Class

Create a PHP class that extends the base TV input functionality. This class handles the rendering of the HTML field within the Resource editor. In MODX, the system looks for specific input types registered in the database or loaded via plugins.

// Example conceptual structure for a custom input handler
class ModCustomColorPicker {
    public function getInput($tv) {
        // $tv contains the TV object and its current value
        $value = $tv->value;
        return '<input type="color" name="tv' . $tv->id . '" value="' . $value . '" />';
    }
}

2. Registering the Input Type

For your custom type to appear in the Input Option dropdown when creating a new TV, it must be registered. This is typically done by adding a record to the modx_tv_input_types table or using a system event plugin that hooks into the Manager's loading sequence.

3. Handling Data Persistence

MODX stores TV values in the modx_tv_values table. If your custom input collects complex data (like an array of coordinates), you must ensure the data is serialized before being saved. Use json_encode() or PHP's serialize() if you are overriding the save process via a plugin.

Example: Implementing a Range Slider TV

Suppose you need a "Priority" slider (1-100) for your resources. A standard text field allows users to enter "999" or "abc", which would break your CSS logic.

Component	Implementation Detail	Expected Result
Manager HTML	<input type="range" min="1" max="100">	Visual slider in Resource editor.
Validation	PHP intval() cast on save.	Database stores only integers.
Frontend Tag	[[*priority_tv]]	Outputs a number (e.g., "45").

Verification and Testing

After deploying your custom input type, perform these checks to ensure stability:

1. UI Check: Navigate to TVs in the MODX Manager. Create a new TV and check if your custom type appears in the Input Option dropdown.
2. Persistence Check: Open a Resource, enter a value using your custom input, and save. Refresh the page to verify the value persists.
3. Frontend Check: Place the TV tag (e.g., [[*your_tv_name]]) on a template. View the page in a browser to confirm the stored value renders correctly.

Limitations and Risks

• Security: Custom inputs that accept HTML or JSON must be strictly sanitized. Use $modx->getOption('script_execution', null, 'N') and appropriate escaping to prevent XSS attacks within the Manager.
• Performance: If your custom TV type performs external API calls (e.g., fetching a list of categories from a remote server) during the getInput phase, it will slow down the Resource editor loading time. Cache these values using the MODX cache system.
• Updates: Never modify files in core/model/. Always use the extras/ directory or a custom package to maintain upgradeability.

Rollback Procedure

If the custom TV type causes Manager crashes or data corruption:

1. Remove the custom PHP class files from the extras/ or plugin directory.
2. Delete the corresponding entry from the modx_tv_input_types table via phpMyAdmin or your SQL client.
3. Clear the MODX system cache (Manage -> Clear Cache) to restore the default input list.