Core Delegates
Built-in delegates shipped with ColdBox/WireBox for common everyday tasks
WireBox ships with a set of built-in core delegates that you can drop into any object in your application. They are registered under the @coreDelegates WireBox namespace, so you only need to reference them by their short name.
Core delegates work in both BoxLang and CFML and can be composed using the delegates component annotation or individual property injections.
Available Core Delegates
Async@coreDelegates
coldbox.system.core.delegates.Async
Async/parallel programming via the ColdBox AsyncManager
DateTime@coreDelegates
coldbox.system.core.delegates.DateTime
Date and time utilities via DateTimeHelper
Env@coreDelegates
coldbox.system.core.delegates.Env
Java system properties and OS environment variables
Flow@coreDelegates
coldbox.system.core.delegates.Flow
Fluent flow-control methods for expressive chaining
JsonUtil@coreDelegates
coldbox.system.core.delegates.JsonUtil
JSON serialization utilities
Population@coreDelegates
coldbox.system.core.delegates.Population
Object population from structs, JSON, XML, and queries
StringUtil@coreDelegates
coldbox.system.core.delegates.StringUtil
String manipulation and formatting utilities
How to Use Core Delegates
Use the delegates component annotation for a concise declaration:
// Single delegate
class delegates="Flow@coreDelegates" {
}
// Multiple delegates
class delegates="Flow@coreDelegates, StringUtil@coreDelegates, Env@coreDelegates" {
}// Single delegate
component delegates="Flow@coreDelegates" {
}
// Multiple delegates
component delegates="Flow@coreDelegates, StringUtil@coreDelegates, Env@coreDelegates" {
}Or use individual property injections when you need prefixes/suffixes or targeted method lists:
Async
WireBox ID: Async@coreDelegates
Class: coldbox.system.core.delegates.Async
Provides access to the ColdBox AsyncManager and its most common utilities for asynchronous and parallel programming.
Methods
async()
Returns the AsyncManager instance directly
newFuture(...)
Delegated from AsyncManager — creates and returns a new Future object
arrayRange(...)
Delegated from AsyncManager — creates a ranged parallel stream from an array
Usage
DateTime
WireBox ID: DateTime@coreDelegates
Class: coldbox.system.core.delegates.DateTime
Delegates all public methods from coldbox.system.async.time.DateTimeHelper directly onto your class, giving you a rich date/time API without any extra boilerplate.
Since all methods come from DateTimeHelper, refer to its API docs for the full method list.
Usage
Env
WireBox ID: Env@coreDelegates
Class: coldbox.system.core.delegates.Env
Provides utilities for reading Java system properties and OS environment variables. Methods search Java system properties first, then environment variables unless specified otherwise.
Methods
getSystemSetting( key, defaultValue )
Returns the value from Java system properties first, then OS env vars. Throws SystemSettingNotFound if missing and no default given.
getSystemProperty( key, defaultValue )
Returns a Java system property (-Dkey=value) only. Throws SystemSettingNotFound if missing and no default given.
getEnv( key, defaultValue )
Returns an OS environment variable only. Throws SystemSettingNotFound if missing and no default given.
getJavaSystem()
Returns the raw java.lang.System instance.
Usage
Flow
WireBox ID: Flow@coreDelegates
Class: coldbox.system.core.delegates.Flow
Provides fluent flow-control methods modeled after functional programming patterns. All methods return the parent object so you can chain calls expressively.
Flow is a transient delegate. If you inject it into a singleton, WireBox will correctly handle the $parent reference per-injection, but be aware that shared state issues can arise. Prefer using the component delegates annotation so WireBox manages the lifecycle.
Methods
peek( target )
Executes the closure with the parent as its argument and returns the parent for chaining.
when( target, success, failure )
Runs success if target is truthy; runs failure if provided and target is falsy.
unless( target, success, failure )
Runs success if target is falsy; runs failure if provided and target is truthy.
throwIf( target, type, message, detail )
Throws an exception if target evaluates to true.
throwUnless( target, type, message, detail )
Throws an exception if target evaluates to false.
ifNull( target, success, failure )
Runs success if target is null; runs failure if provided and target is not null.
ifPresent( target, success, failure )
Runs success if target is not null; runs failure if provided and target is null.
Usage
JsonUtil
WireBox ID: JsonUtil@coreDelegates
Class: coldbox.system.core.delegates.JsonUtil
Provides opinionated JSON serialization utilities. The toJson, prettyJson, and toPrettyJson methods are delegated from coldbox.system.core.util.Util.
Methods
toJson( data )
Serializes any data to a JSON string.
prettyJson( data )
Serializes data to an indented, human-readable JSON string.
toPrettyJson( data )
Alias for prettyJson().
forAttribute( data )
Serializes to JSON (or leaves as-is if simple value) then encodes the result for safe HTML attribute use.
Usage
Population
WireBox ID: Population@coreDelegates
Class: coldbox.system.core.delegates.Population
Provides object population backed by the WireBox Object Populator. Delegates can be used to bind incoming data from forms, REST APIs, XML feeds, or database queries directly onto your object properties.
The target argument defaults to $parent, meaning the delegate will populate itself (the object that declared the delegation). You can override target to populate a different object.
Methods
populate( memento, ... )
Populate from a struct/map.
populateWithPrefix( memento, prefix, ... )
Populate using prefixed keys (e.g., user_name → name with prefix user).
populateFromJSON( JSONString, ... )
Populate from a JSON string.
populateFromXML( xml, root, ... )
Populate from an XML string or XML object.
populateFromQuery( qry, rowNumber, ... )
Populate from a query row.
All methods accept the following common arguments:
scope
""
Use scope injection instead of setters
trustedSetter
false
Call setters without checking if they exist (useful with onMissingMethod)
include
""
Comma-delimited list of keys to populate exclusively
exclude
""
Comma-delimited list of keys to skip
ignoreEmpty
false
Skip empty values during population
nullEmptyInclude
""
Keys to set to null when the incoming value is empty
nullEmptyExclude
""
Keys to not set to null when empty
composeRelationships
false
Automatically compose object relationships from the incoming data
ignoreTargetLists
false
Ignore population include/exclude metadata defined on the target itself
Usage
StringUtil
WireBox ID: StringUtil@coreDelegates
Class: coldbox.system.core.delegates.StringUtil
Provides string manipulation and formatting utilities covering case conversion, slugification, SQL formatting, and basic English pluralization.
Methods
prettySql( target )
Formats a SQL string with newlines and indentation for readability.
slugify( str, maxLength, allow )
Creates a URL-safe slug. maxLength=0 means no limit; allow is a regex safe-list of extra allowed chars.
camelCase( target )
Converts snake_case or kebab-case to camelCase.
headline( target )
Converts a delimited or cased string to Title Case With Spaces.
ucFirst( target )
Uppercases the first character of a string.
lcFirst( target )
Lowercases the first character of a string.
kebabCase( target )
Converts a string to kebab-case.
snakeCase( target, delimiter )
Converts a string to snake_case. delimiter defaults to _.
pluralize( word )
Returns the plural form of an English word.
singularize( word )
Returns the singular form of an English word.
Usage
Last updated
Was this helpful?