Sync docs from wheels@14470a2

github-actions[bot] · github-actions[bot] · commit 44a3c4fc43ee · 2026-03-24T04:08:25.000Z
diff --git a/docs/3.1.0/guides/command-line-tools/cli-overview.md b/docs/3.1.0/guides/command-line-tools/cli-overview.md
@@ -159,8 +159,8 @@ wheels security scan
 
 | Wheels CLI | Wheels | CommandBox | CFML Engine |
 |------------|----------|------------|-------------|
-| 3.0.x | 2.5+ | 5.0+ | Lucee 5.3+, Adobe 2018+ |
-| 2.0.x | 2.0-2.4 | 4.0+ | Lucee 5.2+, Adobe 2016+ |
+| 3.0.x | 3.0+ | 5.0+ | Lucee 5.3+, Adobe 2018+ |
+| 2.0.x | 2.0-2.5 | 4.0+ | Lucee 5.2+, Adobe 2016+ |
 
 ## Community & Support
 
diff --git a/docs/3.1.0/guides/command-line-tools/commands/core/init.md b/docs/3.1.0/guides/command-line-tools/commands/core/init.md
@@ -94,7 +94,7 @@ Please enter a default cfengine: lucee5
   "name": "myapp",
   "version": "1.0.0",
   "dependencies": {
-    "wheels": "^2.5.0"
+    "wheels": "^3.1.0"
   }
 }
 ```
diff --git a/docs/3.1.0/guides/command-line-tools/commands/generate/app-wizard.md b/docs/3.1.0/guides/command-line-tools/commands/generate/app-wizard.md
@@ -55,8 +55,8 @@ Please enter a name for your application: MyWheelsApp
 ### Step 2: Template Selection
 ```
 Which Wheels Template shall we use?
-❯ 3.0.x - Wheels Base Template - Bleeding Edge
-  2.5.x - Wheels Base Template - Stable Release
+❯ 3.1.x - Wheels Base Template - Latest
+  3.0.x - Wheels Base Template - Stable Release
   Wheels Template - HTMX - Alpine.js - Simple.css
   Wheels Starter App
   Wheels - TodoMVC - HTMX - Demo App
diff --git a/docs/3.1.0/guides/command-line-tools/development-workflow.md b/docs/3.1.0/guides/command-line-tools/development-workflow.md
@@ -87,7 +87,7 @@ The `wheels upgrade` command provides an interactive wizard for upgrading your W
 wheels upgrade --check
 
 # Output:
