improve recipes

Author: zspitzer

docs/recipes/exception-cause.md

@@ -26,7 +26,7 @@ Lucee 6.1 improves its support for exception causes, providing better debugging
 
 ## Tag Attribute cause
 
-The `<cfthrow>` tag now includes a new attribute, `cause`, which allows you to add a cause to a newly created exception.
+The `<cfthrow>` tag now includes a `cause` attribute to chain exceptions:
 
 ```run
 <cfscript>
@@ -45,11 +45,11 @@ catch(ex) {
 </cfscript>
 ```
 
-Thanks to this enhancement, you get not only the tag context and Java stack trace from the top-level exception, but also the same information for the "cause" exception.
+This gives you the tag context and Java stack trace from both the top-level exception and its cause.
 
 ## Parent Thread Context
 
-When you throw an exception from a child thread, for example, a `cfhttp` call executed in parallel or an exception inside the `cfthread` tag, you can now see the stack trace from where that thread was started. Previously, you only saw the stack trace within the child thread. With Lucee 6.1, you also get the information from the parent thread as the cause. Consider the following example:
+Exceptions from child threads (parallel `cfhttp`, `cfthread`) now include the parent thread's stack trace as the cause - previously you only saw the child thread's stack trace:
 
 ```run
 <cfscript>
@@ -62,4 +62,4 @@ dump(cfthread["testexception"].error.cause.Message);
 </cfscript>
 ```
 
-The error not only includes the exception information from within the cfthread tag but also provides information from outside, making debugging much easier as you can see where the tag was called from.
+The error includes both the exception from within `cfthread` and where it was called from, making debugging much easier.

docs/recipes/extension-installation.md

@@ -23,11 +23,7 @@
 
 # Extension Installation
 
-In Lucee, there are multiple ways to install an extension. This recipe will show you all the possibilities along with their pros and cons.
-
-The standard Lucee jar, (known as the far jar) bundles a number of common extensions (pdf, image etc).
-
-If you want to control which extensions are installed, use Lucee Light (core and admin) or Lucee Zero (core only).
+Multiple ways to install extensions in Lucee. The standard jar bundles common extensions (pdf, image etc) - use Lucee Light or Zero for more control.
 
 ## Lucee Administrator
 
@@ -188,14 +184,3 @@ java -Dlucee.extensions="99A4EF8D-F2FD-40C8-8FB8C2E67A4EEEB6;name=MSSQL;version=
 ## Logging and Troubleshooting
 
 If you encounter issues while installing extensions, you can check the log at `{lucee-installation}/lucee-server/context/logs/deploy.log` not only for any errors reported but also to see what actions were performed. This log is by default set to info level and should contain all details about the installation process.
-
-## Conclusion
-
-Lucee offers several methods to install extensions, each with its own advantages and disadvantages. Choose the method that best fits your deployment and management workflow:
-
-- **Lucee Administrator**: Best for manual, ad-hoc installations.
-- **`deploy` Directory**: Good for automated deployments with script support.
-- **`.CFConfig.json` Configuration**: Ideal for managing configurations and extensions together.
-- **Environment Variable / System Property**: Suitable for modern deployment environments like Docker and cloud services.
-
-By understanding the pros and cons of each method, you can effectively manage Lucee extensions in your environment.

docs/recipes/externalizing-strings.md

@@ -16,15 +16,14 @@
 }
 -->
 
-# Externalize strings
+# Externalize Strings
 
-Externalize strings from generated class files to separate files. This method is used to reduce the memory of the static contents for templates. We explain this method with a simple example below:
+When Lucee compiles a `.cfm` file, all the static HTML and strings get embedded directly in the Java class file. For pages with lots of static content (like email templates or HTML-heavy pages), this bloats the class files and wastes memory - those strings stay loaded even when not needed.
 
