Data Properties

Data Properties hold the state of your component and are defined with a data structure. Each data property is assigned a default value and is automatically synchronized between server and client.

Data properties are reactive - when an action modifies a property, CBWIRE automatically re-renders only the affected parts of your template. They can hold strings, numbers, booleans, dates, arrays, and structures, and are directly accessible in templates without special syntax.

BoxLang

//./wires/SomeComponent.bx
class extends="cbwire.models.Component" {
    data = {
        "propertyName": "defaultValue"
    };
}

CFML

JavaScript parses your data properties. Your data properties can only store JavaScript-friendly values: strings, numerics, arrays, structs, or booleans.

Single or double quotes must surround property names.

JavaScript is a case-sensitive language, and CFML isn't. To preserve the casing of your property names, you must surround them with quotes.

Don't do this.

data = {
    propertyName: "defaultValue"
};

Data properties are visible to JavaScript. You SHOULD NOT store sensitive data in them. Use locked properties for additional protection against client-side modifications.

Accessing From Actions

Using the data structure, you can access data properties from within your component actions.

// Data properties
data = {
    "time": now()
}; 
   
// Action
function updateTime(){
    data.time = now();
}

Accessing From Templates

You can access data properties within your templates using #propertyName#.

Boxlang

<bx:output>
    <div>
        <h1>Current time</h1>
        <div>#time#</div>
        <button wire:click="updateTime">Update</button>
    </div>
</bx:output>

CFML

Resetting Properties

You can reset all data properties to their original default value inside your actions using reset().

data = {
    "time": now()
};

function resetTime(){
    reset();
}

You can reset individual, some, or all data properties.

function resetForm() {
    reset( "message" ); // resets 'message' data property
    reset( [ "message", "anotherprop" ] ); // reset multiple properties at once
    reset(); // resets all properties
}

You can also reset all properties EXCEPT the properties you pass.

function resetForm() {
    resetExcept( "email" );
    resetExcept( [ "email", "phoneNumber" ] );
}

Locked Properties

Locked properties prevent client-side modifications to sensitive data like user IDs, roles, or permissions. Define a locked variable to protect specific properties from wire:model and other client interactions. CBWIRE throws an exception if locked properties are modified from the client.

Single Property

BoxLang

// wires/UserProfile.bx
class extends="cbwire.models.Component" {
    // Lock single property
    locked = "userId";
    
    data = {
        "userId": 123,
        "name": "John Doe",
        "email": "[email protected]",
        "isActive": true
    };
    
    function updateProfile() {
        // Can modify name, email, isActive
        // Cannot modify userId - it's locked
    }
}

CFML

Multiple Properties

BoxLang

// wires/AdminPanel.bx
class extends="cbwire.models.Component" {
    // Lock multiple properties
    locked = ["userId", "role", "permissions", "accountType"];
    
    data = {
        "userId": 123,
        "name": "Jane Admin",
        "email": "[email protected]",
        "role": "administrator",
        "permissions": ["read", "write", "delete", "admin"],
        "accountType": "premium",
        "lastLogin": now(),
        "theme": "dark"
    };
    
    function updateSettings() {
        // Can modify: name, email, lastLogin, theme
        // Cannot modify: userId, role, permissions, accountType
        data.lastLogin = now();
        data.theme = "light";
    }
}

CFML

Template Usage

Locked properties can be displayed but not modified through form inputs:

BoxLang

<!-- wires/adminPanel.bxm -->
<bx:output>
<div>
    <h1>User Profile</h1>
    
    <!-- Display locked properties (read-only) -->
    <div class="readonly-info">
        <p><strong>User ID:</strong> #userId#</p>
        <p><strong>Role:</strong> #role#</p>
        <p><strong>Account Type:</strong> #accountType#</p>
    </div>
    
    <!-- Form with editable properties -->
    <form wire:submit="updateSettings">
        <!-- These inputs work normally -->
        <input type="text" wire:model="name" placeholder="Name">
        <input type="email" wire:model="email" placeholder="Email">
        
        <select wire:model="theme">
            <option value="light">Light</option>
            <option value="dark">Dark</option>
        </select>
        
        <!-- These would throw an exception if attempted -->
        <!-- <input type="hidden" wire:model="userId"> ❌ -->
        <!-- <input type="text" wire:model="role"> ❌ -->
        
        <button type="submit">Update Profile</button>
    </form>
</div>
</bx:output>

CFML

Common Use Cases

• User Management: Lock userId, role, permissions

• E-commerce: Lock product IDs, prices, inventory counts

• Financial: Lock account numbers, balances, transaction IDs

• Content: Lock author IDs, creation dates, publication status

Locked properties only prevent client-side modifications. Server-side code in your action methods can still modify locked properties when necessary.

Remember that locked properties are still visible in the client-side JavaScript. For truly sensitive data that shouldn't be visible to users, avoid including it in data properties altogether and access it through server-side services instead.