improve recipes

Author: zspitzer

docs/recipes/caches-defined-in-application-cfc.md

@@ -24,15 +24,7 @@
 
 # Caches defined in Application.cfc
 
-It is possible to add cache connections in Lucee 5.1+ on a per-application basis by adding configuration to your `Application.cfc`. 
-
-You can also select the default object cache, query cache, function cache, etc. 
-
-Note if these caches use an extension that provides the cache driver, the extension must be installed already.
-
-To declare cache connections, create a struct called `this.cache.connections` in the pseudo constructor of your `Application.cfc`. 
-
-Each key in the struct will be the name of the cache connection to create, and the value of the item will be another struct defining the properties of that cache connection.
+Add per-application cache connections in `Application.cfc` (Lucee 5.1+). If using an extension-provided cache driver, the extension must be installed first.
 
 ```lucee
 this.cache.connections["myCache"] = {
@@ -49,33 +41,28 @@ this.cache.connections["myCache"] = {
 };
 ```
 
-Note, there is a shortcut for `this.cache.connections["myCache"] = {}` and that is `this.cache["myCache"] = {}`. 
-
-Lucee supports both since the latter is closer to how datasources are defined.
+Shortcut: `this.cache["myCache"] = {}` (matches datasource syntax).
 
 ## Generating Cache Connection code
 
-The easiest way to generate the code block above is to follow these steps:
+Generate the code via Lucee Admin:
 
-1. Start up a Lucee server
-2. Create the cache you want via the web admin
-3. Edit the cache and scroll to the bottom
-4. Copy the code snippet that appears directly into your `Application.cfc`
+- Create the cache in Web Admin
+- Edit the cache, scroll to bottom
+- Copy the code snippet into `Application.cfc`
 
 ## Cache metadata
 
-Let's take a look at some of the keys used to define a cache connection.
-
-- **class** - This is the Java class of the driver for the cache engine.
-- **bundleName** - Optional. The name of the OSGI bundle to load the `class` from.
-- **bundleVersion** - Optional. The version of the OSGI bundle to load the `class` from.
-- **storage** - A boolean that flags whether this cache can be used for client or session storage.
-- **custom** - A struct of key/value pairs for configuring the cache. This struct is entirely dependent on the cache driver in use, so refer to the docs for that cache driver to see the possible values. Note, some of these custom values might be required for some cache drivers to work.
-- **default** - Optional. If you want this cache to be used as a default cache, then give this one of these values: `function`, `object`, `template`, `query`, `resource`, `include`, `http`, `file`, `webservice`.
+- **class** - Java class of the cache driver
+- **bundleName** - OSGi bundle name (optional)
+- **bundleVersion** - OSGi bundle version (optional)
+- **storage** - Enable for client/session storage
+- **custom** - Driver-specific key/value pairs (check driver docs for required values)
+- **default** - Set as default for: `function`, `object`, `template`, `query`, `resource`, `include`, `http`, `file`, `webservice`
 
 ## Default Caches
 
-When declaring a cache, you can make it the default cache for creation operations, but it is also possible to configure the default caches for each operation all at once in your `Application.cfc` like so:
+Configure default caches for each operation type:
 
 ```lucee
 this.cache.object = "myCache";
@@ -89,6 +76,4 @@ this.cache.file = "<cache-name>";
 this.cache.webservice = "<cache-name>";
 ```
 
