### Install and Setup cbwire Project
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/README.md
Commands to initialize a new ColdBox application, install the cbwire module, and start the development server using CommandBox.
```bash
mkdir cbwire-demo
cd cbwire-demo
box coldbox create app .
box install cbwire
box server start
```
--------------------------------
### Install cbwire using CommandBox
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/quick-start.md
This command installs the cbwire library into your project using the CommandBox CLI tool. Run it from your project's root directory.
```shell
box install cbwire
```
--------------------------------
### Integrate cbwire Components into Layout
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/README.md
Example of a ColdBox layout file (Main.cfm) demonstrating how to include cbwire CSS, JavaScript, and components using wireStyles(), wireScripts(), and wire() helper methods.
```HTML/CFML
<-- ./layouts/Main.cfm -->
#wireStyles()#
#wire( "Counter" )#
#wireScripts()#
```
--------------------------------
### Install CommandBox cbwire module
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/essentials/creating-components.md
This command installs the `commandbox-cbwire` module into your CommandBox environment, enabling component scaffolding functionalities.
```javascript
install commandbox-cbwire
```
--------------------------------
### Install latest bleeding-edge cbwire using CommandBox
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/essentials/installation.md
This command installs the latest bleeding-edge (development) version of the cbwire framework using the CommandBox CLI. For example, it might install cbwire@2.0.0-snapshot.
```bash
box install cbwire@be
```
--------------------------------
### Example of cbwire Component View Structure
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/essentials/rendering-components.md
This example illustrates the structure of a cbwire component view file, such as `counter.cfm`. It highlights the critical requirement for an outer HTML element, like a `
`, to ensure cbwire can properly bind to the component's output. Failing to include an outer element will result in an `OuterElementNotFound` exception, as demonstrated by the 'BAD' example.
```xml
// File: ./views/wires/counter.cfm
```
--------------------------------
### Integrate cbwire styles and scripts into ColdFusion layout
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/quick-start.md
This ColdFusion Markup (CFM) snippet demonstrates how to include the necessary `wireStyles()` and `wireScripts()` helper methods within your main layout file. These methods are crucial for cbwire's functionality, injecting required CSS and JavaScript into your HTML.
```coldfusion
#wireStyles()#
cbwire is fire!
#renderView()#
#wireScripts()#
```
--------------------------------
### Implementing Prefetching with cbwire in CFML
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/ui-goodies/prefetching.md
This example demonstrates how to use the `.prefetch` modifier on a `wire:click` action in a CFML view, and the corresponding ColdFusion Component (CFC) that handles the prefetchable action. The view uses `wire:click.prefetch` to trigger the `togglePreview` action on mouseover, while the CFC defines the `togglePreview` function and manages component state.
```CFML
// File: ./views/wires/movie.cfm
```
```CFML
// File: ./wires/Movie.cfc
component extends="cbwire.models.Component"{
variables.data = {
"showPreview": false
};
function togglePreview(){
variables.data.contentIsVisible = true;
}
function renderIt(){
return this.renderView( "wires/movie" );
}
}
```
--------------------------------
### Define and trigger a cbwire component action
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/essentials/actions.md
This example demonstrates how to define an action method within a ColdFusion (CFC) cbwire component and how to invoke that action from the HTML template using the `wire:click` directive. The action modifies component data, which then re-renders the UI.
```cfc
component extends="cbwire.model.Component"{
// Data property
variables.data = {
"counter": 0
};
// Action
function increment(){
variables.data.counter += 1;
}
}
```
```html
```
--------------------------------
### Log messages within a CBWIRE Component
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/component-features/logging.md
Demonstrates how to use the automatically injected `log` object within a CBWIRE component's methods to output informational and debug messages. This provides immediate access to logging without explicit setup.
```javascript
component extends="cbwire.models.Component"{
function mount(){
log.info( "mount() called" );
}
function someAction(){
log.debug( "someAction() called" );
}
}
```
--------------------------------
### Implicit View Lookup in cbwire Components
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/essentials/rendering-components.md
When neither `renderIt()` nor `variables.view` is explicitly defined, cbwire performs an implicit view lookup. It searches for a view file whose name matches the component's filename, typically in a `views/wires/` directory. For example, `Counter.cfc` would implicitly look for `counter.cfm`, requiring lowercase filenames for compatibility.
```javascript
// File: ./wires/Counter.cfc
component extends="cbwire.models.Component" {
// No explicit view defined.
}
```
--------------------------------
### Reference and Mutate Data Properties in cbwire Component Logic
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/essentials/properties.md
This example shows how to access and modify a reactive data property, `counter`, directly within a cbwire component's action method (`increment`). The `variables.data` scope holds the property definitions and their current values.
```javascript
// File: wires/Counter.cfc
component extends="cbwire.models.Component"{
// Data properties
variables.data = {
"counter": 0
};
// Action called from UI
function increment(){
variables.data.counter += 1;
}
...
}
```
--------------------------------
### cbwire create command API reference
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/essentials/creating-components.md
This API documentation outlines the full signature and available arguments for the `cbwire create` command. It details each parameter's name, type, default value, and purpose, allowing for comprehensive customization of component generation.
```APIDOC
/**
* @name Name of the component to create without the .cfc.
* @actions Comma-delimited list of actions to generate.
* @views Generate a view for the cbwire component.
* @viewsDirectory Directory where your views are stored. Only used if views is set to true.
* @integrationTests Generate the integration test component
* @testsDirectory Your integration tests directory. Only used if integrationTests is true
* @directory Base directory to create your handler in and creates the directory if it does not exist. Defaults to 'handlers'.
* @description Component hint description.
* @open Opens the component (and test(s) if applicable) once generated.
**/
function run(
required string name,
string actions = "",
boolean views = true,
string viewsDirectory = "views/wires",
boolean integrationTests = true,
string testsDirectory = "tests/specs/integration/wires",
string directory = "wires",
string description = "I am a new cbwire component.",
boolean open = false
)
```
--------------------------------
### ColdBox `relocate` Method API Reference
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/component-features/redirecting.md
This section provides the API documentation for the `relocate` method, detailing its purpose and all available parameters. It outlines how to specify redirection targets (event, URL, URI), manage query strings, persist data, and control SSL and base URL settings, along with other advanced options.
```APIDOC
/**
* Relocate user browser requests to other events, URLs, or URIs.
*
* @event The name of the event to run, if not passed, then it will use the default event found in your configuration file
* @URL The full URL you would like to relocate to instead of an event: ex: URL='http://www.google.com'
* @URI The relative URI you would like to relocate to instead of an event: ex: URI='/mypath/awesome/here'
* @queryString The query string or struct to append, if needed. If in SES mode it will be translated to convention name value pairs
* @persist What request collection keys to persist in flash ram
* @persistStruct A structure key-value pairs to persist in flash ram
* @addToken Wether to add the tokens or not. Default is false
* @ssl Whether to relocate in SSL or not
* @baseURL Use this baseURL instead of the index.cfm that is used by default. You can use this for ssl or any full base url you would like to use. Ex: https://mysite.com/index.cfm
* @postProcessExempt Do not fire the postProcess interceptors
* @statusCode The status code to use in the relocation
*/
void function relocate(
event,
URL,
URI,
queryString,
persist,
struct persistStruct,
boolean addToken,
boolean ssl,
baseURL,
boolean postProcessExempt,
numeric statusCode
);
```
--------------------------------
### Create a basic cbwire Counter component
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/essentials/creating-components.md
This command scaffolds a new cbwire component named 'Counter'. It generates the component CFC, its corresponding view file, and an integration test file in their default locations.
```javascript
cbwire create Counter
// Created /wires/Counter.cfc
// Created /views/wires/counter.cfm
// Created /tests/specs/integration/wires/CounterTest.cfc
```
--------------------------------
### Create cbwire component without view file
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/essentials/creating-components.md
This command demonstrates creating a cbwire component named 'Counter' while explicitly preventing the generation of its view file using the `views=false` argument. It still creates the CFC and test file.
```javascript
cbwire create name=Counter views=false
// Created /wires/Counter.cfc
// Created /tests/specs/integration/wires/CounterTest.cfc
```
--------------------------------
### Define View with renderIt() Method in cbwire Component
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/essentials/rendering-components.md
The `renderIt()` method allows explicit definition of a component's template in cbwire. It uses `this.renderView()` to specify the view file, such as `myView`, which typically resolves to `./views/wires/myView.cfm`. This provides direct control over which template is rendered for the component.
```javascript
component extends="cbwire.models.Component" {
function renderIt(){
// Renders ./views/wires/myView.cfm
return this.renderView( "myView" );
}
}
```
--------------------------------
### CBWIRE Component mount() Method
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/essentials/lifecycle-events.md
The `mount` method in a CBWIRE component executes only once when the component is initially wired. It can access incoming values from the event object.
```javascript
component extends="cbwire.models.Component" {
function mount( event, rc, prc, parameters ){
variables.data.incomingValue = event.getValue( "someField" );
}
}
```
--------------------------------
### Create cbwire Counter Component View (CFM)
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/README.md
ColdFusion Markup file (counter.cfm) for the cbwire Counter component. It displays the reactive counter value and provides a button to trigger the increment action using the wire:click attribute, linking the view to the component's server-side logic.
```HTML/CFML
Count: #args.counter#
```
--------------------------------
### Defining a cbwire component action for prefetching
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/templates/prefetching.md
This ColdFusion Component (CFC) defines the `togglePreview` action, which is designed to be prefetched. It updates a data property to control visibility. The `renderIt` function renders the associated view. This component illustrates the backend logic for a prefetch operation, emphasizing that such actions should not have side effects.
```CFML
// File: ./wires/Movie.cfc
component extends="cbwire.models.Component"{
variables.data = {
"showPreview": false
};
function togglePreview(){
variables.data.contentIsVisible = true;
}
function renderIt(){
return this.renderView( "wires/movie" );
}
}
```
--------------------------------
### ColdFusion Component for Checkout Action
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/ui-goodies/loading-states.md
Defines a ColdFusion Component (CFC) named `Cart` with a `checkout` function that simulates a long-running process using `sleep(5000)`. This component is designed to be a cbwire 'wire object' and includes a `$renderIt` function to render its view.
```CFML
component extends="cbwire.models.Component"{
function checkout(){
sleep( 5000 ); // optimize this code yo!
}
function $renderIt(){
return this.$renderView( "wires/cart" );
}
}
```
--------------------------------
### Define cbwire Component Action for Checkout
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/templates/loading-states.md
This ColdFusion Component (CFC) defines a 'checkout' action that simulates a long-running process using 'sleep(5000)'. It also includes a '$renderIt' function to render the associated view. This component is used to demonstrate loading states during asynchronous operations.
```javascript
component extends="cbwire.models.Component"{
function checkout(){
sleep( 5000 ); // optimize this code yo!
}
function $renderIt(){
return this.$renderView( "wires/cart" );
}
}
```
--------------------------------
### HTML Markup for Basic Loading State Display
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/ui-goodies/loading-states.md
Demonstrates how to use the `wire:loading` attribute on an HTML `div` element to display a 'Processing Payment...' message while the `checkout` action is running. The message automatically disappears once the action completes.
```HTML
Processing Payment...
```
--------------------------------
### Set View with variables.view Property in cbwire Component
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/essentials/rendering-components.md
As an alternative to the `renderIt()` method, the `variables.view` property can be used to set a component's template. By assigning the view name, like `"myView"`, to this property, cbwire will render the corresponding view file. This offers a concise way to specify the component's visual representation.
```javascript
component extends="cbwire.models.Component" {
variables.view = "myView";
}
```
--------------------------------
### Register Client-Side Event Listener in JavaScript
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/essentials/events.md
Demonstrates how to register a client-side event listener using `cbwire.on()` in JavaScript, allowing the browser to react to events emitted from the server or other client-side scripts.
```javascript
// File: ./views/wires/myView.cfm
```
--------------------------------
### Accessing the root LogBox logger in CBWIRE
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/component-features/logging.md
Shows how to retrieve the main LogBox parent object using the `getLogBox()` method and then obtain the root logger. This allows for more advanced or global logging operations beyond the component's injected logger.
```javascript
component extends="cbwire.models.Component"{
function mount(){
var logbox = getLogBox();
var logger = logbox.getRootLogger();
log.info( "Logging with the root logger!" );
}
}
```
--------------------------------
### Define cbwire Counter Component (CFC)
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/README.md
ColdFusion Component (CFC) defining a cbwire component. It includes reactive data properties and an action method to increment a counter, demonstrating server-side logic for a reactive UI.
```CFML
// File: ./wires/Counter.cfc
component extends="cbwire.models.Component" {
// Reactive Data Properties
variables.data = {
"counter": "0"
};
// Action to increment counter
function increment(){
variables.data.counter += 1;
}
}
```
--------------------------------
### Configure cbwire module settings in ColdBox CFC
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/essentials/configuration.md
This ColdFusion code snippet demonstrates how to override default cbwire module settings within the `configure` function of a `config/ColdBox.cfc` file. It shows how to set `throwOnMissingSetterMethod` to `false` and `componentLocation` to `wires`.
```ColdFusion
// File: ./config/ColdBox.cfc
component{
function configure() {
moduleSettings = {
cbwire = {
"throwOnMissingSetterMethod" : false,
"componentLocation": "wires"
}
};
}
}
```
--------------------------------
### Applying .prefetch modifier in a cbwire view
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/templates/prefetching.md
This CFML snippet demonstrates how to apply the `.prefetch` modifier to a button's `wire:click` event in a ColdFusion Markup Language (CFML) view. When the user mouses over this button, the `togglePreview` action will be invoked on the associated cbwire component, but its results will only be displayed upon a click.
```CFML
// File: ./views/wires/movie.cfm
```
--------------------------------
### HTML Markup for Customizing Loading State Display Property
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/ui-goodies/loading-states.md
Shows various modifiers (`.flex`, `.grid`, `.inline`, `.table`) that can be appended to `wire:loading` to override the default `display: inline-block;` CSS property, allowing for flexible layout control of loading indicators.
```HTML
...
...
...
...
```
--------------------------------
### Redirecting Users in cbwire Components
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/component-features/redirecting.md
This snippet demonstrates how to redirect a user from a cbwire component using the `this.relocate()` method. It includes a ColdFusion Component (CFC) defining the `findADev` method which triggers the redirection, and a corresponding ColdFusion Markup (CFM) view with a button that invokes this method.
```cfml
// File: ./wires/FindADeveloper.cfc
component extends="cbwire.models.Component"{
function findADev(){
return this.relocate( URL="https://www.ortussolutions.com" );
}
function renderIt(){
return this.renderView( "wires/findADev" );
}
}
```
```cfm
// File: ./views/wires/findADev.cfm
```
--------------------------------
### Define Server-Side Event Listeners in cbwire Component
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/essentials/events.md
Explains how to register server-side event listeners in a cbwire component by mapping event names to component methods within the `variables.listeners` object.
```javascript
component extends="cbwire.models.Component"{
variables.listeners = {
"counterIncremented": "tweetAboutIt"
};
function tweetAboutIt(){
// Blow up Twitter
}
...
}
```
--------------------------------
### Emit Event from cbwire View
Source: https://github.com/ortus-docs/cbwire-docs/blob/master/essentials/events.md
Demonstrates emitting a custom event directly from an HTML element within a cbwire view using the `wire:click` directive.
```markup