-# Current Wheels version: 2.5.0
+# Current Wheels version: 3.1.0
 # Upgrade available: 3.1.0
 # Run 'wheels upgrade' to start the upgrade process.
 ```
diff --git a/docs/3.1.0/guides/database-interaction-through-models/database-migrations/README.md b/docs/3.1.0/guides/database-interaction-through-models/database-migrations/README.md
@@ -6,7 +6,7 @@ description: >-
 
 # Database Migrations
 
-With Wheels 2.x, you can now create, alter and populate your database via cfscript in an organized manner. Using custom CFC files, you can create an organized database schema, and move between versions easily, either programmatically, via the provided GUI, or via the CLI.&#x20;
+Wheels allows you to create, alter and populate your database via cfscript in an organized manner. Using custom CFC files, you can create an organized database schema, and move between versions easily, either programmatically, via the provided GUI, or via the CLI.&#x20;
 
 ### Getting Started
 
diff --git a/docs/3.1.0/guides/database-interaction-through-models/database-migrations/migrations-in-production.md b/docs/3.1.0/guides/database-interaction-through-models/database-migrations/migrations-in-production.md
@@ -34,7 +34,7 @@ Please consult the internal documentation API reference under Configurations > D
 
 ### Further considerations with automatic migrations
 
-If you are using automatic migrations, then you could lock down production mode even further. With Wheels 2.x there is more data available to development mode, such as the internal documentation, routing GUI and Migration GUI.
+If you are using automatic migrations, then you could lock down production mode even further. In development mode, there is more data available, such as the internal documentation, routing GUI and Migration GUI.
 
 **Turn off environment switching**
 
diff --git a/docs/3.1.0/guides/displaying-views-to-users/linking-pages.md b/docs/3.1.0/guides/displaying-views-to-users/linking-pages.md
@@ -266,7 +266,7 @@ To link to the `pages` resource, you add the parent resource's singular name fir
 
 ### Linking to a Delete Action
 
-Wheels 2.0 introduced security improvements for actions that change data in your applications (i.e., creating, updating, and deleting database records). Wheels protects these actions by requiring that they happen along with a form `POST` in the browser.
+Wheels includes security improvements for actions that change data in your applications (i.e., creating, updating, and deleting database records). Wheels protects these actions by requiring that they happen along with a form `POST` in the browser.
 
 A common UI pattern is to have a link to delete a record, usually in an admin area. Unfortunately, links can only trigger `GET` requests, so we need to work around this.
 
diff --git a/docs/3.1.0/guides/handling-requests-with-controllers/caching.md b/docs/3.1.0/guides/handling-requests-with-controllers/caching.md
@@ -94,7 +94,7 @@ The variables themselves are fairly self-explanatory. When `cacheDatabaseSchema`
 {% hint style="info" %}
 #### No more Design mode
 
-Note that "Design" mode has been removed in Wheels 2.x: please use development mode instead.
+Note that "Design" mode has been removed: please use development mode instead.
 {% endhint %}
 
 Please refer to the [Configuration and Defaults](https://wheels.dev/3.1.0/guides/working-with-wheels/configuration-and-defaults) chapter for a complete listing of all the variables you can set and their default values.
diff --git a/docs/3.1.0/guides/handling-requests-with-controllers/cors-requests.md b/docs/3.1.0/guides/handling-requests-with-controllers/cors-requests.md
@@ -10,7 +10,7 @@ When we separate our systems in such a manner, we need to consider CORS (Cross O
 
 ### The "Quick and Dirty" approach
 
-If you just need to satisfy your CORS requirement quickly, you can do so from Wheels 2.0 onwards with a simple configuration switch in your `/config/settings.cfm` file: `set(allowCorsRequests=true);`.
+If you just need to satisfy your CORS requirement quickly, you can do so with a simple configuration switch in your `/config/settings.cfm` file: `set(allowCorsRequests=true);`.
 
 By default, this will enable the following CORS headers:
 
@@ -29,13 +29,7 @@ This will satisfy most requirements to get going quickly, but is more of a blank
 
 ### Custom CORS Headers
 
-{% hint style="info" %}
-#### From Wheels 2.1
-
-The options below were introduced in Wheels 2.1
-{% endhint %}
-
-From Wheels 2.1, we can be more specific. We still need to specify `set(allowCorsRequests=true);` in our `/config/settings.cfm` to turn on the main CORS functionality, but we can now provide some additional configuration options to fine tune our responses.
+We can be more specific. We still need to specify `set(allowCorsRequests=true);` in our `/config/settings.cfm` to turn on the main CORS functionality, but we can also provide some additional configuration options to fine tune our responses.
 
 ### Access Control Allow Origin
 
@@ -56,7 +50,7 @@ set(accessControlAllowOrigin="https://app.domain.com,https://staging-app.domain.
 
 You can also take advantage of the environment specific configurations, such as only allowing access to `localhost:8080` in `/config/development/settings.cfm` for example.
 
-**Wheels 2.2** allows for subdomain wildcard matching for CORS permitted origins:
+Wheels also allows for subdomain wildcard matching for CORS permitted origins:
 
 ```javascript
 // Match https://foo.domain.com or https://bar.domain.com or https://www.mydomain.com
diff --git a/docs/3.1.0/guides/handling-requests-with-controllers/nesting-controllers.md b/docs/3.1.0/guides/handling-requests-with-controllers/nesting-controllers.md
@@ -1,6 +1,6 @@
 # Nesting Controllers
 
-With the new routing system in Wheels 2.x, there are lots of nice features which allow for better code organization. One of these is the ability to nest controllers into folders using the `namespace()` method in our `mapper()` call.
+With the routing system in Wheels, there are lots of nice features which allow for better code organization. One of these is the ability to nest controllers into folders using the `namespace()` method in our `mapper()` call.
 
 For example, we may have a whole "Admin" section, where for each endpoint, we need to check some permissions, and possibly load some default data. Let's say we have a `Users` controller which provides standard CRUD operations.
 