-A single cache can only be the default storage location for a single operation at a time. 
-
-For example, a cache named "myCache" cannot both be the default cache for objects as well as queries.
+A single cache can only be default for one operation type (e.g. "myCache" can't be default for both objects and queries).

docs/recipes/checksum.md

@@ -22,13 +22,9 @@
 
 # Checksum
 
-This document explains how to use a checksum in Lucee.
+Validate downloads using checksums provided in response headers.
 
-Many servers provide a checksum for the files they provide for download. We use the checksum to validate a download file in order to avoid a corrupted file.
-
-If you download a file in your application, you can automatically check if the download is valid or not if the necessary info was provided in the response header.
-
-## Example 1
+## Download and Validate
 
 ```luceescript
 <cfscript>
@@ -61,50 +57,20 @@ dump("something went wrong! give it another try?");
 </cfscript>
 ```
 
-- Download the jar file by using cfhttp.
-- Dump the file response header. You can see the "X-Checksum-MD5" "X-Checksum-SHA1" keys from the file itself.
-- Save the file, and dump(fileInfo(localFile.checksum)). Check to see if the dump matches the value of the downloaded file response["X-Checksum-MD5"] header.
-
-Checksum values are hashed from the binaryfile itself.
-
-```luceescript
-dump(hash(fileReadBinary(localFile),"md5"));
-dump(hash(fileReadBinary(localFile),"SHA1"));
-```
-
-You can validate the checksum as shown below:
-
-```luceescript
-// validate file
-if(!isEmpty(res.responseheader["X-Checksum-MD5"]?:"")) {
-fi=fileInfo("esapi-2.1.0.1.jar");
-if(res.responseheader["X-Checksum-MD5"]==fi.checksum) {
-dump("we have a match!");
-}
-else {
-fileDelete("esapi-2.1.0.1.jar");
-dump("something went wrong! give it another try?");
-}
-}
-```
-
-If the checksum is provided, we can check it. However, the checksum may not always be provided. The following example shows how to provide a checksum for all downloads.
-
-## Example 2
+Check `X-Checksum-MD5` or `X-Checksum-SHA1` headers against `fileInfo().checksum` or `hash(fileReadBinary(file), "md5")`.
 
-//download.cfm
+## Providing Checksum Headers
 
 ```luceescript
 <cfscript>
+// download.cfm
 fi=fileInfo("esapi-2.1.0.1.jar");
 header name="Content-MD5" value=fi.checksum;
 content file="esapi-2.1.0.1.jar" type="application/x-zip-compressed";
 </cfscript>
 ```
 
-This code allows a downloading application to check if the download was successful or not. Adding the file with header content "Content-MD5" is not required.
-
-Download the file using the below example code:
+## Validate with Multiple Header Types
 
 ```luceescript
 <cfscript>
@@ -148,9 +114,4 @@ dump("something went wrong! give it another try?");
 </cfscript>
 ```
 
-The above code checks and validates the downloaded file.
-
-## Footnotes
-
-You can see the details in this video:
-[Checksum](https://www.youtube.com/watch?v=Kb_zSsRDEOg)
+Video: [Checksum](https://www.youtube.com/watch?v=Kb_zSsRDEOg)

docs/recipes/component-mappings.md

@@ -26,17 +26,11 @@
 
 # Component Mappings
 
-Component mappings in Lucee define locations where the server will look for CFML components (CFC files) when using the `createObject()` function or the `new` operator. 
+A mapping in Lucee is an alias that points to a directory - instead of using full filesystem paths, you use a short name. Lucee has three types: regular mappings (for templates/includes), custom tag mappings (for custom tags), and component mappings (for CFCs).
 
-They provide a way to organize and access your components without having to specify the full path each time.
+Component mappings define where Lucee looks for CFCs when using `createObject()` or `new`. This lets you organize and access components without specifying full paths - useful in larger applications with multiple component packages.
 
-## Understanding Component Mappings
-
-Component mappings provide a way to organize and access your CFC files without having to specify the full path each time. 
-
-This is particularly useful in large applications with multiple component packages.
-
-**Important**: Component mappings point to the root of package paths, not to individual components. 
+Mappings point to the root of package paths, not individual components. 
 
 For example, if you have a mapping pointing to:
 

docs/recipes/configuration-administrator-cfc.md

@@ -17,15 +17,12 @@
 }
 -->
 
-# Configure Lucee within your application
+# Configure Lucee Programmatically
 
-Lucee provides a web frontend to configure the server and each web context, but you can also do this configuration from within your application.
-(For per request settings, please check out the "Application.cfc" section in the [Cookbook](/guides/cookbooks.html)).
+Configure Lucee from code using `Administrator.cfc` (for per-request settings, see [[tag-application]]).
 
 ## Administrator.cfc
 
-Lucee provides the component "Administrator.cfc" in the package "org.lucee.cfml", a package auto imported in any template, so you can simply use that component as follows:
-
 ```cfs
 admin = new Administrator("web", "myPassword"); // first argument is the admin type you want to load (web|server), second is the password for the Administrator
 dump(admin); // show me the doc for the component
@@ -34,5 +31,4 @@ admin.updateCharset(resourceCharset: "UTF-8"); // set the resource charset
 
 ## cfadmin Tag
 
-The component "Administrator" is far from being feature complete, so if you miss a functionality, best consult the unofficial tag "cfadmin" (undocumented) and check out how this tag is used inside the [Lucee Administrator](https://github.com/lucee/Lucee/blob/5.2/core/src/main/java/resource/component/org/lucee/cfml/Administrator.cfc).
-Of course, it would be great if you could contribute your addition to the "Administrator" component.
+For functionality not in `Administrator.cfc`, check the undocumented `cfadmin` tag usage in the [Lucee Administrator source](https://github.com/lucee/Lucee/blob/7.0/core/src/main/java/resource/component/org/lucee/cfml/Administrator.cfc). Contributions welcome!

docs/recipes/console-logging.md

@@ -20,29 +20,17 @@
 }
 -->
 
-## Console Logging in Lucee
+# Console Logging
 
-Most CFML developers are familiar with using [[tag-dump]] when debugging.
+Most CFML developers are familiar with [[tag-dump]] for debugging. [[function-systemoutput]] is similar but writes to the console - useful for CLI scripts, background tasks, and CI environments.
 
-Lucee has a very useful function [[function-systemoutput]], which lets you write messages and dump objects to the console.
+Like [[tag-dump]], it can output both text and complex objects. The second argument `addNewLine` controls whether a newline is added (default: `false`).
 
-### What's the console?
+## Access the Console
 
-If you are using Tomcat, you can run it interactively using `catalina run` in the `tomcat\bin` directory.
-
-With [[getting-started-commandbox]], you can do similar, via `box server start --console`.
-
-Both then run the Server with the console logs being output.
-
-### What can we log?
-
-Similar to [[tag-dump]], [[function-systemoutput]] can output both text and complex objects.
-
-By default, it doesn't output new lines, the second boolean argument, `addNewLine` does what it says.
-
-### Use with CI like GitHub Actions
-
-When you are running tests remotely, any output from [[function-systemoutput]] is then visible directly in the job log.
+- **Tomcat**: `catalina run` in `tomcat\bin`
+- **CommandBox**: `box server start --console`
+- **CI/CD**: Output appears directly in job logs
 
 ## Example
 

docs/recipes/custom-tag-mappings.md

@@ -28,13 +28,7 @@
 
 # Custom Tag Mappings
 
-Custom tag mappings in Lucee define locations where the server will look for CFML custom tags when you use them in your code.
-
-They provide a way to organize and access your custom tags without having to specify the full path each time or use [[tag-import]] repeatedly.
-
-## Understanding Custom Tag Mappings
-
-Custom tags are reusable CFML templates that you can call like built-in tags. Custom tag mappings tell Lucee where to find these custom tag files.
+Custom tags are reusable CFML templates (`.cfm` files) that you can call like built-in tags. Custom tag mappings tell Lucee where to find these files, so you don't have to specify full paths or use [[tag-import]] repeatedly.
 
 For example, if you have a custom tag file at:
 

docs/recipes/datasource-how-to-define-them.md

@@ -18,32 +18,28 @@
 }
 -->
 
-# Datasource - How to define them
+# Datasources
 
-To execute queries, you need a datasource definition, which points to a specific local or remote datasource. There are different ways to do so.
+Define datasources to execute queries against local or remote databases.
 
-## Create a Datasource in the Administrator
+## Lucee Administrator
 
-The most common way to define a datasource is in the Lucee Server or Web Administrator. The only difference between the Web and Server Administrator is that datasources defined in the Server Administrator are visible to all web contexts, while datasources defined in the Web Administrator are only visible to the current web context.
-
-In your Administrator, go to the Page "Services/Datasource", in the section "create new Datasource" choose a name for your datasource and the type of your Datasource, for example "MySQL".
+Go to Services > Datasource, create a new datasource by choosing a name and type (e.g. MySQL).
 
 ![create datasource](https://bitbucket.org/repo/rX87Rq/images/3802808059-createds.png)
 
-On the following page, you can define settings to connect to your datasource. The look and feel of this page depend on the datasource type used. After saving this page, you get back to the overview page and you will get feedback if Lucee was able to connect to your datasource or not.
+Configure connection settings on the next page. Server Administrator datasources are visible to all web contexts; Web Administrator datasources only to the current context.
 
-## Create a Datasource in the Application.cfc
+## Application.cfc
 
-You cannot only define a datasource in the Lucee Administrator, you can also do this in the [application-context-guide]. The easiest way to do so is to create a datasource in the Administrator (see above) and then go to the detail view of this datasource by clicking the "edit button".
+Create a datasource in Administrator, then click "edit" to view its definition:
 
 ![select datasource](https://bitbucket.org/repo/rX87Rq/images/4142224660-select-datasource.png)
 
-At the bottom of the detail page, you find a box that will look like this:
+Copy the code from the bottom of the detail page:
 
 ![datasource application definition](https://bitbucket.org/repo/rX87Rq/images/1656402808-datasource-app-def.png)
 
-You can simply copy the code inside the box to your [application-context-guide] body, and Lucee will pick up this definition. After that, you can delete the datasource from the Administrator.
-
 ```cfs
 this.datasources["myds"] = {
     class: 'org.gjt.mm.mysql.Driver',
@@ -53,7 +49,7 @@ this.datasources["myds"] = {
 };
 ```
 
-Alternatively, you can also use this pattern:
+Or use this pattern:
 
 ```cfs
 this.datasources["myds"] = {
@@ -75,13 +71,13 @@ this.datasources["myds"] = {
 
 ### Default Datasource
 
-With the [application-context-guide], you can also define a default datasource that is used if no "datasource" attribute is defined with the tag cfquery, cfstoredproc, cfinsert, cfupdate, etc. Simply do the following:
+Define a default datasource used when no `datasource` attribute is specified in `cfquery`, `cfstoredproc`, etc.:
 
 ```cfs
 this.defaultdatasource = "myds";
 ```
 
-In that case, the datasource "myds" is used if there is no datasource defined. Instead of defining a datasource name, you can also define the datasource directly as follows:
+Or define the datasource inline:
 
 ```cfs
 this.datasource = {
@@ -91,3 +87,41 @@ this.datasource = {
     password: 'encrypted:5120611ea34c6123fd85120a0c27ab23fd81ea34cb854'
 };
 ```
+
+### Custom JDBC Drivers (Other)
+
+When using the "Other - JDBC Driver" type for databases without built-in support, provide:
+
+- **class**: The fully qualified JDBC driver class name
+- **connectionString**: The JDBC connection URL
+
+```cfs
+this.datasources["mydb"] = {
+    class: 'com.example.jdbc.Driver',
+    connectionString: 'jdbc:example://localhost:1234/mydb',
+    username: 'user',
+    password: 'pass'
+};
+```
+
+For OSGi-based JDBC drivers (JARs deployed as bundles in `/lucee-server/bundles/`), you can also specify:
+
+- **bundleName**: The OSGi bundle symbolic name
+- **bundleVersion**: The OSGi bundle version
+
+```cfs
+this.datasources["mydb"] = {
+    class: 'com.example.jdbc.Driver',
+    connectionString: 'jdbc:example://localhost:1234/mydb',
+    bundleName: 'com.example.jdbc',
+    bundleVersion: '1.2.3',
+    username: 'user',
+    password: 'pass'
+};
+```
+
+This is useful when:
+
+- Using database drivers not bundled with Lucee
+- Deploying drivers as OSGi bundles for better version management
+- Working with multiple versions of the same driver

docs/recipes/directory-placeholders.md

@@ -17,7 +17,7 @@
 
 ## Directory Placeholders ##
 
-In order to make configuring Lucee a little easier, there are several constants (we call them "directory placeholders") that contain a certain value which might change depending on the system, the environment or the context.
+Directory placeholders are constants you can use in Lucee configuration instead of hardcoding paths. They resolve to actual paths at runtime, making your config portable across different systems and environments.
 
 ### Available Directory Placeholders ###