-**Example:**
-
-//index.cfm
+Externalizing strings moves this static content to separate text files. The class file shrinks, and strings only load on demand when the page actually runs.
 
 ```lucee
+<!--- index.cfm - mostly static HTML with a bit of CFML --->
 <cfset year = 1960>
 <html>
     <body>
@@ -38,21 +37,12 @@ Externalize strings from generated class files to separate files. This method is
 </html>
 ```
 
-1. Here the Index.cfm file contains a lot of strings (static contents), but there is no functionality. The file just gives a cfoutput with year. The variable string 'year' is already declared by using in top of the Index.cfm page.
-
-2. Execute the CFM page in a browser. A class file is created in the `webapps/ROOT/WEB-INF/lucee/cfclasses/` directory while the CFM file is executed. The run time compiler compiles that file to load the Java bytecode and execute it.
-
-3. Right click the class file. Then see `Get info`. For example, in my class file there is 8Kb size on the disk. In Lucee, the CFM file with its strings was also loaded. So a lot of memory could be occupied just by string loading the bytecode. To avoid this problem, the Lucee admin has the following solution:
-
-   - Lucee admin --> Language/compiler --> Externalize strings
-   - This `Externalize strings` setting has four options. Select any one option to test. We selected the fourth option (externalize strings larger than 10 characters).
-   - Again run the CFM page in a browser. The class file is created with lower memory size than the original 8Kb on disk.
-   - In addition, it created a text file too. The text file contains the strings from the CFM page. The cfoutput with year is simply not there. The byte code will crop the piece of cfoutput content from the CFM file.
-
-So, the string 'year' is no longer in memory. When the bytecode is called, it loads the string into memory. The memory is not occupied forever and this reduces the footprint of our application.
+Without externalization, all that HTML lives in the class file. With it enabled, only the CFML logic stays in the class.
 
-## Footnotes
+Configure via **Lucee Admin > Language/compiler > Externalize strings**:
 
-Here you can see the above details in video
+- Strings are moved to separate text files
+- Class file size decreases
+- Strings load on demand instead of staying in memory
 
