← Back to Core Domains

4.5 View and Frontend Patterns

KMP renders CakePHP templates enhanced with Bootstrap 5, Stimulus, and selected Turbo Frames. JavaScript and CSS are built by Vite. Turbo Drive is disabled.

Rendering layers

Layer	Use
Layout	Page shell, landmarks, global navigation, asset entry points
Template	One controller action’s semantic page structure
Element	Small reusable, mostly presentational fragment
Cell	Reusable component that needs its own data-loading/render logic
Helper	HTML generation or view-specific formatting
Stimulus controller	Progressive behavior attached through data-controller
Turbo Frame	Focused server-rendered replacement region

Business workflows belong in services, not templates, helpers, cells, or JavaScript.

Assets

vite.config.js defines entry points and writes the manifest to webroot/.vite/manifest.json. AppView loads ViteHelper, and templates use that helper to resolve development or hashed production assets. Do not add Laravel Mix/Webpack manifest calls or hard-code built filenames.

Core Stimulus controllers live in app/assets/js/controllers and register through window.Controllers. Plugin controllers follow the plugin asset pattern and are imported by the controller entry point. Preserve existing controller identifiers and data attributes because templates and tests depend on them.

Plugin composition

Plugins contribute navigation and view content through NavigationRegistry and ViewCellRegistry. This keeps core templates independent of optional domains. For mixed core/plugin detail tabs, use the existing detail-tab registration and ordering conventions rather than hard-coding plugin tabs into a core template.

Turbo Frames

Use frames for bounded server-rendered updates such as tabs, forms, and modal content. A response intended for a frame must return the expected frame identifier and an accessible error state. Do not rely on Turbo Drive page lifecycle events; it remains disabled for compatibility.

Accessibility contract

User-facing changes target WCAG 2.2 Level AA:

• Use semantic landmarks, headings, lists, tables, buttons, and links.
• Give every input an accessible name and associate validation help/errors.
• Preserve visible focus and logical keyboard order.
• Use Bootstrap modal/tab APIs with their expected ARIA state.
• Announce asynchronous success, error, and loading changes through KMP_accessibility utilities.
• Do not encode state by color or icon alone.
• Mark decorative icons aria-hidden="true"; label meaningful icon-only controls.

Invoke the repository’s WCAG accessibility skill for templates, CSS, Stimulus, forms, modals, tabs, grids, navigation, or mobile UI changes.

Safe implementation checklist

1. Find a current template/controller with the same interaction.
2. Authorize and shape data in the controller/service.
3. Render semantic server HTML first.
4. Add Stimulus only for behavior that needs it.
5. Remove listeners and observers in disconnect().
6. Test keyboard operation, focus movement, labels, announcements, and failure states.
7. Run npm run test:js; run npm run dev when imports or bundles change.

See JavaScript Development for entry points and controller conventions.