`. The data property becomes a `FileUpload` object held in temporary storage. It stays there until an action commits it, which is what makes an upload behave like any other staged edit. ```boxlang // wires/PhotoUpload.bx, inside the class function save() { if ( isSimpleValue( data.avatar ) ) { return; } if ( data.avatar.isImage() ) { var storedPath = data.avatar.store( expandPath( "./uploads" ) ); } data.avatar = ""; } ``` | `FileUpload` method | Purpose | |---------------------|---------| | `store( path )` | Move the file to permanent storage. Returns the absolute stored path | | `isImage()` | Type test before processing | | `getSize()` / `getMIMEType()` / `getMeta()` | Inspect without reading the bytes | | `get()` | The binary content | | `getBase64()` / `getBase64Src()` | Encoded content, and a `data:` URL for an `` tag | | `getPreviewURL()` | Preview an image before committing | | `getTemporaryStoragePath()` / `getMetaPath()` | The staged locations | | `destroy()` | Discard the staged file | `store()` takes **one** argument. Pass a directory and the original filename is kept. Pass a full file path and the file is renamed. Missing directories are created either way. ### Do not call destroy() after store() The CBWIRE documentation shows `store()` followed by `destroy()`. **Do not copy that pattern.** `store()` repoints the object's internal path at the file it just wrote. `destroy()` then deletes whatever that path points at, so the pair deletes the file you just saved. ```boxlang var storedPath = data.avatar.store( expandPath( "./uploads" ) ); data.avatar.destroy(); // WRONG, deletes the file store() just wrote data.avatar = ""; // RIGHT, store() already moved it ``` `destroy()` is still the right call when you are **discarding** an upload the user never committed. ### Upload errors `onUploadError( property, errors, multiple )` fires on any non-2xx response. In 4.x an upload error threw instead. `errors` is null unless the status was 422, in which case it holds the response body. ## JavaScript Integration ### cbwire:script and cbwire:assets These are the supported way to attach JavaScript to a component. Both sit **outside** the root element, as siblings. CBWIRE lifts them out of the template before rendering, so they never become a second root. ```html

``` Why use these over a hand-rolled script tag: `$wire` is already in scope, so no lookup, no id matching, no init event. Assets load once per page while scripts run once per component instance. And Livewire guarantees assets are on the page before scripts evaluate. A plain ` ``` **Never use `DOMContentLoaded`.** It fires before the component registers, so `Livewire.find()` returns `undefined` there. The id check is required, because `component.init` fires for every component on the page. `#_id#` is the current component's id, pre-loaded into the template scope. Keep the global, so later code calls `window._myWidget.someAction()` instead of finding the component again. CBWIRE re-fires the Livewire events under its own names, so `cbwire:init`, `cbwire:initialized`, and `cbwire:navigated` also work, and `window.cbwire` aliases `window.Livewire`. Other hooks: `element.init`, the `morph.*` family, `commit`, `commit.prepare`, and `request`. The `request` hook is how you replace the default "page expired" dialog on a 419. ### wire:ignore versus wire:ignore.self - **`wire:ignore`** protects an entire subtree. Use it for anything holding browser state the morph would destroy: a date picker, a rich text editor, a drop zone with pending files. - **`wire:ignore.self`** protects only the element's own attributes and still updates its children. Use it when a client library owns a class on the container, such as an active or collapsed state. The inputs inside still belong to the component. ## Advanced API ### js( expression ) Queues JavaScript to run in the browser after the response lands, as in `js( "myToast.show('Saved')" )`. It is the shortest path from an action to a client side side-effect, with no template plumbing. **It must be a single expression.** Alpine splices the queued string into an assignment, so anything that cannot legally follow an `=` is a syntax error. That rules out a string starting with `for`, `while`, `var`, `function`, `return`, `throw`, or `try`. A leading `if (...)`, `let`, or `const` is special-cased and does work. Semicolon-separated statements parse, but only the first value is captured. Build a helper function and call that instead. `js()` is documented only in the 4.0 release notes, not the CBWIRE 5 docs. If a call produces a browser console `TypeError` instead of running, the server and the bundled Livewire build disagree about the payload shape. Check your installed version before debugging the expression. ### reset( property ) and resetExcept( property ) Restore data properties to the values they were declared with. Both accept a name, a list, an array, or nothing at all to mean every property: `reset()`, `reset( "search,page" )`, `resetExcept( "perPage" )`. ### Lazy loading and placeholder() Defer a component until it scrolls into view with `#wire( name = "SalesReport", lazy = true )#`. Useful for anything expensive that is not needed for first contentful paint. A component can opt into this itself with `lazyLoad = true`, and into render isolation with `isolate = true`. ```boxlang function placeholder() { return "

