Configuration
CBWIRE provides extensive configuration options to customize its behavior for your application needs. You can override the default settings by adding configuration in your ColdBox application's config/ColdBox.bx for BoxLang or config/ColdBox.cfc for CFML.
All CBWIRE configuration is placed within the moduleSettings
struct under the cbwire
key. Here's a complete example showing all available configuration options with their default values:
// config/ColdBox.bx
class {
function configure() {
moduleSettings = {
"cbwire": {
// Asset Management
"autoInjectAssets": true,
"moduleRootURL": "/modules/cbwire",
// Component Configuration
"wiresLocation": "wires",
"trimStringValues": false,
"throwOnMissingSetterMethod": false,
// Request Handling
"updateEndpoint": "/cbwire/updates",
"maxUploadSeconds": 300, // 5 minutes
// UI Features
"showProgressBar": true,
"progressBarColor": "#2299dd",
// Security
"csrfEnabled": false,
"csrfStorage": "SessionStorage@cbstorages",
"checksumValidation": true
}
};
}
}
Asset Management
autoInjectAssets
Controls whether CBWIRE automatically includes its CSS and JavaScript assets in your pages. When enabled, you don't need to manually add wireStyles()
in your layout's <head>
or wireScripts()
before the closing </body>
tag.
Default: true
moduleSettings = {
"cbwire": {
"autoInjectAssets": false
}
};
When disabled, you'll need to manually include the assets in your layout:
<!-- In your layout's <head> -->
#wireStyles()#
<!-- Before closing </body> -->
#wireScripts()#
moduleRootURL
Specifies the root URL path for CBWIRE module assets and endpoints. Useful when your application is deployed in a subdirectory or when using custom URL mappings.
Default: /modules/cbwire
Component Configuration
wiresLocation
Defines the directory where your CBWIRE components are stored, relative to your application root. This affects component auto-discovery and naming conventions.
Default: wires
moduleSettings = {
"cbwire": {
"wiresLocation": "app/components"
}
};
trimStringValues
When enabled, automatically trims whitespace from string values in component data properties during updates. This is particularly useful for form inputs where users might accidentally include leading or trailing spaces.
Default: false
You can also enable this setting on individual components:
// wires/ContactForm.bx
class extends="cbwire.models.Component" {
trimStringValues = true;
data = {
"name": "",
"email": "",
"message": ""
};
}
Changing the wiresLocation
after components have been created will require updating your component references and possibly your routing configuration.
throwOnMissingSetterMethod
Controls whether CBWIRE throws an exception when trying to set a property that doesn't have a corresponding setter method. When disabled, missing setters are silently ignored.
Default: false
Request Handling
updateEndpoint
Sets the URI endpoint where CBWIRE processes component updates and actions. You may need to modify this if URL rewriting is disabled or if you're using custom routing.
Default: /cbwire/updates
moduleSettings = {
"cbwire": {
"updateEndpoint": "/index.cfm/cbwire/updates"
}
};
maxUploadSeconds
Specifies the maximum time (in seconds) allowed for file upload operations to complete. This prevents long-running uploads from consuming server resources indefinitely.
Default: 300
(5 minutes)
moduleSettings = {
"cbwire": {
"maxUploadSeconds": 600 // 10 minutes
}
};
UI Features
showProgressBar
Controls whether a progress bar appears at the top of the page during wire:navigate operations. The progress bar provides visual feedback during page transitions.
Default: true
moduleSettings = {
"cbwire": {
"showProgressBar": false
}
};
progressBarColor
Customizes the color of the progress bar displayed during wire:navigate operations. Accepts any valid CSS color value.
Default: #2299dd
moduleSettings = {
"cbwire": {
"progressBarColor": "#ff6b35"
}
};
Security Configuration
csrfEnabled
Enables Cross-Site Request Forgery (CSRF) protection for CBWIRE requests. When enabled, all component actions require a valid CSRF token.
Default: false
moduleSettings = {
"cbwire": {
"csrfEnabled": true
}
};
csrfStorage
Specifies the WireBox mapping for the storage provider used to store CSRF tokens. The storage provider must implement the appropriate interface for session or cache storage.
Default: SessionStorage@cbstorages
moduleSettings = {
"cbwire": {
"csrfStorage": "CacheStorage@cbstorages"
}
};
CSRF protection will be enabled by default starting in CBWIRE 5.0. It's recommended to enable and test CSRF protection in your applications now to ensure compatibility.
checksumValidation
Enables or disables checksum validation for component payloads. This security feature validates the integrity of data sent between the client and server to prevent tampering.
Default: true
moduleSettings = {
"cbwire": {
"checksumValidation": false
}
};
Last updated
Was this helpful?