docs(api): validate Controller section (run 25476931516) (wheels-dev#2462)

Co-authored-by: wheels-docs-validator[bot] <wheels-docs-validator@users.noreply.github.com>

Author: github-actions[bot]

tools/docs-validation/state.json

@@ -163,6 +163,7 @@ component {
 	 * @disposition Set to `inline` to have the browser handle the opening of the file (possibly inline in the browser) or set to `attachment` to force a download dialog box.
 	 * @directory Directory outside of the web root where the file exists. Must be a full path.
 	 * @deleteFile Pass in `true` to delete the file on the server after sending it.
+	 * @deliver When set to `false`, the file will not be sent to the browser (used for testing).
 	 */
 	public any function sendFile(
 		required string file,

vendor/wheels/controller/miscellaneous.cfc

@@ -19,9 +19,10 @@ component {
 	 * @host Set this to override the current host.
 	 * @protocol Set this to override the current protocol.
 	 * @port Set this to override the current port number.
+	 * @method HTTP method constraint used when matching routes.
 	 * @url Redirect to an external URL.
 	 * @delay Set to `true` to delay the redirection until after the rest of your action code has executed.
-	 * @encode [see:URLFor].
+	 * @encode Encode URL parameters using `EncodeForURL()`. Please note that this does not make the string safe for placement in HTML attributes, for that you need to wrap the result in `EncodeForHtmlAttribute()` or use `linkTo()`, `startFormTag()` etc instead.
 	 */
 	public void function redirectTo(
 		boolean back = false,

vendor/wheels/controller/redirection.cfc

@@ -0,0 +1,11 @@
+// 1. Embed the CSRF token in a manually-built form hidden field
+token = authenticityToken();
+writeOutput('<input type="hidden" name="authenticityToken" value="' & token & '">');
+
+// 2. Pass the token as a request header for an AJAX call (e.g. in a JavaScript data island)
+writeOutput('<meta name="csrf-token" content="' & authenticityToken() & '">');
+// JavaScript can then read this and send it as the X-CSRF-Token header with each POST request.
+
+// 3. Include the token in a JSON API response body so a client can replay it
+tokenValue = authenticityToken();
+writeOutput(serializeJSON({authenticityToken = tokenValue}));

vendor/wheels/public/docs/reference/controller/authenticitytoken.txt

@@ -1,11 +1,11 @@
-// Cache the `termsOfUse` action.
+// 1. Cache the `termsOfUse` action for the default 60 minutes.
 caches("termsOfUse");
 
-// Cache the `termsOfUse` action for 30 minutes.
-caches(actions="browseByUser, browseByTitle", time=30);
+// 2. Cache two actions for 30 minutes.
+caches(actions="browseByUser,browseByTitle", time=30);
 
-// Cache the `termsOfUse` and `codeOfConduct` actions, including their filters.
-caches(actions="termsOfUse, codeOfConduct", static=true);
+// 3. Cache the `termsOfUse` and `codeOfConduct` actions, including their filters.
+caches(actions="termsOfUse,codeOfConduct", static=true);
 
-// Cache content separately based on region.
-caches(action="home", key="request.region");
+// 4. Cache content separately based on region.
+caches(action="home", appendToKey="request.region");

vendor/wheels/public/docs/reference/controller/caches.txt

@@ -0,0 +1,8 @@
+// 1. Clear all cached action metadata for the current controller.
+clearCachableActions();
+
+// 2. Clear the cached metadata for a single action.
+clearCachableActions(action="termsOfUse");
+
+// 3. Clear the cached metadata for a list of specific actions.
+clearCachableActions(action="browseByUser,browseByTitle");

vendor/wheels/public/docs/reference/controller/clearcachableactions.txt

@@ -1,5 +1,14 @@
-// Get filter chain.
+// 1. Get the entire filter chain for the current controller
 myFilterChain = filterChain();
+// myFilterChain -> array of structs, each with keys: through, type, only, except, arguments
+// e.g. [{ through: "checkLogin", type: "before", only: "", except: "" }, ...]
 
-// Get filter chain for after filters only.
-myFilterChain = filterChain(type="after");
+// 2. Get only the before-filters
+beforeFilters = filterChain(type="before");
+for (f in beforeFilters) {
+    writeOutput(f.through);
+}
+
+// 3. Get only the after-filters
+afterFilters = filterChain(type="after");
+writeOutput(arrayLen(afterFilters));

vendor/wheels/public/docs/reference/controller/filterchain.txt

@@ -1,5 +1,25 @@
-// Always execute `restrictAccess` before all actions in this controller.
+// 1. Run `restrictAccess` before every action in this controller (declared inside config()).
 filters("restrictAccess");
 
-// Always execute `isLoggedIn` and `checkIPAddress` (in that order) before all actions in this controller, except the `home` and `login` actions.
+// 2. Run two before-filters on every action except `home` and `login`.
 filters(through="isLoggedIn, checkIPAddress", except="home, login");
+
+// 3. Run `auditLog` after only the `create`, `update`, and `delete` actions.
+filters(through="auditLog", type="after", only="create, update, delete");
+
+// 4. Prepend a filter so it runs before any already-registered filters.
+filters(through="maintenanceCheck", placement="prepend");
+
+// Note: filter functions must be declared as `private` in the controller
+// to prevent them from being routed as public actions.
+// Example controller setup:
+// component extends="Controller" {
+//     function config() {
+//         filters("restrictAccess");
+//     }
+//     private function restrictAccess() {
+//         if (!isLoggedIn()) {
+//             redirectTo(route="login");
+//         }
+//     }
+// }

vendor/wheels/public/docs/reference/controller/filters.txt

@@ -1,5 +1,12 @@
-// Get the current value of notice in the Flash
+// 1. Get the current value of a specific key in the Flash
 notice = flash("notice");
+// notice -> "Your profile was updated successfully."
 
-// Get the entire Flash as a struct
-flashContents = flash();
+// 2. Get the entire Flash as a struct when no key is passed
+flashContents = flash();
+// flashContents -> {notice: "Record saved.", error: "Something went wrong."}
+
+// 3. Check for a key before reading it to avoid an empty-string fallback
+if (flashKeyExists("error")) {
+    errorMessage = flash("error");
+}

vendor/wheels/public/docs/reference/controller/flash.txt

@@ -1 +1,18 @@
-flashClear();
+// 1. Clear all flash data
+flashClear();
+
+// 2. Insert some messages, then clear them all before redirecting
+flashInsert(notice="Record saved.");
+flashInsert(warning="Check your settings.");
+// Oops — wipe everything and start fresh
+flashClear();
+// flash() is now an empty struct: {}
+
+// 3. Clear flash conditionally inside a controller action
+function checkout() {
+    if (!isLoggedIn()) {
+        flashClear();
+        flashInsert(error="You must be logged in to check out.");
+        redirectTo(action="login");
+    }
+}