ReddRadar
Agent skill
umbraco-controllers
Understand and create controllers in Umbraco backoffice (foundational concept)
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/umbraco-controllers
SKILL.md
Umbraco Controllers
What is it?
Controllers are separate classes that contain or reuse logic across elements while maintaining connection to an element's lifecycle. A Controller is assigned to a Host Element and supports lifecycle methods (hostConnected, hostDisconnected, destroy) for managing side effects, timers, subscriptions, and cleanup. Controllers can host other controllers, enabling composition and reuse of functionality.
Documentation
Always fetch the latest docs before implementing:
- Main docs: https://docs.umbraco.com/umbraco-cms/customizing/foundation/umbraco-controller
- Write Custom Controller: https://docs.umbraco.com/umbraco-cms/customizing/foundation/umbraco-controller/write-your-own-controller
- Foundation: https://docs.umbraco.com/umbraco-cms/customizing/foundation
Workflow
- Fetch docs - Use WebFetch on the URLs above
- Ask questions - Need custom controller? What lifecycle events? What cleanup needed?
- Generate code - Implement controller extending UmbControllerBase based on latest docs
- Explain - Show what was created and how to host it
Minimal Examples
Basic Custom Controller
import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
export class MyController extends UmbControllerBase {
constructor(host: UmbControllerHost) {
super(host);
// Auto-registers with host
}
override hostConnected() {
super.hostConnected();
console.log('Controller connected!');
}
override hostDisconnected() {
super.hostDisconnected();
console.log('Controller disconnected!');
}
override destroy() {
super.destroy();
console.log('Controller destroyed!');
}
}
Timer Controller Example
import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
export class TimerController extends UmbControllerBase {
#timer?: number;
#secondsAlive = 0;
constructor(host: UmbControllerHost) {
super(host);
}
override hostConnected() {
super.hostConnected();
// Start timer when element connects to DOM
this.#timer = window.setInterval(this.#onInterval, 1000);
}
override hostDisconnected() {
super.hostDisconnected();
// Clean up timer when element disconnects
if (this.#timer) {
clearInterval(this.#timer);
}
}
#onInterval = () => {
this.#secondsAlive++;
console.log(`Controller active for ${this.#secondsAlive} seconds`);
};
override destroy() {
super.destroy();
if (this.#timer) {
clearInterval(this.#timer);
}
}
getSecondsAlive(): number {
return this.#secondsAlive;
}
}
Hosting a Controller in Element
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { TimerController } from './timer-controller.js';
export class MyElement extends UmbLitElement {
#timerController = new TimerController(this);
render() {
return html`
<div>
Active for: ${this.#timerController.getSecondsAlive()}s
</div>
`;
}
}
Manual Registration (Not Recommended)
export class MyManualController {
#host: UmbControllerHost;
constructor(host: UmbControllerHost) {
this.#host = host;
// Manual registration required
this.#host.addUmbController(this);
}
hostConnected() {
console.log('Connected');
}
destroy() {
// Manual deregistration required
this.#host.removeUmbController(this);
}
}
Controller with Context Access
import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
import { UMB_NOTIFICATION_CONTEXT } from '@umbraco-cms/backoffice/notification';
export class NotificationController extends UmbControllerBase {
async showSuccess(message: string) {
// Controllers can access contexts via getContext
const context = await this.getContext(UMB_NOTIFICATION_CONTEXT);
context?.peek('positive', { data: { message } });
}
}
Key Concepts
Host Element: Web component that hosts the controller (all Umbraco Elements can be hosts)
Lifecycle Methods:
hostConnected()- Called when host element connects to DOMhostDisconnected()- Called when host element disconnects from DOMdestroy()- Called when controller is permanently destroyed
Auto-Registration: Extending UmbControllerBase automatically registers/deregisters
Controller Composition: Controllers can host other controllers
Context Access: Controllers can consume contexts via getContext() and consumeContext()
Use Cases:
- Managing subscriptions and cleanup
- Handling timers and intervals
- Coordinating side effects
- Reusing logic across multiple elements
- Managing API calls and data fetching
API Calls: When making API calls from controllers, NEVER use raw fetch(). Always use a generated OpenAPI client configured with Umbraco's auth context. See the umbraco-openapi-client skill for setup.
That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?