-[Externalize strings](https://youtu.be/AUcsHkVFXHE)
+Video: [Externalize strings](https://youtu.be/AUcsHkVFXHE)

docs/recipes/file-extensions.md

@@ -19,11 +19,11 @@
 
 # File Extensions
 
-Lucee supports several file extensions for different types of templates and components. The most common extensions are `.cfm`, `.cfc`, `.cfml`, and `.cfs`. Each serves a specific purpose in CFML development.
+Lucee processes several file types, each serving a different purpose in CFML development. Knowing when to use each helps keep your code organized.
 
 ## .cfm
 
-The `.cfm` extension is used for CFML templates. These files contain CFML code that is processed by the server to generate dynamic web pages.
+The standard CFML template extension. These files mix CFML tags and HTML to generate dynamic web pages - the workhorse of most CFML applications.
 
 ### Example
 
@@ -44,7 +44,7 @@ The `.cfm` extension is used for CFML templates. These files contain CFML code t
 
 ## .cfc
 
-The `.cfc` extension is used for CFML Components (CFCs). These files define reusable components that encapsulate functionality in methods, similar to classes in object-oriented programming.
+CFML Components define reusable objects that encapsulate data and behavior - similar to classes in other languages. Use these for your business logic, models, and services.
 
 ### Example
 
@@ -58,11 +58,11 @@ component {
 
 ## .cfml
 
-The `.cfml` extension is an alternative to `.cfm` and can be used for CFML templates. It serves the same purpose as `.cfm` but is less commonly used.
+Alternative extension for CFML templates - functionally identical to `.cfm`. Some developers prefer the explicit `.cfml` extension, but `.cfm` is far more common.
 
 ## .cfs
 
-Since version 6.0, Lucee supports templates with the extension `.cfs`. These templates contain script code, similar to `.js` files in the JavaScript world. This allows you to write direct script code without the need for the `<cfscript>` tag.
+Script-only templates introduced in Lucee 6.0. Like `.js` files in the JavaScript world, these contain pure script code without needing `<cfscript>` tags. Great for scripts, utilities, and developers who prefer script syntax over tags.
 
 ### Example
 

docs/recipes/function-listeners.md

@@ -23,7 +23,7 @@
 
 # Function Listeners
 
-Lucee 6.1 introduced a new feature called "Function Listeners". This allows you to execute a function (of any kind) in parallel, so you do not have to wait for the result of the execution, similar to using the `cfthread` tag. Function Listeners provide an easy syntax to not only execute a function in parallel but also include support to handle the result by simply adding a listener after the function call. This listener can handle the result or exception of a function.
+Execute functions in parallel with a simple listener syntax. Like `cfthread` but cleaner - attach a listener after any function call to handle results or exceptions asynchronously.
 
 ## Simple Version
 

docs/recipes/hidden-gems.md

@@ -11,29 +11,30 @@
     "Bracket notation",
     "URL form scopes",
     "Array format"
+  ],
+  "categories": [
+    "language"
   ]
 }
 -->
 
 # Hidden Gems
 
-This document explains how to declare variables, function calls with dot and bracket notation, and passing arguments via URL/form scopes as an array. These concepts are explained with simple examples below:
+Lesser-known Lucee features that can make your code cleaner and more flexible. These aren't obscure - they're useful patterns that many developers overlook.
 
-## Example 1: Declare Variables
-
-// test.cfc
+## Variable Declaration
 
 ```luceescript
+// test.cfc
 component {
 	function getName() {
 		return "Susi";
 	}
 }
 ```
 
-// example1.cfm
-
 ```luceescript
+// example.cfm
 function test() {
 	var qry;
 	dump(qry);
@@ -45,50 +46,42 @@ function test() {
 test();
 ```
 
-In the cfm page, we have a test() function with a local variable scope assigned as an empty string `var qry`. When executing this cfm, the qry returns "1". Dumping the `qry` below the var declaration returns an empty string.
-
-## Example 2: Dot and Bracket Notation for Function Calls
+Declaring `var qry` creates an empty local variable. The query then populates it.
 
-Lucee allows you to use bracket notation to call a component function.
+## Bracket Notation for Function Calls
 
-// example2.cfm
+You can call component methods using bracket notation instead of dot notation. This lets you call functions dynamically without the overhead and security concerns of `evaluate()`:
 
 ```luceescript
-// UDF call via dot notation
+// Standard dot notation
 test = new Test();
 dump( test.getName() );
-// Dynamic function name
+
+// Dynamic with evaluate (avoid this)
 funcName = "getName";
-dump(evaluate('test.#funcName#()'));
-// UDF call via bracket notation
+dump( evaluate('test.#funcName#()') );
+
+// Dynamic with bracket notation (better!)
 funcName = "getName";
 dump( test[funcName]() );
 ```
 
-These three different types of function calls are:
-
-- Calling the user-defined function `getName()` from the component.
-- Dynamic function name with evaluate function.
-- User-defined function via bracket notation.
-
-All three different function calls return the same content "Susi" as defined in the CFC page.
-
-## Example 3: Passing Arguments via URL/Form Scopes as Array
+All three return "Susi", but bracket notation is cleaner and safer than `evaluate()`.
 
-Lucee allows passing URL and Form scope data as an array instead of a string list.
+## URL/Form Arrays
 
-// example3.cfm
+When you have multiple form fields or URL parameters with the same name, Lucee normally merges them into a comma-separated string. Adding `[]` to the name tells Lucee to return an array instead - much easier to work with:
 
 ```lucee
 <cfscript>
 	dump(label:"URL", var:url);
 	dump(label:"Form", var:form);
-	// current name
 	curr = listLast(getCurrentTemplatePath(),'\/');
 </cfscript>
 
 <cfoutput>
 	<h1>Countries</h1>
+	<!--- Note the [] in country[] --->
 	<form method="post" action="#curr#?country[]=USA&country[]=UAE">
 		<pre>
 			Countries Europe:	<input type="text" name="country[]" value="Switzerland,France,Germany" size="30">
@@ -99,25 +92,6 @@ Lucee allows passing URL and Form scope data as an array instead of a string lis
 </cfoutput>
 ```
 
-// index.cfm
-
-```luceescript
-directory sort="name" action="list" directory=getDirectoryFromPath(getCurrentTemplatePath()) filter="example*.cfm" name="dir";
-loop query=dir {
-	echo('<a href="#dir.name#">#dir.name#</a><br>');
-}
-```
-
-In this cfm page, URL and form scopes are available. The names are used twice.
-
-- The query string on the URL scope has the same name `country` twice. Similarly, the form also has two fields with the same name `country`.
-- Execute this cfm page in the browser & submit the form. It shows a single URL string list in merged format instead of two fields & Form fields also merged as a single `country` field.
-- Adding square brackets behind the name `country[]` means it returns two separate strings in array format. You will see the difference in the browser while dumping that name with square brackets.
-
-These simple methods are helpful for defining variables in different ways.
-
-## Footnotes
-
-Here you can see the above details in the video
+With `country` you get `"USA,UAE"` (string). With `country[]` you get `["USA","UAE"]` (array).
 
-[Lucee Hidden Gems](https://youtu.be/4MUKPiQv1kAsss)
+Video: [Lucee Hidden Gems](https://youtu.be/4MUKPiQv1kA)

docs/recipes/hooks-and-monitors.md

@@ -18,7 +18,7 @@
 
 # Hooks and Monitors
 
-Lucee provides two powerful extension mechanisms that allow you to inject custom functionality at different points in the application lifecycle: **Hooks** and **Monitors**. These systems enable you to extend Lucee's capabilities, implement custom initialization logic, collect runtime metrics, and integrate with external systems seamlessly.
+Two extension mechanisms for custom functionality: **Hooks** run at lifecycle points (startup), **Monitors** collect runtime metrics (requests, actions, intervals).
 
 ## AI-Optimized Technical Reference
 

docs/recipes/http-logging.md

@@ -19,35 +19,16 @@
 
 # Logging CFHTTP Calls
 
-As of Lucee 6.1.0.135, all `cfhttp` calls are logged by default to a dedicated `http` log file at the log level `info`. This logging behavior provides more visibility into HTTP requests made through Lucee applications, helping to track external requests easily.
-
-## Default Logging Behavior
-
-In the default setup, Lucee logs HTTP requests with the following settings:
-
-- **Log File**: `http.log` (If the `http.log` log does not exist, entries are directed to `application.log`).
-- **Log Level**: `info`.
+All `cfhttp` calls are logged by default to a dedicated `http` log file at `info` level (falls back to `application.log` if `http.log` doesn't exist).
 
 ### Example Log Entry
 
-An example entry for a `cfhttp` call might look like this:
-
 ```plaintext
 "TRACE","pool-3-thread-2","10/29/2024","18:31:04","cftrace","httpRequest [GET] to [https://lucee.org], returned [200 OK] in 294ms, at /index.cfm:10; /index.cfm.callLucee():20"
 ```
 
-This log entry includes:
-
-- **Request Details**: Method (`GET`), URL (`https://lucee.org`)
-- **Response Status**: `[200 OK]`
-- **Response Time**: `294ms`
-- **Source Location**: Code locations responsible for the request.
-
-## Changes in Logging Behavior (Pre-Lucee 6.1.0.135)
-
-In earlier versions of Lucee, before version 6.1.0.135:
+Includes method, URL, response status, time, and source location.
 
-- **Log File**: Only `application.log` was used for logging HTTP requests.
-- **Log Level**: `trace` instead of `info`.
+## Pre-6.1.0.135 Behavior
 
-The change to a dedicated `http` log and `info` level helps separate HTTP logs from other system logs, improving clarity.
+Earlier versions logged to `application.log` at `trace` level instead.