diff --git a/docs/3.1.0/guides/handling-requests-with-controllers/request-handling.md b/docs/3.1.0/guides/handling-requests-with-controllers/request-handling.md
@@ -168,7 +168,7 @@ So in the same way that the `url` and `form` scopes are merged, so a valid `json
 {% hint style="info" %}
 #### NOTE
 
-The mapping of a json array to params.json was introduced in Wheels 2.1
+When a JSON array is the root element, it is mapped to `params._json` following Rails conventions.
 {% endhint %}
 
 ### Routing
diff --git a/docs/3.1.0/guides/handling-requests-with-controllers/routing.md b/docs/3.1.0/guides/handling-requests-with-controllers/routing.md
@@ -409,15 +409,15 @@ GET /news/show/5
 
 With this convention, the URL above told Wheels to invoke the `show` action in the `news` controller. It also passed a parameter called `key` to the action, with a value of `5`.
 
-If you're upgrading from 1.x or still prefer this style of routing for your Wheels 2+ application, you can use the [wildcard()](https://wheels.dev/api/v3.1.0/mapper.wildcard.html) method to enable it part of it:&#x20;
+If you're upgrading from 1.x or still prefer this style of routing for your Wheels application, you can use the [wildcard()](https://wheels.dev/api/v3.1.0/mapper.wildcard.html) method to enable it part of it:&#x20;
 
 ```javascript
 mapper()
     .wildcard()
 .end();
 ```
 
-Wheels 2 will only generate routes for `[controller]/[action]`, however, because resources and the other routing methods are more appropriate for working with records identified by primary keys.
+Wheels will only generate routes for `[controller]/[action]`, however, because resources and the other routing methods are more appropriate for working with records identified by primary keys.
 
 Here is a sample of the patterns that `wildcard` generates:
 
@@ -601,7 +601,7 @@ mapper()
 
 ### Redirection
 
-As of Wheels 2.1, you can now use a `redirect` argument on `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` requests. This will execute before reaching any controllers, and perform a `302` redirect immediately after the route is matched.
+You can use a `redirect` argument on `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` requests. This will execute before reaching any controllers, and perform a `302` redirect immediately after the route is matched.
 
 CFScript
 
@@ -619,12 +619,6 @@ This is useful for the occasional redirect, and saves you having to create a ded
 
 ### Disabling automatic \[format] routes
 
-{% hint style="info" %}
-#### Note
-
-Introduced in Wheels 2.1
-{% endhint %}
-
 By default, Wheels will add `.[format]` routes when using `resources()`. You may wish to disable this behavior to trim down the number of generated routes for clarity and performance reasons (or you just don't use this feature!).
 
 You can either disable this via `mapFormat = false` on a per resource basis, or more widely, on a mapper basis:
diff --git a/docs/3.1.0/guides/handling-requests-with-controllers/url-rewriting/README.md b/docs/3.1.0/guides/handling-requests-with-controllers/url-rewriting/README.md
@@ -29,7 +29,7 @@ Once you have added the rewrite rules (usually in either `.htaccess`, `web.confi
 {% hint style="info" %}
 #### Head's Up!
 
-Since 2.x, engine specific URL rewrite files are not included in the default distribution. Don't worry - we've got you covered though!
+Engine specific URL rewrite files are not included in the default distribution. Don't worry - we've got you covered though!
 {% endhint %}
 
 For webserver specific instructions look at the following pages:
diff --git a/docs/3.1.0/guides/handling-requests-with-controllers/using-the-flash.md b/docs/3.1.0/guides/handling-requests-with-controllers/using-the-flash.md
@@ -236,7 +236,7 @@ considerations.
 
 ### Appending to, rather than replacing the flash
 
-From Wheels 2.1, you can now change the default flash behavior to append to an existing key, rather than directly replacing it. To turn on this behavior, add `set(flashAppend=true)` to you `/config/settings.cfm` file.
+You can change the default flash behavior to append to an existing key, rather than directly replacing it. To turn on this behavior, add `set(flashAppend=true)` to you `/config/settings.cfm` file.
 
 An example of where this might be useful:
 
@@ -270,8 +270,6 @@ flashInsert(info=msgs);
 
 ### Disabling the Flash Cookie
 
