wheels generate property

Add properties to existing model files with database migrations and view updates.

Synopsis

wheels generate property name=<modelName> columnName=<propertyName> [options]

#Can also be used as:
wheels g property name=<modelName> columnName=<propertyName> [options]

Parameter Syntax

CommandBox supports multiple parameter formats:

• Named parameters: name=value (e.g., name=User, columnName=email)

• Flag parameters: --flag equals flag=true (e.g., --allowNull equals allowNull=true)

• Flag with value: --flag=value equals flag=value (e.g., --dataType=boolean)

Note: Flag syntax (--flag) avoids positional/named parameter conflicts and is recommended for boolean options.

Description

The wheels generate property command generates a database migration to add a property to an existing model and scaffolds it into _form.cfm and show.cfm views.

Arguments

Argument	Description	Default
name	Model name (table name)	Required
columnName	Name of column to add	Required

Options

Option	Description	Valid Values	Default
dataType	Type of column	biginteger, binary, boolean, date, datetime, decimal, float, integer, string, text, time, timestamp, uuid	string
default	Default value for column	Any valid default value	""
allowNull	Whether to allow null values	true, false	true
limit	Character or integer size limit	Numeric value	0
precision	Precision for decimal columns	Numeric value	0
scale	Scale for decimal columns	Numeric value	0

Data Type Options

Type	Database Type	Description
biginteger	BIGINT	Large integer values
binary	BLOB	Binary data
boolean	BOOLEAN	Boolean (true/false) values
date	DATE	Date only
datetime	DATETIME	Date and time
decimal	DECIMAL	Decimal numbers with precision/scale
float	FLOAT	Floating point numbers
integer	INTEGER	Integer values
string	VARCHAR	Variable character strings
text	TEXT	Long text content
time	TIME	Time only
timestamp	TIMESTAMP	Timestamp values
uuid	VARCHAR(35)	UUID/GUID strings

Examples

Basic string property

wheels generate property name=User columnName=firstName

Creates a string property called firstName on the User model.

Boolean property with default

wheels generate property name=User columnName=isActive --dataType=boolean --default=0

Creates a boolean property with default value of 0 (false).

Datetime property

wheels generate property name=User columnName=lastLoggedIn --dataType=datetime

Creates a datetime property on the User model.

Decimal property with precision

wheels generate property name=Product columnName=price --dataType=decimal --precision=10 --scale=2

Creates a decimal property with 10 total digits and 2 decimal places.

String with character limit

wheels generate property name=User columnName=username --dataType=string --limit=50 --allowNull=false

Creates a required string property with maximum 50 characters.

What the Command Does

The wheels generate property command performs these actions:

1. Creates Database Migration: Generates a migration file to add the column to the database

2. Updates Form View: Adds the property to _form.cfm if it exists

3. Updates Index View: Adds the property to index.cfm table if it exists

4. Updates Show View: Adds the property to show.cfm if it exists

5. Offers Migration: Prompts to run the migration immediately

Generated Files

Database Migration

File: app/migrator/migrations/[timestamp]_add_[columnName]_to_[tableName].cfc

component extends="wheels.migrator.Migration" {

    function up() {
        transaction {
            addColumn(
                table = "users",
                columnName = "firstName",
                columnType = "string",
                limit = 255,
                allowNull = true
            );
        }
    }

    function down() {
        transaction {
            removeColumn(table = "users", columnName = "firstName");
        }
    }
}

View Updates

When views exist, the command adds the new property to them:

Form View (_form.cfm): Adds appropriate input field

<!-- Added to _form.cfm -->
#textField(objectName="user", property="firstName")#

Index View (index.cfm): Adds column to table

<!-- Added to table header -->
<th>First Name</th>

<!-- Added to table body -->
<td>#user.firstName#</td>

Show View (show.cfm): Adds property display

<!-- Added to show.cfm -->
<p><strong>First Name:</strong> #user.firstName#</p>

Special Behaviors

Boolean Default Values

When adding boolean properties without a default value, the command automatically sets default=0:

wheels generate property name=User columnName=isActive --dataType=boolean
# Automatically gets default=0

Model File Check

The command checks if the corresponding model file exists and asks for confirmation if it doesn't:

Hold On! We couldn't find a corresponding Model at /app/models/User.cfc:
are you sure you wish to add the property 'email' to users? [y/n]

Lowercase Column Names

Column names are automatically converted to lowercase in migrations (following Wheels conventions):

# Input: columnName=firstName
# Migration: columnName=firstname

Command Workflow

1. Validation: Checks if model file exists (optional)

2. Migration: Creates database migration using wheels dbmigrate create column

3. Form Update: Adds form field to _form.cfm (if exists)

4. Index Update: Adds column to index.cfm table (if exists)

5. Show Update: Adds property display to show.cfm (if exists)

6. Migration Prompt: Asks if you want to run migration immediately

Troubleshooting

Property Not Added to Views

• Check that view files exist (_form.cfm, index.cfm, show.cfm)

• View files must be in /app/views/[modelPlural]/ directory

Migration Fails

• Ensure model name matches existing table

• Check that column doesn't already exist

• Verify database permissions

Boolean Values

• Boolean properties automatically get default=0 if no default specified

• Use --default=1 for true default values

Best Practices

1. Run migrations immediately when prompted to keep database in sync

2. Use semantic names for properties (firstName, not fname)

3. Set appropriate defaults for boolean and numeric fields

4. Consider null constraints based on business logic

5. Add one property at a time for better change tracking

See Also

• wheels generate model - Generate models

• wheels dbmigrate create column - Create columns

• wheels generate test - Generate tests