docs(api): validate View Helpers section (run 25478239817) (wheels-dev#2465)

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

Author: github-actions[bot]

tools/docs-validation/state.json

@@ -1,8 +1,11 @@
-<!--- Needed here because we're not using `startFormTag`. --->
+// 1. Include CSRF token in a plain HTML form that POSTs data
+//    (use this when you are not using startFormTag())
 <form action="#urlFor(route='posts')#" method="post">
   #authenticityTokenField()#
+  <!--- other fields here --->
+</form>
+
+// 2. Not needed for GET forms — GET requests are not CSRF-protected
+<form action="#urlFor(route='posts')#" method="get">
+  <!--- no token required --->
 </form>
-  
-<!--- Not needed here because we're not POSTing the form. --->
-<form action="#urlFor(route='invoices')#" method="get">
-</form>

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

@@ -1,5 +1,15 @@
-<!--- Will output: Download CFWheels from <a href="http://cfwheels.org/download">http://cfwheels.org/download</a> --->
-#autoLink("Download CFWheels from http://cfwheels.org/download")#
+// 1. Link both URLs and email addresses (default behavior)
+result = autoLink("Download CFWheels from http://cfwheels.org/download");
+// result -> "Download CFWheels from <a href="http://cfwheels.org/download">http://cfwheels.org/download</a>"
 
-<!--- Will output: Email us at <a href="mailto:info@cfwheels.org">info@cfwheels.org</a> --->
-#autoLink("Email us at info@cfwheels.org")#
+// 2. Link email addresses only
+result = autoLink(text="Email us at info@cfwheels.org or visit http://cfwheels.org", link="emailAddresses");
+// result -> "Email us at <a href="mailto:info@cfwheels.org">info@cfwheels.org</a> or visit http://cfwheels.org"
+
+// 3. Link URLs only (skip email addresses)
+result = autoLink(text="Visit http://cfwheels.org or contact info@cfwheels.org", link="URLs");
+// result -> "Visit <a href="http://cfwheels.org">http://cfwheels.org</a> or contact info@cfwheels.org"
+
+// 4. Disable auto-linking of relative URLs
+result = autoLink(text="See /docs/guide for details or http://cfwheels.org for more.", relative=false);
+// result -> "See /docs/guide for details or <a href="http://cfwheels.org">http://cfwheels.org</a> for more."

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

@@ -1,5 +1,21 @@
-<!--- View Code --->
-#startFormTag(action="something")#
-    <!--- Form Controls go here --->
-    #buttonTag(content="Submit this form", value="save")#
+// 1. Basic submit button inside a form
+#startFormTag(action="create")#
+    #buttonTag(content="Save changes", value="save")#
 #endFormTag()#
+<!--- Produces: <button type="submit" value="save">Save changes</button> --->
+
+// 2. Reset button to clear form fields
+#buttonTag(content="Clear form", type="reset")#
+<!--- Produces: <button type="reset" value="save">Clear form</button> --->
+
+// 3. Plain button (no form submission) with a CSS class and id
+#buttonTag(content="Open dialog", type="button", value="open", class="btn btn-secondary", id="openDialogBtn")#
+<!--- Produces: <button type="button" value="open" class="btn btn-secondary" id="openDialogBtn">Open dialog</button> --->
+
+// 4. Submit button wrapped in a paragraph using prepend and append
+#buttonTag(content="Submit", value="submit", prepend="<p>", append="</p>")#
+<!--- Produces: <p><button type="submit" value="submit">Submit</button></p> --->
+
+// 5. Image button (renders an img tag inside the button element)
+#buttonTag(content="", image="submit-icon.png", value="save")#
+<!--- Produces: <button type="submit" value="save"><img src="/images/submit-icon.png" alt="Submit Icon" /></button> --->

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

@@ -1,4 +1,20 @@
-#buttonTo(text="Delete Account", action="perFormDelete", disable="Wait...")#
+// 1. Basic button that submits to a controller/action
+#buttonTo(text="Delete Account", controller="account", action="delete")#
+<!--- Outputs: <form action="/account/delete" method="post"><button type="submit">Delete Account</button></form> --->
 
-<!--- apply attributes to the input element by prefixing any arguments with "input"--->
-#buttonTo(text="Edit", action="edit", inputId="edit-button", inputClass="edit-button-class")#
+// 2. If you're already in the `account` controller, CFWheels will assume the current controller
+#buttonTo(text="Delete Account", action="delete")#
+<!--- Outputs: <form action="/account/delete" method="post"><button type="submit">Delete Account</button></form> --->
+
+// 3. Use `method` to send a DELETE request (a hidden `_method` field is added automatically)
+#buttonTo(text="Remove Post", controller="blog", action="delete", key=99, method="delete")#
+<!--- Outputs: <form action="/blog/delete/99" method="post"><input type="hidden" name="_method" value="delete" /><button type="submit">Remove Post</button></form> --->
+
+// 4. Use a named route configured in `config/routes.cfm`
+#buttonTo(text="Archive", route="archivePost", postId=12)#
+
+// 5. Show a "please wait" state by disabling the button on click — pass extra attributes to the button using the `input` prefix
+#buttonTo(text="Place Order", action="checkout", inputId="checkout-btn", inputClass="btn btn-primary", inputData-disable-with="Processing...")#
+
+// 6. Use an image instead of text for the button
+#buttonTo(image="icons/trash.png", action="destroy", key=params.id, method="delete")#

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

@@ -1,12 +1,10 @@
-<!--- Basic example of a check box for a boolean field --->
+// 1. Basic check box bound to a boolean model property
 #checkBox(objectName="photo", property="isPublic", label="Display this photo publicly.")#
 
-<!--- Shows check boxes for selecting public access for all photos provided by the `photos` association and nested properties --->
+// 2. Custom checked and unchecked values (e.g. "yes" / "no" instead of 1 / 0)
+#checkBox(objectName="user", property="agreedToTerms", checkedValue="yes", uncheckedValue="no", label="I agree to the terms of service.")#
+
+// 3. Check boxes for a nested association (photos belonging to a user)
 <cfloop from="1" to="#ArrayLen(user.photos)#" index="i">
-    <div>
-        <h3>#user.photos[i].title#:</h3>
-        <div>
-            #checkBox(objectName="user", association="photos", position=i, property="isPublic", label="Display this photo publicly.")#
-        </div>
-    </div>
-</cfloop>
+    #checkBox(objectName="user", association="photos", position=i, property="isPublic", label="Make public: #user.photos[i].title#")#
+</cfloop>

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

@@ -1,16 +1,24 @@
-<!--- Example 1: Basic usage involves a `label`, `name`, and `value` --->
-#checkBoxTag(name="subscribe", value="true", label="Subscribe to our newsletter", checked=false)#
+// 1. Basic usage with a label and a pre-checked state
+<cfoutput>
+	#checkBoxTag(name="subscribe", value="1", label="Subscribe to our newsletter", checked=true)#
+</cfoutput>
 
-<!--- Example 2: Loop over a query to display choices and whether or not they are checked --->
-// Controller code
-pizza = model("pizza").findByKey(session.pizzaId);
-selectedToppings = pizza.toppings();
-toppings = model("topping").findAll(order="name");
+// 2. Render an unchecked check box that also submits a value when unchecked
+<cfoutput>
+	#checkBoxTag(name="agreeToTerms", value="1", uncheckedValue="0", label="I agree to the terms")#
+</cfoutput>
 
-<!--- View code --->
-<fieldset>
-	<legend>Toppings</legend>
-	<cfoutput query="toppings">
-		#checkBoxTag(name="toppings", value="true", label=toppings.name, checked=YesNoFormat(ListFind(ValueList(selectedToppings.id), toppings.id))#
-	</cfoutput>
-</fieldset>
+// 3. Loop over a query to render one check box per option, checking those already selected
+// Controller
+toppings = model("Topping").findAll(order="name");
+selectedIds = "2,5,9"; // e.g. previously saved topping IDs as a comma-delimited list
+
+// View
+<cfoutput query="toppings">
+	#checkBoxTag(
+		name    = "toppingIds",
+		value   = toppings.id,
+		label   = toppings.name,
+		checked = listFindNoCase(selectedIds, toppings.id) GT 0
+	)#
+</cfoutput>

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

