Custom HTML components

Reusable custom elements inside page views are provided by DomTemplate, which is documented in more detail at https://www.php.gt/docs/DomTemplate/HTML-Components/.

In WebEngine, custom HTML components let us write our own element names such as <main-menu> or <user-card> and define the underlying HTML in one reusable component file.

This is different from browser-defined Web Components. Here the component is expanded on the server while the page is being rendered, so the browser receives ordinary HTML in the final response.

Each component can also have its own PHP logic. When that logic runs, it receives a Binder that is scoped to the component's element, which keeps the binding work isolated to that component rather than the whole page.

When to use components

Components are useful when a fragment of HTML appears in many places and has a clear boundary of its own. Navigation menus, cards, callouts, profile summaries, and other small UI building blocks are all common examples.

They also help keep page views smaller. Instead of one long file containing every repeated block, the larger page can reference named components and stay focused on the overall document structure.

If a component needs its own focused logic, that logic can stay beside the component rather than being duplicated across several page files.

Component discovery

Component files live in the component directory, which by default is page/_component.

For a tag such as:

<main-menu></main-menu>

WebEngine looks for the component view at:

page/_component/main-menu.html

If component-specific logic is needed, the matching PHP file can live alongside it.

Good component boundaries

Components work best when they represent a repeated UI fragment with a clear purpose. They are less useful when every tiny piece of markup is turned into its own component and the page becomes difficult to read as a whole.

The scoped binder helps here. Because the component logic works within the context of the component element, it can bind values without reaching unexpectedly into the rest of the document.

---

HTML views can also be extended and kept tidy in page partials, and the view can be made dynamic by binding data to the DOM.