Loading report...

"; } ``` **The placeholder must use the same root element type as the component.** A placeholder that returns a `

` in front of a component whose root is a `` renders wrong. `placeholder()` can also return a ColdBox view through `view( "spinner" )`. ### Nested components Call `wire()` from a parent template. Give every child in a loop a `wire:key` so the morph matches children by identity rather than position: `#wire( name = "RowEditor", params = { "id" : row.id }, key = "row-#row.id#" )#`. ### stream( target, content, replace ) Push partial output to the page during a long-running action, paired with `wire:stream` in the template. All three arguments are required. `replace` has no default, and calling `stream()` with two arguments errors. ### The secured annotation Component-level and method-level authorization, evaluated through cbSecurity. The annotation is only active when cbSecurity is installed. Without it, use `onSecure()`. This is the one place where the two language modes differ by more than a mechanical substitution, so both are shown. ```boxlang // wires/AdminPanel.bx @secured class extends="cbwire.models.Component" { @secured( "admin" ) function deleteUser( userId ) {} } ``` ```cfml // wires/AdminPanel.cfc component extends="cbwire.models.Component" secured { function deleteUser( userId ) secured="admin" {} } ``` A bare `secured` means "must be logged in". A string is passed to cbSecurity as a permission check, and a comma list passes when the user holds any one of them. `@secured(false)` allows everyone. The `cbsecurity` skill covers what a permission string resolves to. ### redirect( url, useNavigate ) Navigate away from an action. Pass `true` for the second argument to use SPA navigation instead of a full page load. ### Interception points Six ColdBox interception points, so cross-cutting concerns need not live in the components: `onCBWIREMount`, `preCBWIRERender`, `onCBWIRERender`, `preCBWIREUpdate`, `onCBWIREUpdate`, and `onCBWIRESecureFail`. Each carries the wire instance, its name, and its data. ## Behavior and Gotchas Each of these is hard to diagnose from the symptom alone. ### wire:dirty compares snapshots, not history It measures the canonical snapshot against the reactive one. **Every commit makes the current state canonical.** Dirty silently resets after any server round trip, including one the user never thought of as a save. Do not use it as a running "has this form been touched" flag across requests. ### wire:target on a wire:dirty element must name a property `wire:loading` and `wire:dirty` both read `wire:target`, but differently. `wire:dirty` resolves the target against the component's data, so it must be a **data property path**. Point it at an action name and it silently never fires, with no error. ```html

Unsaved

``` A `wire:model` on the same element is added as a target automatically, and `wire:target` accepts a comma-separated list of paths. ### Livewire wipes any class a wire:dirty directive names A reset runs after the morph and returns every `wire:dirty` element to its clean state. So a class the server renders **must not** be a class the directive also toggles, or it vanishes a moment after it appears. Give each signal its own class and combine them in CSS. ```html

Unsaved

