In October CMS 4.x, a custom backend form field widget is a plugin class that renders a control, loads its current value, and—unless it is display-only—returns data for saving. Scaffold it with Artisan, extend BackendClassesFormWidgetBase, register its alias in the plugin, and reference that alias in fields.yaml.
When to build a custom form widget
October CMS describes a form widget as “a widget specifically made for use as a form field.” It adds a new control type to backend forms and usually interacts with a model by loading and saving a value. See the October CMS 4.x Form Widgets guide.
- Use a native field when it already provides the input and behavior you need; it requires less custom code.
- Build a widget when you need a new control type, specialized UI, or custom save behavior.
Scaffold the widget in a plugin
From the October CMS project, run the documented Artisan generator, replacing the example author and plugin with your own:
php artisan create:formwidget Acme.Blog ColorPickerThe generator places the widget class and its partials and assets in the plugin structure. Keep the class, view partials, JavaScript, and CSS in their generated locations so October CMS can load them as intended. The command and structure are documented in the 4.x Form Widgets guide.
Recommended Free Tools
#1 Best Overall
Implement the widget class
Extend BackendClassesFormWidgetBase, provide a unique alias, define any configurable properties, and load the configuration in init(). In render(), obtain the field identifier, submitted field name, and current value, then pass them to a partial.
<?php namespace AcmeBlogFormWidgets;
use BackendClassesFormWidgetBase;
class ColorPicker extends FormWidgetBase
{
protected $defaultAlias = 'colorpicker';
public function init()
{
$this->fillFromConfig([
'mode',
]);
}
public function render()
{
$this->vars['id'] = $this->getId();
$this->vars['name'] = $this->getFieldName();
$this->vars['value'] = $this->getLoadValue();
return $this->make partial('colorpicker');
}
}The example illustrates the documented class shape; adapt the namespace and partial name to the generated plugin files. Declare every YAML option your widget accepts in the configuration passed to fillFromConfig(). The official widget guide covers the lifecycle and API methods: Form Widgets.
Render values safely in the partial
In the partial, use the provided identifier and name for the input attributes, and escape the loaded value before placing it in HTML. Values from a model or request should not be interpolated into markup without escaping.
<input
id="<?= e($id) ?>"
name="<?= e($name) ?>"
value="<?= e($value) ?>"
>October CMS’s form-widget example uses e($value) when rendering the input value. Consult the official rendering example when adapting markup or asset behavior.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsRank #3
Choose what gets saved
For an ordinary input, the widget’s standard save path can pass the submitted value through. Override getSaveValue($value) when the widget must normalize or transform it—for example, to store a canonical representation rather than the exact text entered.
public function getSaveValue($value)
{
return strtoupper(trim($value));
}This transformation is only illustrative; choose normalization appropriate to the widget’s data contract. For a display-only control that must not write to the model, return FormField::NO_SAVE_DATA from getSaveValue(). The official save-value guidance is in the Form Widgets guide.
Register the widget and use it in fields.yaml
Register a class-to-alias mapping in the plugin’s Plugin.php using registerFormWidgets(). Once registered, the alias can be used as a field’s type. Alternatively, a field definition can refer directly to the widget class.
public function registerFormWidgets()
{
return [
AcmeBlogFormWidgetsColorPicker::class => 'colorpicker',
];
}fields:
accent_color:
label: Accent color
type: colorpicker
mode: hexAliases keep YAML concise and separate form configuration from PHP class names. A fully qualified class reference is more explicit and can be useful for a one-off integration. Both approaches are supported by October CMS form definitions; see the widget guide and form widget field reference.
Free tools Windows power users keep installed
One-click scans. No signup required.
Pass options and add dynamic behavior
Widget configuration belongs alongside the field’s type. For example, a date-oriented widget can receive mode, minDate, and maxDate, provided the class declares and loads those properties. YAML field definitions also support behavior beyond static options:
trigger: use browser-side field conditions and events to show, hide, or change state in response to another field.dependsOn: declare fields that cause server-side recalculation or AJAX refreshes when their values change.- Nested fields: define fields in a nested structure where the form’s data model calls for it.
Triggers and dependencies solve different problems: triggers handle client-side form state, while dependsOn supports server-side updates. The available options and syntax are described in the form widget field reference and form field reference.
When to add fields programmatically
For forms assembled at runtime or extended by other code, October CMS’s Form API provides addField() and addFields(). Registered widget fields are processed by the form, while the WidgetManager supports manual registration and alias resolution for extensions. Prefer a YAML definition for a stable, declarative form; use the API when the field set genuinely needs to be built or altered programmatically. See the Form Widgets guide and Form Controller API.
Check version compatibility
The implementation described here targets October CMS 4.x. October’s 3.x and 2.x form references may differ, so verify the widget lifecycle, registration method, and YAML options against the documentation for the major version your project runs before adapting the code.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
