Creating a Custom Input Field in ProcessWire to Extend the Admin Interface

Desired outcome

Create a reusable custom input field (e.g., a simple color picker) that appears in the ProcessWire admin, stores its value with a page, and can be accessed via the API.

Prerequisites

• ProcessWire 3.0.165 or newer installed.
• Access to the file system with write permission to /site/templates/.
• Administrator login to the ProcessWire admin.
• Basic PHP OOP knowledge.

Procedure

1. Create the field class file

In /site/templates/ create a new PHP file named InputfieldColor.php. This file will contain the field definition.

<?php
namespace ProcessWire;

class InputfieldColor extends Inputfield {
    /** @var string Default hex color */
    public $defaultValue = '#ffffff';

    /**
     * Define the field label and type.
     */
    public function ___init() {
        parent::___init();
        $this->label = 'Color Picker';
        $this->type = 'color';
    }

    /**
     * Render the HTML input.
     */
    public function ___render() {
        $value = $this->value ? $this->value : $this->defaultValue;
        return "<input type='color' name='{$this->name}' value='{$value}'>";
    }

    /**
     * Sanitize and store the submitted value.
     */
    public function ___processInput($inputData) {
        // Expect a hex color like #ff0000
        if (isset($inputData[$this->name])) {
            $val = trim($inputData[$this->name]);
            if (preg_match('/^#[0-9a-fA-F]{6}$/', $val)) {
                $this->value = $val;
            } else {
                $this->value = $this->defaultValue;
            }
        }
        return $this->value;
    }
}
?>

2. Make the field discoverable by ProcessWire

ProcessWire automatically loads classes from /site/templates/ that follow the Inputfield* naming convention. No extra registration is needed, but you must clear the system cache after adding the file.

1. Log in to the admin.
2. Navigate to Modules > Refresh (or click the refresh icon).
3. Confirm that no errors appear.

3. Add the field to a template

1. Go to Admin > Fields > Add New.
2. Set Label to "Background Color" (or any name).
3. Set Type to InputfieldColor (should appear in the dropdown).
4. Click Save.
5. Open the template where you want the field (e.g., Admin > Templates > basic-page > Fields).
6. Add the newly created field to the template and save.

4. Verify the field works

1. Create or edit a page using the template.
2. Locate the color picker input; it should render as a small color square.
3. Select a color, save the page.
4. After reload, the picker should show the selected color.
5. Retrieve the value via API in a template file:

<?php
$color = $page->background_color; // matches the field name
if ($color) {
    echo "<div style='background-color:{$color};width:100px;height:100px;'></div>";
}
?>

5. Expected checks

• The input appears without PHP errors or warnings.
• Selected color persists after page save.
• API returns the exact hex string stored.
• Invalid input (non‑hex) falls back to the default value.

6. Recovery / rollback options

If the field causes issues:

1. Remove the field from any template (Admin > Templates > [template] > Fields).
2. Delete the field definition (Admin > Fields > [field] > Delete).
3. Optionally delete /site/templates/InputfieldColor.php.
4. Refresh modules again to clear the class cache.

These steps revert the system to its prior state without affecting core files.

Limitations

• The example field does not include advanced features like alpha channel or swatches; extend the ___render() method for those.
• Heavy logic inside ___render() or ___processInput() can slow the admin interface; keep processing minimal.
• Always sanitize input; the regex shown is a basic safeguard but may need adjustment for other data types.

Summary

By following the steps above you have created a functional ProcessWire custom input field, verified its operation, and know how to roll back if needed. This pattern can be adapted for any specialized data type you need to expose in the admin.