``` ### A file upload is itself a commit The upload round trip makes the new value canonical, so `wire:dirty` reports **clean** while the file is still uncommitted to storage. Any "you have a staged file" indicator has to come from the server, which can see the `FileUpload` object. ### The template scope is pre-loaded CBWIRE injects a lot into the template scope before including it: - every data key as a bare variable, plus a `get()` for each - the `data` and `args` structs - every public method and every computed function - `event`, the ColdBox request context - `view()`, `_id`, and `validation` when cbvalidation is installed An unprefixed local variable in a wire template can silently overwrite one of them. Prefix locals, or derive the value from a component method instead. Params passed through `wire()` are applied **last** and overwrite same-named data properties. The one exception is `event`, assigned after the params, which therefore wins over a param of that name. ### Components are transients A fresh instance per request, so memoizing in the `variables` scope is safe within a render and cannot leak across requests. This matters when a template asks for the same derived value many times. Key the memo on whatever it derives from if an action can change that value mid-request. ```boxlang function getSettings() { if ( !variables.keyExists( "_settingsMemo" ) ) { variables._settingsMemo = settingsService.load( data.recordId ); } return variables._settingsMemo; } ``` ### The single root element is no longer enforced CBWIRE used to throw a clear error for a template with two root elements. That check now returns immediately without validating. The rule still holds, because CBWIRE injects the wire attributes into the first tag it finds. Breaking it now gives a confusing morph failure instead of a helpful message. ### wire:model on a file input already has a native listener Livewire binds to the input's own `change` event, so a browse pick already reaches Livewire with no help. Code that sets `input.files` and dispatches a synthetic `change` fires twice on a browse and uploads the same file twice. A drag and drop never touches the input, so that path does need the synthetic event. Fire only when the file set actually changed, and guard against re-entry, because your own listener will hear the event you dispatch. ```javascript const changed = !sameFiles( input.files, dt.files ); input.files = dt.files; if ( changed ) input.dispatchEvent( new Event( "change", { bubbles: true } ) ); ``` ### Alpine x-if destroys nested components A wire component inside an `x-if` template is torn out of the DOM when the condition flips, and Livewire then reports "unable to find component". Use `x-show`, or `wire:show`, which keeps the element in the DOM. ## Testing Extend `cbwire.models.BaseWireTest` and call `wire()` for a chainable test instance. The `testbox/bdd` skill covers the `describe` and `it` structure itself. ```boxlang // tests/specs/TaskListTest.bx class extends="cbwire.models.BaseWireTest" { function run() { describe( "TaskList", function() { beforeEach( function( currentSpec ) { setup(); } ); it( "clears the tasks", function() { wire( "TaskList" ) .data( "tasks", [ "task1" ] ) .see( "task1" ) .call( "clearTasks" ) .dontSee( "task1" ); } ); } ); } } ``` | Method | Purpose | |--------|---------| | `data( key, value )` | Set a data property, or pass a struct of them | | `computed( key, closure )` | Stub a computed property | | `toggle( key )` | Flip a boolean data property | | `call( method, params )` | Run an action | | `emit( event, params )` | Fire an event and run the component's listeners | | `see( text )` / `dontSee( text )` | Assert on the rendered HTML | | `seeData( key, value )` / `dontSeeData( key, value )` | Assert on a data property | `setup()` and `execute()` come from ColdBox's `BaseTestCase`, which `BaseWireTest` extends. Call `setup()` in `beforeEach()` so each example starts from a clean request context. ### The render cache makes repeated renders return stale HTML CBWIRE caches rendered content on the component instance and never clears it. The framework relies on this, because a parent renders each non-lazy child twice. For tests, a second render of the same instance returns the **first** render's HTML, whatever changed in between. That produces both false passes and false regressions. Keep one render per test block. To assert on state after an action, use `seeData()` rather than a second `see()`. ### Test rendering is HTML only No JavaScript runs in a test render. Directives, morph behavior, `wire:dirty`, uploads, and any client integration are all **unverifiable** by the suite. A green suite says the markup rendered, not that the component behaves. Say so when reporting results, and verify client-side work in a browser. ## Best Practices - **Fetch large reference lists in the template** through `getInstance()`, never in `data`. Everything in `data` travels in every payload, so keep it flat and small - **Encode output with `encodeForHTML()`.** CBWIRE does not sanitize for you - **Use `wire:loading`** for feedback on slow actions, `dispatchTo()` for targeted messaging, and keep heavy work in the service layer where it can be cached - **For tabs, accordions, and wizards, consider rendering every pane** and toggling visibility on the client. Server-side switching sends a whole subtree back and forces the morph to rebuild it, the case morphdom handles worst. The tradeoff is a larger first render, so weigh it - **Reach for plain JavaScript** when a component would manage hundreds of nodes. CBWIRE is the wrong tool for a large tree ## Documentation - cbwire: https://github.com/coldbox-modules/cbwire - cbwire docs: https://cbwire.ortusbooks.com