-In `2.2` upwards:
+There are certain circumstances where you might not be using the flash: for example, if you have Wheels setup as a stateless API (perhaps in a cluster behind a load balancer) where you're using tokens vs sessions. In this circumstance, you've probably turned off session management, which only leaves `cookie` as a viable route. But if set to `cookie`, you always get `Set-Cookie` being returned, which is unnecessary.
 
-There are certain circumstances where you might not be using the flash: for example, if you have wheels setup as a stateless API (perhaps in a cluster behind a load balancer) where you're using tokens vs sessions. In this circumstance, you've probably turned off session management, which only leaves `cookie` as a viable route. But if set to `cookie`, you always get `Set-Cookie` being returned, which is unnecessary.
-
-In wheels 2.2 you can now `set(flashStorage = "none")` which will prevent the creation of the cookie, and also not try and write to a session.
+You can set `set(flashStorage = "none")` which will prevent the creation of the cookie, and also not try and write to a session.
diff --git a/docs/3.1.0/guides/introduction/screencasts.md b/docs/3.1.0/guides/introduction/screencasts.md
@@ -6,24 +6,28 @@ description: >-
 
 # Screencasts
 
-### Wheels 2.x
+### Wheels 3.x
 
-Create a basic CRUD interface in Wheels 2.x\
+{% hint style="info" %}
+The screencasts below were recorded with Wheels 2.x but the core concepts (CRUD, routing, testing) remain applicable to Wheels 3.x.
+{% endhint %}
+
+Create a basic CRUD interface\
 [https://youtu.be/K5HLItTru1g](https://youtu.be/K5HLItTru1g)
 
-Create a basic JSON API in Wheels 2.x\
+Create a basic JSON API\
 [https://youtu.be/qZr5JzO0vo4](https://youtu.be/qZr5JzO0vo4)
 
-Routing in Wheels 2.x - Part 1\
+Routing in Wheels - Part 1\
 [https://youtu.be/BnPGApAvMVQ](https://youtu.be/BnPGApAvMVQ)
 
-Routing in Wheels 2.x - Part 2\
+Routing in Wheels - Part 2\
 [https://youtu.be/0CiGxJyJEIQ](https://youtu.be/0CiGxJyJEIQ)
 
-Introduction to Unit Testing in Wheels 2.x\
+Introduction to Unit Testing in Wheels\
 [https://youtu.be/XgMuzzmBQ98](https://youtu.be/XgMuzzmBQ98)
 
-Unit Testing Controllers in Wheels 2.x\
+Unit Testing Controllers in Wheels\
 [https://youtu.be/cygj9WDqHjY](https://youtu.be/cygj9WDqHjY)
 
 ### Wheels 1.x
diff --git a/docs/3.1.0/guides/introduction/upgrading.md b/docs/3.1.0/guides/introduction/upgrading.md
@@ -309,11 +309,11 @@ For many applications, you need to follow these steps:
 
 See documentation for the [CSRF Protection Plugin](https://github.com/liquifusion/wheels-csrf-protection) for more information.
 
-Note: If you had previously installed the [CSRF Protection plugin](https://github.com/liquifusion/wheels-csrf-protection), you may remove it and rely on the functionality included in the Wheels 2 core.
+Note: If you had previously installed the [CSRF Protection plugin](https://github.com/liquifusion/wheels-csrf-protection), you may remove it and rely on the functionality included in the Wheels core.
 
 #### Database Migrations
 
-If you have previously been using the dbmigrate plugin, you can now use the inbuilt version within the Wheels 2 core.&#x20;
+If you have previously been using the dbmigrate plugin, you can now use the inbuilt version within the Wheels core.&#x20;
 
 Database Migration files in `/db/migrate/` should now be moved to `/app/migrator/migrations/` and extend `wheels.migrator.Migration`, not `plugins.dbmigrate.Migration` which can be changed with a simple find and replace. Note: Oracle is not currently supported for Migrator.
 
diff --git a/docs/3.1.0/guides/plugins/developing-plugins.md b/docs/3.1.0/guides/plugins/developing-plugins.md
@@ -16,7 +16,7 @@ Here's an example:
 ```javascript
 component {
   function init(){
-    this.version="1.4.5,2.0";
+    this.version="3.0,3.1";
     return this;
   }
 }
@@ -121,7 +121,7 @@ pluginManager.installPlugin(URL.plugin);
 
 ### Don't forget to comment!
 
-With Wheels 2.x we can take advantage of the inbuilt documentation generator. Try and tag your public facing functions appropriately.
+Wheels includes an inbuilt documentation generator. Try and tag your public facing functions appropriately.
 
 Here's an example from the wheels ical4J plugin:
 
@@ -154,7 +154,7 @@ The javaDoc style comments will automatically show this function under Plugins >
 
 ### Box.json
 
-With `2.x`, a `box.json` is required for new plugins. Read the [Publishing Plugins](https://wheels.dev/3.1.0/guides/plugins/publishing-plugins) chapter for more details on that. One advantage is that Wheels now includes the version and meta data for each plugin when there's a `box.json` file.
+A `box.json` is required for new plugins. Read the [Publishing Plugins](https://wheels.dev/3.1.0/guides/plugins/publishing-plugins) chapter for more details on that. One advantage is that Wheels now includes the version and meta data for each plugin when there's a `box.json` file.
 
 ```javascript
 // Version Number
@@ -168,13 +168,13 @@ This saves you having to read in the `box.json` file, should you wish to use it
 
 ### Automatic Java Lib Mappings
 
-If you've ever wanted to do a quick wrapper for a java class/lib, this new feature in `2.x` means you can add a `.class` or `.jar` file, and it will be automatically mapped into the `this.javaSettings.loadpaths` setting when the application starts.
+If you've ever wanted to do a quick wrapper for a java class/lib, you can add a `.class` or `.jar` file, and it will be automatically mapped into the `this.javaSettings.loadpaths` setting when the application starts.
 
 This means you can distribute plugins with Java libs and they'll work properly without additional user intervention!
 
 ### Enabling Travis CI Testing
 
-One of the nicest things about `2.x` is the tighter integration with command-line tools such as CommandBox. We can take advantage of the new testing suite JSON return type and the new Wheels CLI in CommandBox 2.x to easily build a Travis CI test. It's perhaps easiest to just show the `.travis.yml` file - this goes in the root of your gitHub plugin repository, and once you've turned on testing under Travis.org, will run your test suite on every commit.
+Wheels has tight integration with command-line tools such as CommandBox. We can take advantage of the testing suite JSON return type and the Wheels CLI to easily build a CI test. It's perhaps easiest to just show the `.travis.yml` file - this goes in the root of your gitHub plugin repository, and once you've turned on testing under Travis.org, will run your test suite on every commit.
 
 {% code title=".travis.yml" %}
 ```yaml
diff --git a/docs/3.1.0/guides/working-with-wheels/contributing-to-wheels.md b/docs/3.1.0/guides/working-with-wheels/contributing-to-wheels.md
@@ -73,7 +73,7 @@ To stay true to our ColdFusion and Java roots, all names must be camelCase. In s
 
 #### Local Variables
 
-Since moving to Wheels 2.x, the old `loc` scope has now been deprecated and you should use the function `local` scope.
+The old `loc` scope has been deprecated and you should use the function `local` scope.
 
 Code Example
 
diff --git a/docs/3.1.0/guides/working-with-wheels/documenting-your-code.md b/docs/3.1.0/guides/working-with-wheels/documenting-your-code.md
@@ -78,4 +78,4 @@ Whilst the core has additional code samples which can be loaded from text files,
 
 Whilst this API/function explorer is a great first step, you’ll notice your controller and model specific functions aren’t included (only those shared amongst controllers, or in the `/app/global/functions.cfm` file. This is because we’re only looking at the main `Model.cfc` and `Controller.cfc` and what it can access.
 
-In Wheels 2.1, we’ll look at adding a full Controller and Model metadata explorer using the same techniques, and map functions like `show()` to their respective routes too.
+In a future release, we’ll look at adding a full Controller and Model metadata explorer using the same techniques, and map functions like `show()` to their respective routes too.

Original file line number	Diff line number	Diff line change
`@@ -94,7 +94,7 @@ Please enter a default cfengine: lucee5`
`94`	`94`	`"name": "myapp",`
`95`	`95`	`"version": "1.0.0",`
`96`	`96`	`"dependencies": {`
`97`		`- "wheels": "^2.5.0"`
	`97`	`+ "wheels": "^3.1.0"`
`98`	`98`	`}`
`99`	`99`	`}`
`100`	`100`	```