From 6d31c0854bf40a2e29684a80ca7a97043dd37388 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Sun, 10 May 2026 05:13:41 +0000 Subject: [PATCH 1/4] docs(web/guides): add Debug Panel guide covering each tab and configuration --- CHANGELOG.md | 3 + .../digging-deeper/debug-panel.mdx | 205 ++++++++++++++++++ .../v4-0-0-snapshot/digging-deeper/index.mdx | 5 + 3 files changed, 213 insertions(+) create mode 100644 web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/debug-panel.mdx diff --git a/CHANGELOG.md b/CHANGELOG.md index 944364728f..1781e552d4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,9 @@ All historical references to "CFWheels" in this changelog have been preserved fo ### Added +**Documentation** +- Add Debug Panel guide covering each tab, configuration settings, and when the bar appears + **ORM & data layer** - Chainable query builder with `where()`, `orWhere()`, `whereNull()`, `whereBetween()`, `whereIn()`, `whereNotIn()`, `orderBy()`, `limit()`, and more for injection-safe fluent queries (#1922) - Enum support with `enum()` for named property values, auto-generated `is*()` checkers, auto-scopes, and inclusion validation (#1921) diff --git a/web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/debug-panel.mdx b/web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/debug-panel.mdx new file mode 100644 index 0000000000..c98faa1091 --- /dev/null +++ b/web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/debug-panel.mdx @@ -0,0 +1,205 @@ +--- +title: Debug Panel +description: The built-in development debug bar — what each tab shows, how to configure it, and when it appears. +type: howto +sidebar: + order: 11 +--- + +import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; + +The Debug Panel is a fixed bar that Wheels appends to every HTML response in development mode. It surfaces request details, execution timing, parameters, environment configuration, installed packages, and links to built-in tools — without leaving the page you are working on. The panel is rendered by `vendor/wheels/events/onrequestend/debug.cfm` and runs at the very end of the request lifecycle, after your controller and views have finished. + +**You'll learn:** + +- When the debug bar appears and how to control it +- What each tab shows and which configuration drives it +- How to read the timing breakdown to find bottlenecks +- Where to find package and plugin status +- How to access developer tools from the bar + +## When the debug bar appears + +The bar only renders for standard full-page HTML requests. It is automatically suppressed for any of the following: + +- AJAX requests (`X-Requested-With: XMLHttpRequest`) +- HTMX requests (`HX-Request`) +- Turbo Frame requests (`Turbo-Frame`) +- Fetch requests (`X-Fetch: true`) +- Requests that produce structured output (`?format=json`, `xml`, `csv`, or `pdf`) + +This means AJAX-driven partial updates, Turbo Streams, API endpoints, and CSV exports all receive clean responses with no injected HTML. + +## Enabling and disabling + +The bar respects the `enableDebug` application setting. By default, Wheels sets this to `true` in the `development` and `testing` environments and `false` in `production` and `maintenance`. You can override it explicitly in `config/environment.cfm`: + +```cfm title="config/environment.cfm" + +``` + +Setting `enableDebug=false` removes the bar entirely — no HTML is injected into responses. + + + +## The debug bar + +When active, the bar appears as a slim strip pinned to the bottom of the browser window. Tabs are arranged from left to right: a Wheels logo (doubles as the Request tab toggle), then Request, Timing, Params, Environment, and optionally Tools. The right side shows the current git branch (when Wheels detects a `.git` directory), the framework version, and a one-click reload link when no reload password is configured. + +{/* screenshot: the collapsed debug bar across the bottom of a browser window, showing all tabs and the git-branch + version on the right */} + +Clicking any tab opens a panel above the bar. Clicking the same tab again closes it. The minimize button (×) collapses the bar to a small "Debug" button in the corner, persisted via `sessionStorage` so it stays collapsed as you navigate. + +## Request tab + +The Request tab label shows `controller.action` for the current request. Clicking it opens a key-value panel with: + +| Field | Description | +|---|---| +| Route | Named route that matched this request (omitted when no named route matched) | +| Controller | Controller name | +| Action | Action name | +| Key | URL key segment, if present | +| HTTP Method | `GET`, `POST`, `PUT`, `DELETE`, etc. | +| URL | Full URL for this request | +| Application | Value of `applicationName` from `Application.cfc` | +| Data Source | The configured `dataSourceName` | +| DB Adapter | The active database adapter (MySQL, PostgreSQL, SQL Server, etc.) | +| URL Rewriting | Current URL rewriting mode | + +{/* screenshot: Request panel open — the key-value table showing Route, Controller, Action, HTTP Method, URL, Application, Data Source, DB Adapter, and URL Rewriting */} + +Use this panel to confirm that routing resolved the way you intended, that the correct data source is in use, and that URL rewriting is configured as expected. + +## Timing tab + +The Timing tab label shows the total request duration in milliseconds, color-coded by threshold: + +- **Green** — under 100 ms +- **Yellow** — 100–499 ms +- **Red** — 500 ms or more + +Opening the panel shows a horizontal bar chart breaking down where time was spent. Each phase (model, queries, template rendering, etc.) is sorted by duration descending and rendered as a proportional colored bar showing both the raw milliseconds and the percentage of total time. + +{/* screenshot: Timing panel open — horizontal bar chart with phases (model, queries, template) color-coded and sorted by duration, total ms shown in the header */} + +The chart is most useful for spotting query-heavy actions: if `queries` or `model` accounts for 80%+ of total time, look at the SQL being generated (the Routes admin page lists query counts per action if you need more detail). + +## Params tab + +The Params tab shows the count of extra request parameters as a badge. Opening the panel displays a table of every parameter that was available to the action, excluding the routing parameters (`controller`, `action`, `key`, `route`) and `fieldnames`. + +| Column | Description | +|---|---| +| Name | Parameter key, lowercased | +| Value | The value; complex values (structs, arrays) are JSON-encoded | +| Type | `string` or `json` | + +{/* screenshot: Params panel open — table with Name, Value, Type columns, showing a mix of string and json-type parameters */} + +This is the fastest way to confirm that form fields, query string values, and nested structs arrived the way you expected before you reach for a `writeDump` call. + +## Environment tab + +The Environment tab label shows the current environment name (Development, Testing, etc.) with a color-coded dot matching the timing badge palette. The panel is divided into subsections based on what is enabled. + +### Application + +Always shown. Lists the environment, the git branch (when the app root contains a `.git` directory), the Wheels version, the CFML engine and version, and the host name (when available). + +When no reload password is set, the environment name is followed by quick-switch links that reload the app in a different environment mode. This is useful during development to test environment-specific code paths without editing config files. + +{/* screenshot: Environment panel open, Application section — showing environment dot, git branch, Wheels version, CFML engine, with environment-switch links */} + +### Packages + +Shown when `enablePackagesComponent` is `true` (the default in Wheels 4.0+). Displays two tables. + +**Installed packages** lists every package found in `vendor/` and loaded by `PackageLoader.cfc`: + +| Column | Description | +|---|---| +| Package | Package name from `package.json` | +| Version | Semver version string | +| Description | One-line description | + +If any package failed to load (manifest error, missing dependency, CFC exception), a red error list appears below the installed table with the package name and the exception message. + +**Available from registry** pulls the same 24-hour cached registry index used by the `wheels packages` CLI and shows what is available to install: + +| Column | Description | +|---|---| +| Package | Name, linked to the package homepage when available | +| Latest | Latest compatible version | +| Description | Registry description | + +{/* screenshot: Packages section of the Environment panel — Installed table on top showing two packages, Available from registry table below listing several first-party packages */} + +This lets you discover first-party packages such as `wheels-hotwire`, `wheels-sentry`, or `wheels-i18n` without leaving the app. The table reflects the same 24-hour cache as `wheels packages list`; run `wheels packages registry refresh` from the CLI if you need up-to-the-minute data. + +### Plugins (legacy) + +Shown when `enablePluginsComponent` is `true`. Lists plugins installed in the legacy `plugins/` directory with their names and versions. Legacy plugins are the Wheels 3.x predecessor to packages — if you are on a fresh 4.x app, this section is likely empty. + +If any plugin warnings exist, a red **Warnings** subsection appears beneath the plugin table: + +- **Incompatible plugins** — plugins flagged as incompatible with the current Wheels version (controlled by `showIncompatiblePlugins`) +- **Dependent plugins** — plugins whose dependencies are not satisfied +- **Version mismatches** — plugins that require a different version of another plugin than what is loaded +- **Mixin collisions** — cases where two plugins defined the same method name on the same mixin target; the later-loaded plugin wins + +## Tools tab + +Shown when `enablePublicComponent` is `true` (the default in development). Opens a grid of link cards, each opening in a new tab: + +| Card | Links to | +|---|---| +| System Info | `/wheels/info` — Wheels internals, environment variables, loaded settings | +| Routes | `/wheels/routes` — all registered routes with HTTP method, path, and handler | +| API Docs | `/wheels/api-docs` — generated API documentation | +| Guides | `/wheels/guides` — the documentation site | +| Tests | `/wheels/tests` — the test runner | +| Migrator | `/wheels/migrator` — the database migration UI (shown when `enableMigratorComponent` is `true`) | +| Packages | `/wheels/packages` — the package browser (shown when `enablePackagesComponent` is `true`) | +| Plugins | `/wheels/plugins` — the legacy plugin list (shown when `enablePluginsComponent` is `true`) | + +{/* screenshot: Tools panel open — the link-card grid showing System Info, Routes, API Docs, Guides, Tests, Migrator, Packages, and Plugins cards */} + +## Configuration reference + +All settings are applied in `config/settings.cfm` or an environment-specific file under `config/`: + +```cfm title="config/environment.cfm" + + + + + + +``` + +| Setting | Default | Effect | +|---|---|---| +| `enableDebug` | `true` in development/testing | Show or hide the debug bar entirely | +| `enablePackagesComponent` | `true` | Show the Packages subsection in the Environment panel and the Packages link in Tools | +| `enablePluginsComponent` | `true` | Show the Plugins (Legacy) subsection and the Plugins link in Tools | +| `showIncompatiblePlugins` | `true` | Include incompatible-plugin warnings in the Warnings subsection | +| `enablePublicComponent` | `true` | Show the Tools tab and its link grid | +| `enableMigratorComponent` | `true` | Show the Migrator link in the Tools panel | + +## Related guides + + + + + diff --git a/web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/index.mdx b/web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/index.mdx index 2fed031f1d..a09f8c857d 100644 --- a/web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/index.mdx +++ b/web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/index.mdx @@ -71,6 +71,11 @@ The Digging Deeper section covers Wheels' advanced features — the ones you rea href="/v4-0-0-snapshot/digging-deeper/packages/" description="Activating first-party packages, writing your own, and the package.json manifest." /> + Date: Sat, 9 May 2026 23:18:37 -0700 Subject: [PATCH 2/4] docs(web/guides): fix debug panel setting names and sidebar order Address review feedback on PR #2539: - Replace `enableDebug` (which does not exist in the framework) with `showDebugInformation` throughout. The actual gate is checked in `vendor/wheels/events/EventMethods.cfc` and initialized in `vendor/wheels/events/init/debugging.cfm`. - Correct the default-environment claim: `showDebugInformation` is `true` only in `development`, not also in `testing` (per `debugging.cfm` lines 26-27, anything other than `development` flips it to false). - Correct `enablePublicComponent` default: it is `false`, only flipped to `true` in `development` (per `onapplicationstart.cfc` lines 241-243). - Add conditionality note to the Request tab's DB Adapter row, matching the existing treatment of the Route row (debug.cfm renders DB Adapter inside `StructKeyExists(application.wheels, "adapterName")`). - Bump sidebar `order` for `route-model-binding`, `cors`, `rate-limiting`, and `dependency-injection-usage` by 1 each so `debug-panel` (order 11) no longer collides with `route-model-binding`. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../docs/v4-0-0-snapshot/digging-deeper/cors.mdx | 2 +- .../v4-0-0-snapshot/digging-deeper/debug-panel.mdx | 14 +++++++------- .../digging-deeper/dependency-injection-usage.mdx | 2 +- .../digging-deeper/rate-limiting.mdx | 2 +- .../digging-deeper/route-model-binding.mdx | 2 +- 5 files changed, 11 insertions(+), 11 deletions(-) diff --git a/web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/cors.mdx b/web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/cors.mdx index 8772f87961..ba7d9cc927 100644 --- a/web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/cors.mdx +++ b/web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/cors.mdx @@ -3,7 +3,7 @@ title: CORS description: Cross-origin request handling — configuring the Cors middleware, preflight, credentials mode, and per-route scoping. type: howto sidebar: - order: 12 + order: 13 --- import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components'; diff --git a/web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/debug-panel.mdx b/web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/debug-panel.mdx index c98faa1091..02c9c7109e 100644 --- a/web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/debug-panel.mdx +++ b/web/sites/guides/src/content/docs/v4-0-0-snapshot/digging-deeper/debug-panel.mdx @@ -32,13 +32,13 @@ This means AJAX-driven partial updates, Turbo Streams, API endpoints, and CSV ex ## Enabling and disabling -The bar respects the `enableDebug` application setting. By default, Wheels sets this to `true` in the `development` and `testing` environments and `false` in `production` and `maintenance`. You can override it explicitly in `config/environment.cfm`: +The bar respects the `showDebugInformation` application setting. By default, Wheels sets this to `true` only in the `development` environment and `false` in every other environment (`testing`, `maintenance`, and `production`). You can override it explicitly in `config/environment.cfm`: ```cfm title="config/environment.cfm" - + ``` -Setting `enableDebug=false` removes the bar entirely — no HTML is injected into responses. +Setting `showDebugInformation=false` removes the bar entirely — no HTML is injected into responses.