@@ -0,0 +1,10 @@
+// 1. Basic color picker bound to a model object property
+#colorField(objectName="product", property="themeColor")#
+
+// 2. Color picker with a custom label and a CSS class
+#colorField(objectName="user", property="profileColor", label="Profile Color", class="color-picker")#
+
+// 3. Color pickers for nested properties on a hasMany association (e.g., palette swatches)
+<cfloop from="1" to="#ArrayLen(design.swatches)#" index="i">
+	#colorField(objectName="design", association="swatches", position="#i#", property="hexValue", label="Swatch ##i#")#
+</cfloop>

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

@@ -0,0 +1,8 @@
+// 1. Basic color picker with a default value
+#colorFieldTag(name="brandColor", value="##FF5733")#
+
+// 2. Color picker with a label and a CSS class
+#colorFieldTag(name="themeColor", value="##336699", label="Theme Color", class="color-input")#
+
+// 3. Color picker with label placement and prepend/append wrappers
+#colorFieldTag(name="highlightColor", label="Highlight", labelPlacement="before", prepend="<div class=""field"">", append="</div>")#

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

@@ -1,18 +1,43 @@
-<!--- In your view --->
+// 1. Store sidebar content for use in the layout
 <cfsavecontent variable="mySidebar">
-<h1>My Sidebar Text</h1>
+  <nav>Recent Posts</nav>
 </cfsavecontent>
 <cfset contentFor(sidebar=mySidebar)>
 
-<!--- In your layout --->
-<html>
-	<head>
-	    <title>My Site</title>
-	</head>
-	<body>
-		<cfoutput>
-			#includeContent("sidebar")#
-			#includeContent()#
-		</cfoutput>
-	</body>
-</html>
+<!--- In your layout, output the stored section --->
+<cfoutput>
+  #includeContent("sidebar")#
+  #includeContent()#
+</cfoutput>
+
+// 2. Push content onto a stack — multiple calls append by default
+<cfsavecontent variable="firstScript">
+  <script src="/js/base.js"></script>
+</cfsavecontent>
+<cfset contentFor(scripts=firstScript)>
+
+<cfsavecontent variable="secondScript">
+  <script src="/js/page.js"></script>
+</cfsavecontent>
+<cfset contentFor(scripts=secondScript)>
+
+<!--- Both scripts are rendered in order --->
+<cfoutput>#includeContent("scripts")#</cfoutput>
+
+// 3. Prepend content to an existing section using position="first"
+<cfsavecontent variable="criticalScript">
+  <script src="/js/critical.js"></script>
+</cfsavecontent>
+<cfset contentFor(position="first", scripts=criticalScript)>
+
+// 4. Overwrite an entire section with overwrite="all"
+<cfsavecontent variable="replacementSidebar">
+  <nav>Admin Sidebar</nav>
+</cfsavecontent>
+<cfset contentFor(overwrite="all", sidebar=replacementSidebar)>
+
+// 5. Overwrite a specific position in the stack (position=1, overwrite=true)
+<cfsavecontent variable="updatedScript">
+  <script src="/js/updated.js"></script>
+</cfsavecontent>
+<cfset contentFor(position=1, overwrite=true, scripts=updatedScript)>