// 1. Allow only `isActive` to be set through mass assignment (e.g. `updateAll()`, `new()`, `update()`).
config() {
	accessibleProperties("isActive");
}

// 2. Allow a comma-delimited list of properties to be set through mass assignment.
//    Any property not in this list is silently ignored when set via mass assignment.
config() {
	accessibleProperties("firstName,lastName,email");
}

// 1. Add a simple string column to an existing table
addColumn(table="members", columnType="string", columnName="status", limit=50);

// 2. Add a boolean column with a default value and no NULLs allowed
addColumn(
    table="members",
    columnType="boolean",
    columnName="isActive",
    default=1,
    allowNull=false
);

// 3. Add a decimal column with precision and scale (e.g. for a price field)
addColumn(
    table="products",
    columnType="decimal",
    columnName="price",
    precision=10,
    scale=2,
    default=0,
    allowNull=false
);

// 1. Add an error to the `email` property.
this.addError(property="email", message="Sorry, you are not allowed to use that email. Try again, please.");

// 2. Add a named error so you can distinguish it from other errors on the same property.
this.addError(property="email", message="That email address is already taken.", name="emailTaken");

// 3. Check for the named error after adding it.
this.addError(property="username", message="Username is reserved.", name="reservedUsername");
if (this.hasErrors(property="username", name="reservedUsername")) {
	writeOutput("A reserved-username error is present.");
}

// 1. Add a general error on the object (not tied to any single property)
user = model("User").findByKey(params.userId);
user.addErrorToBase(message="Your account has been locked. Please contact support.");

// 2. Add a named base error so it can be targeted or cleared later
order = model("Order").findByKey(params.orderId);
order.addErrorToBase(message="This order cannot be placed outside business hours.", name="businessHoursViolation");
if (order.hasErrors(name="businessHoursViolation")) {
    // handle the named error
}

// 3. Use addErrorToBase inside a custom validation method on the model
function validate() {
    if (this.totalAmount > creditLimit()) {
        this.addErrorToBase(message="The total amount exceeds your available credit limit.");
    }
}

// 1. Add a foreign key from orders.customerId to customers.id
addForeignKey(
    table="orders",
    referenceTable="customers",
    column="customerId",
    referenceColumn="id"
);

// 2. Add a foreign key from comments.postId to posts.id
addForeignKey(
    table="comments",
    referenceTable="posts",
    column="postId",
    referenceColumn="id"
);

// 3. Use addForeignKey in a migration's up() and remove it in down()
// In your migration CFC:
//
// public void function up() {
//     addForeignKey(
//         table="order_items",
//         referenceTable="orders",
//         column="orderId",
//         referenceColumn="id"
//     );
// }
//
// public void function down() {
//     dropForeignKey(table="order_items", keyName="FK_order_items_orders");
// }

// 1. Add the `js` format
addFormat(extension="js", mimeType="text/javascript");

// 2. Add the `ppt` and `pptx` formats
addFormat(extension="ppt", mimeType="application/vnd.ms-powerpoint");
addFormat(extension="pptx", mimeType="application/vnd.ms-powerpoint");

// 3. Add a custom `csv` format so controllers can respond with `responds(formats="csv")`
addFormat(extension="csv", mimeType="text/csv");

// 1. Add a basic index on a single column
addIndex(table="users", columnNames="email");

// 2. Add a unique index to enforce uniqueness on a column
addIndex(table="members", columnNames="username", unique=true);

// 3. Add a composite index on multiple columns
addIndex(table="orders", columnNames="customerId,createdAt");

// 4. Add an index with a custom index name
// (defaults to tableName_firstColumnName, e.g. "posts_publishedAt")
addIndex(table="posts", columnNames="publishedAt", indexName="idx_posts_published");

// 1. Insert a simple seed record into a settings table
addRecord(
    table = "settings",
    name = "siteName",
    value = "My Wheels App"
);

// 2. Insert a record with multiple columns (extra keyword arguments become column/value pairs)
addRecord(
    table = "people",
    id = 1,
    title = "Mr",
    firstName = "Bruce",
    lastName = "Wayne",
    email = "bruce@wayneenterprises.com",
    phone = "555-678-9099"
);

// 3. Seed an admin user role during a migration's up() function
component extends="wheels.migrator.Migration" {
    function up() {
        addRecord(
            table = "roles",
            id = 1,
            name = "admin",
            active = true
        );
    }
    function down() {
        removeRecord(table = "roles", where = "id = 1");
    }
}

// 1. Add a foreign key from comments.postId to posts.id using a reference name
// Equivalent to: addForeignKey(table="comments", referenceTable="posts", column="postId", referenceColumn="id")
addReference(table="comments", referenceName="post");

// 2. Add a foreign key from order_items.orderId to orders.id
addReference(table="order_items", referenceName="order");

// 3. Use addReference in a migration's up() and undo it with dropReference() in down()
// In your migration CFC:
//
// public void function up() {
//     addReference(table="comments", referenceName="post");
// }
//
// public void function down() {
//     dropReference(table="comments", referenceName="post");
// }

// 1. Register a single method to run after an object is created
// In models/User.cfc
component extends="Model" {
    function config() {
        afterCreate("sendWelcomeEmail");
    }
    private function sendWelcomeEmail() {
        // send email to this.email
    }
}

// 2. Register multiple methods by passing a comma-delimited list
afterCreate("updateCache,notifyAdmin");

// 3. Register using the named `methods` argument
afterCreate(methods="syncToExternalApi");

// 1. Call a single method after an object is deleted
// In models/Order.cfc
afterDelete("notifyWarehouse");

// 2. Call multiple methods after an object is deleted (comma-separated list)
// In models/User.cfc
afterDelete("removeFromSearchIndex,clearCachedData");

// 3. Register several after-delete callbacks individually for clarity
// In models/Article.cfc
afterDelete("logDeletion");
afterDelete("cleanupAttachments");

// 1. Register a single callback method to run after records are fetched
// In models/User.cfc
config() {
	afterFind("setFetchedAt");
}

// The callback receives each row's columns as arguments; return the struct to modify the record.
function setFetchedAt() {
	arguments.fetchedAt = Now();
	return arguments;
}

// 2. Format a column value after a find (works for both query rows and objects)
// In models/Product.cfc
config() {
	afterFind("formatPrice");
}

function formatPrice() {
	if (StructKeyExists(arguments, "price")) {
		arguments.price = DollarFormat(arguments.price);
	}
	return arguments;
}

// 3. Register multiple callback methods as a comma-delimited list
config() {
	afterFind("setFetchedAt,formatPrice");
}

// 1. Call a single method after any object is initialized (whether new or fetched from the database)
afterInitialization("fixObj");

// 2. Call multiple methods after initialization by passing a comma-delimited list
afterInitialization("setDefaults,fixObj");

// 1. Call a single method after a new object is initialized
// In models/User.cfc
component extends="Model" {
    function config() {
        afterNew("setDefaults");
    }
    private function setDefaults() {
        this.role = "member";
        this.active = true;
    }
}

// 2. Call multiple methods after a new object is initialized (comma-delimited list)
afterNew("setDefaults,generateToken");

// 3. Use the `method` argument alias instead of `methods`
afterNew(method="setDefaults");

// 1. Register a single callback method to run after an object is saved (both create and update)
// In models/User.cfc
component extends="Model" {
    function config() {
        afterSave("sendWelcomeEmail");
    }

    private function sendWelcomeEmail() {
        // called automatically each time a User is saved
    }
}

// 2. Register multiple callback methods using a comma-delimited list
component extends="Model" {
    function config() {
        afterSave("updateSearchIndex,notifyAdmins");
    }
}

// 3. Register multiple callbacks by calling afterSave() more than once
component extends="Model" {
    function config() {
        afterSave("updateSearchIndex");
        afterSave("notifyAdmins");
    }
}

// 1. Register a single method to run after an object is updated
// In models/User.cfc
component extends="Model" {
    function config() {
        afterUpdate("clearCache");
    }
    private function clearCache() {
        // invalidate cached data for this user
    }
}

// 2. Register multiple methods by passing a comma-delimited list
afterUpdate("clearCache,notifyAuditLog");

// 3. Register using the named `methods` argument
afterUpdate(methods="syncToSearchIndex");

// 1. Call a single method after an object is validated
afterValidation("fixObj");

// 2. Call multiple methods after an object is validated (comma-delimited list)
afterValidation("sanitizeFields,logValidationResult");

// 3. Use the singular `method` alias for clarity
afterValidation(method="trimWhitespace");

// 1. Call a single method after a new object is validated on create
component extends="Model" {
	function config() {
		afterValidationOnCreate("assignDefaults");
	}

	private function assignDefaults() {
		if (!Len(this.role)) {
			this.role = "member";
		}
	}
}

// 2. Call multiple methods after validation on create (comma-delimited list)
component extends="Model" {
	function config() {
		afterValidationOnCreate("sanitizeFields,logNewRecord");
	}
}

// 3. Use the singular `method` alias for clarity
component extends="Model" {
	function config() {
		afterValidationOnCreate(method="trimWhitespace");
	}
}

// 1. Call a single method after an existing object is validated on update
// In models/User.cfc:
component extends="Model" {
    function config() {
        afterValidationOnUpdate("stampUpdatedBy");
    }

    private function stampUpdatedBy() {
        this.updatedBy = request.currentUserId;
    }
}

// 2. Register multiple methods to run after an existing object is validated on update
component extends="Model" {
    function config() {
        afterValidationOnUpdate("normalizeSlug,logValidation");
    }

    private function normalizeSlug() {
        this.slug = LCase(Replace(this.title, " ", "-", "all"));
    }

    private function logValidation() {
        // custom logging logic here
    }
}

// 1. Collect all validation errors from associated objects on a post
post = model("Post").findOne(where="id=1", include="comments");
errors = post.allAssociationErrors();
// errors -> array of error structs from associated comments (and their associations, recursively)
// Each struct contains keys: property, message, name

// 2. Use allErrors() with includeAssociations=true instead (preferred shorthand)
// allErrors() calls allAssociationErrors() internally when includeAssociations is true
post = model("Post").findOne(where="id=1", include="comments");
allErrors = post.allErrors(includeAssociations=true);
// allErrors -> combined array of the post's own errors plus all associated errors

// 3. Check if any associated model has errors before saving
order = model("Order").findOne(where="id=1", include="lineItems");
associationErrors = order.allAssociationErrors();
if (arrayLen(associationErrors)) {
    writeOutput("One or more line items have validation errors.");
}

// 1. Get an object, change some properties, and inspect all changes before saving
member = model("member").findByKey(params.memberId);
member.firstName = params.newFirstName;
member.email = params.newEmail;
changes = member.allChanges();
// changes -> {
//   firstName: { changedFrom: "Jane", changedTo: "Janet" },
//   email:     { changedFrom: "jane@example.com", changedTo: "janet@example.com" }
// }

// 2. Only call allChanges() when there are changes to process
post = model("post").findByKey(params.id);
post.title = params.title;
post.body = params.body;
if (post.hasChanged()) {
    changes = post.allChanges();
    for (prop in changes) {
        writeOutput("'#prop#' changed from '#changes[prop].changedFrom#' to '#changes[prop].changedTo#'");
    }
}

// 3. allChanges() returns an empty struct when nothing has changed
user = model("user").findByKey(params.userId);
changes = user.allChanges();
// changes -> {} (empty struct — no unsaved changes)

// 1. Get all errors on a model object after a failed validation
user = model("User").new(username="", password="");
user.valid();
errors = user.allErrors();
// errors ->
// [
//   { message: "Username must not be blank.", name: "", property: "username" },
//   { message: "Password must not be blank.", name: "", property: "password" }
// ]

// 2. Check for errors and iterate over them
if (user.hasErrors()) {
	for (error in user.allErrors()) {
		writeOutput(error.property & ": " & error.message);
	}
}

// 3. Include errors from associated models (e.g. a user with associated profile)
user = model("User").findOne(where="id=1", include="profile");
user.valid();
allErrors = user.allErrors(includeAssociations=true);
// allErrors contains errors from both user and its associated profile model

// 1. Log a custom message during a migration's up() step
function up() {
	var state = {};
	transaction {
		try {
			t = createTable(name="articles", force=true);
			t.string(columnNames="title", allowNull=false);
			t.text(columnNames="body");
			t.timestamps();
			t.create();
			announce("Created articles table");
		} catch (any e) {
			state.exception = e;
		}

		if (StructKeyExists(state, "exception")) {
			transaction action="rollback";
			throw(errorCode="1", detail=state.exception.detail, message=state.exception.message, type="any");
		} else {
			transaction action="commit";
		}
	}
}

// 2. Announce multiple steps to provide granular feedback
function up() {
	var state = {};
	transaction {
		try {
			addColumn(table="users", columnType="string", columnName="apiKey", limit=64, allowNull=true);
			announce("Added apiKey column to users");

			addIndex(table="users", columnNames="apiKey", unique=true);
			announce("Added unique index on users.apiKey");
		} catch (any e) {
			state.exception = e;
		}

		if (StructKeyExists(state, "exception")) {
			transaction action="rollback";
			throw(errorCode="1", detail=state.exception.detail, message=state.exception.message, type="any");
		} else {
			transaction action="commit";
		}
	}
}

<cfscript>

// 1. Basic API scope using the default path and name prefix "api"
mapper()
    .api()
        // Route name:  apiUsers
        // Example URL: /api/users
        .resources("users")
    .end()
.end();

// 2. Combine api() with version() for versioned API endpoints
mapper()
    .api()
        .version(1)
            // Route name:  apiV1Users
            // Example URL: /api/v1/users
            .resources("users")
        .end()

        .version(2)
            // Route name:  apiV2Products
            // Example URL: /api/v2/products
            .resources("products")
        .end()
    .end()
.end();

// 3. Override the default path and name prefixes
mapper()
    .api(path="public-api", name="publicApi")
        // Route name:  publicApiOrders
        // Example URL: /public-api/orders
        .resources("orders")
    .end()
.end();

// 4. Use api() with a callback to avoid manual .end() calls
mapper()
    .api(callback=function(m) {
        m.version(number=1, callback=function(m) {
            // Route name:  apiV1Users
            // Example URL: /api/v1/users
            m.resources("users");
        });
    })
.end();

</cfscript>

// 1. Get all association definitions for a model and inspect them
info = model("post").associationInfo();
// info is a struct where each key is an association name, e.g.:
// info.comments.type        -> "hasMany"
// info.comments.modelName   -> "Comment"
// info.comments.foreignKey  -> "postId"
// info.comments.dependent   -> "delete"
// info.author.type          -> "belongsTo"
// info.author.modelName     -> "Author"

// 2. Check whether a specific association is defined on the model
info = model("user").associationInfo();
if (structKeyExists(info, "profile")) {
    writeOutput("User has a profile association of type: " & info.profile.type);
}

// 3. Iterate over all associations to build a summary
info = model("article").associationInfo();
for (assocName in info) {
    writeOutput(assocName & " -> " & info[assocName].type & " " & info[assocName].modelName);
}

// 1. Get all association names defined on a model
names = model("User").associationNames();
// names -> "profile,posts,comments"

// 2. Check whether a specific association exists on the model
if (listFindNoCase(model("Post").associationNames(), "comments")) {
    // the Post model has a "comments" association
}

// 3. Iterate over each association name
for (assocName in listToArray(model("Order").associationNames())) {
    writeOutput(assocName);
}

// 1. Embed the CSRF token in a manually-built form hidden field
token = authenticityToken();
writeOutput('<input type="hidden" name="authenticityToken" value="' & token & '">');

// 2. Pass the token as a request header for an AJAX call (e.g. in a JavaScript data island)
writeOutput('<meta name="csrf-token" content="' & authenticityToken() & '">');
// JavaScript can then read this and send it as the X-CSRF-Token header with each POST request.

// 3. Include the token in a JSON API response body so a client can replay it
tokenValue = authenticityToken();
writeOutput(serializeJSON({authenticityToken = tokenValue}));

// 1. Include CSRF token in a plain HTML form that POSTs data
//    (use this when you are not using startFormTag())
<form action="#urlFor(route='posts')#" method="post">
  #authenticityTokenField()#
  <!--- other fields here --->
</form>

// 2. Not needed for GET forms — GET requests are not CSRF-protected
<form action="#urlFor(route='posts')#" method="get">
  <!--- no token required --->
</form>

// 1. Link both URLs and email addresses (default behavior)
result = autoLink("Download CFWheels from http://cfwheels.org/download");
// result -> "Download CFWheels from <a href="http://cfwheels.org/download">http://cfwheels.org/download</a>"

// 2. Link email addresses only
result = autoLink(text="Email us at info@cfwheels.org or visit http://cfwheels.org", link="emailAddresses");
// result -> "Email us at <a href="mailto:info@cfwheels.org">info@cfwheels.org</a> or visit http://cfwheels.org"

// 3. Link URLs only (skip email addresses)
result = autoLink(text="Visit http://cfwheels.org or contact info@cfwheels.org", link="URLs");
// result -> "Visit <a href="http://cfwheels.org">http://cfwheels.org</a> or contact info@cfwheels.org"

// 4. Disable auto-linking of relative URLs
result = autoLink(text="See /docs/guide for details or http://cfwheels.org for more.", relative=false);
// result -> "See /docs/guide for details or <a href="http://cfwheels.org">http://cfwheels.org</a> for more."

// 1. Disable automatic validations for this model (useful when automatic validations are enabled globally but you want to opt out for a specific model).
component extends="Model" {
	function config() {
		automaticValidations(false);
	}
}

// 2. Explicitly enable automatic validations for this model (useful when automatic validations are disabled globally but you want to opt in for a specific model).
component extends="Model" {
	function config() {
		automaticValidations(true);
	}
}

// 1. Get the average salary for all employees.
avgSalary = model("employee").average("salary");

// 2. Get the average salary for employees in a given department.
avgSalary = model("employee").average(property="salary", where="departmentId=#params.key#");

// 3. Make sure a numeric value is always returned if no records are found.
avgSalary = model("employee").average(property="salary", where="salary BETWEEN #params.min# AND #params.max#", ifNull=0);

// 4. Average only distinct salary values (duplicates excluded).
avgSalary = model("employee").average(property="salary", distinct=true);

// 5. Get the average salary grouped by department (returns a query).
avgByDept = model("employee").average(property="salary", group="departmentId");

// 1. Register a single callback method to run before a new object is created
// Defined inside the model's config() function
beforeCreate("setDefaults");

// 2. Register multiple callback methods to run in sequence before creation
beforeCreate("generateSlug,stampCreatedBy");

// 3. Register callbacks using the named argument
beforeCreate(methods="generateToken,normalizeEmail");

// 1. Register a single method to run before an object is deleted
// In models/Post.cfc
component extends="Model" {
    function config() {
        beforeDelete("cleanUpAttachments");
    }

    private function cleanUpAttachments() {
        // Remove associated files from disk before the record is deleted
        fileDelete(expandPath("/uploads/#this.id#"));
    }
}

// 2. Register multiple methods to run before deletion (comma-delimited list)
// In models/User.cfc
component extends="Model" {
    function config() {
        beforeDelete("revokeTokens,archiveActivity");
    }

    private function revokeTokens() {
        model("Token").deleteAll(where="userId=#this.id#");
    }

    private function archiveActivity() {
        model("ActivityLog").updateAll(
            properties="archivedAt=NOW()",
            where="userId=#this.id#"
        );
    }
}

// 3. Halt deletion by returning false from the callback
// In models/Order.cfc
component extends="Model" {
    function config() {
        beforeDelete("preventIfShipped");
    }

    private function preventIfShipped() {
        // Returning false cancels the delete operation
        if (this.status eq "shipped") {
            return false;
        }
    }
}

// 1. Call a single method before every save (create or update)
// In models/User.cfc
component extends="Model" {
    function config() {
        beforeSave("normalizeEmail");
    }

    private function normalizeEmail() {
        this.email = LCase(Trim(this.email));
    }
}

// 2. Register multiple callback methods as a comma-delimited list
component extends="Model" {
    function config() {
        beforeSave("stripWhitespace,generateSlug");
    }
}

// 3. Use the `method` argument alias to register a single callback
component extends="Model" {
    function config() {
        beforeSave(method="sanitizeContent");
    }
}

// 1. Call a single method before every update
// In models/User.cfc
component extends="Model" {
    function config() {
        beforeUpdate("stampUpdatedBy");
    }

    private function stampUpdatedBy() {
        this.updatedBy = session.userId;
    }
}

// 2. Register multiple callback methods as a comma-delimited list
component extends="Model" {
    function config() {
        beforeUpdate("validateOwnership,recalculateTotals");
    }
}

// 3. Use the `method` argument alias to register a single callback
component extends="Model" {
    function config() {
        beforeUpdate(method="fixObj");
    }
}

// 1. Register a single method to run before any validation
// In models/User.cfc
component extends="Model" {
    function config() {
        beforeValidation("normalizeEmail");
        validatesPresenceOf("email");
    }

    private function normalizeEmail() {
        this.email = LCase(Trim(this.email));
    }
}

// 2. Register multiple methods to run before validation using a comma-delimited list
// In models/Article.cfc
component extends="Model" {
    function config() {
        beforeValidation("stripTags,setSlug");
        validatesPresenceOf(properties="title,slug");
    }

    private function stripTags() {
        this.title = ReReplace(this.title, "<[^>]*>", "", "all");
    }

    private function setSlug() {
        if (!Len(this.slug)) {
            this.slug = LCase(ReReplace(Trim(this.title), "\s+", "-", "all"));
        }
    }
}

// 3. Register callbacks across multiple calls (they are stacked in order)
// In models/Product.cfc
component extends="Model" {
    function config() {
        beforeValidation("trimFields");
        beforeValidation("setDefaults");
    }

    private function trimFields() {
        this.name = Trim(this.name);
    }

    private function setDefaults() {
        if (!Len(this.status)) {
            this.status = "draft";
        }
    }
}

// 1. Register a single method to run before a new object is validated
// In models/User.cfc config()
beforeValidationOnCreate("sanitizeEmail");

// 2. Register multiple methods to run before a new object is validated
// In models/Order.cfc config()
beforeValidationOnCreate("setDefaultStatus,generateTrackingNumber");

// 3. Use the `method` argument alias instead of `methods`
// In models/Post.cfc config()
beforeValidationOnCreate(method="normalizeSlug");

// 1. Register a single method to run before an existing object is validated on update
// Called inside the model's config() function
beforeValidationOnUpdate("sanitizeFields");

// 2. Register multiple methods as a comma-delimited list
beforeValidationOnUpdate("sanitizeFields,enforceBusinessRules");

// 3. Use the `method` argument alias for a single callback
beforeValidationOnUpdate(method="normalizeEmail");

// 1. Specify that instances of this model belong to an author.
// (The table for this model should have a foreign key column, typically named `authorId`.)
belongsTo("author");

// 2. Override naming conventions by specifying `modelName` and `foreignKey` explicitly.
belongsTo(name="bookWriter", modelName="author", foreignKey="authorId");

// 3. Use a LEFT OUTER JOIN instead of the default INNER JOIN when including this association.
belongsTo(name="category", joinType="outer");

// 4. Declare a polymorphic belongsTo association (e.g. a Comment that can belong to a Post or a Photo).
// Wheels will look for `commentableId` and `commentableType` columns on the comments table.
belongsTo(name="commentable", polymorphic=true);

// 1. Add a single bigInteger column to a new table
t = createTable(name='events');
	t.bigInteger(columnNames='externalId');
	t.string(columnNames='title', limit=255, allowNull=false);
	t.timestamps();
t.create();

// 2. Add multiple bigInteger columns at once
t = createTable(name='analytics');
	t.bigInteger(columnNames='pageViews,uniqueVisitors', default=0, allowNull=false);
	t.string(columnNames='path', limit=500, allowNull=false);
	t.timestamps();
t.create();

// 3. Add a bigInteger column with a limit and default when altering an existing table
t = changeTable(name='orders');
	t.bigInteger(columnNames='totalCents', default=0, allowNull=false);
t.change();

// 1. Add a single binary column to a new table
t = createTable(name='attachments');
	t.string(columnNames='filename', limit=255, allowNull=false);
	t.binary(columnNames='fileData');
	t.timestamps();
t.create();

// 2. Add multiple binary columns at once
t = createTable(name='media');
	t.string(columnNames='title', limit=255, allowNull=false);
	t.binary(columnNames='thumbnail,fullImage', allowNull=false);
	t.timestamps();
t.create();

// 3. Add a binary column with a default when altering an existing table
t = changeTable(name='documents');
	t.binary(columnNames='rawContent', allowNull=true);
t.change();

// 1. Add a single boolean column to a new table
t = createTable(name='products');
	t.string(columnNames='name', limit=255, allowNull=false);
	t.boolean(columnNames='isActive', default=1, allowNull=false);
	t.timestamps();
t.create();

// 2. Add multiple boolean columns at once
t = createTable(name='users');
	t.string(columnNames='email', limit=255, allowNull=false);
	t.boolean(columnNames='isAdmin,isVerified,isActive', default=0, allowNull=false);
	t.timestamps();
t.create();

// 3. Add a boolean column to an existing table
t = changeTable(name='articles');
	t.boolean(columnNames='isPublished', default=0, allowNull=false);
t.change();

// 1. Basic submit button inside a form
#startFormTag(action="create")#
    #buttonTag(content="Save changes", value="save")#
#endFormTag()#
<!--- Produces: <button type="submit" value="save">Save changes</button> --->

// 2. Reset button to clear form fields
#buttonTag(content="Clear form", type="reset")#
<!--- Produces: <button type="reset" value="save">Clear form</button> --->

// 3. Plain button (no form submission) with a CSS class and id
#buttonTag(content="Open dialog", type="button", value="open", class="btn btn-secondary", id="openDialogBtn")#
<!--- Produces: <button type="button" value="open" class="btn btn-secondary" id="openDialogBtn">Open dialog</button> --->

// 4. Submit button wrapped in a paragraph using prepend and append
#buttonTag(content="Submit", value="submit", prepend="<p>", append="</p>")#
<!--- Produces: <p><button type="submit" value="submit">Submit</button></p> --->

// 5. Image button (renders an img tag inside the button element)
#buttonTag(content="", image="submit-icon.png", value="save")#
<!--- Produces: <button type="submit" value="save"><img src="/images/submit-icon.png" alt="Submit Icon" /></button> --->

// 1. Basic button that submits to a controller/action
#buttonTo(text="Delete Account", controller="account", action="delete")#
<!--- Outputs: <form action="/account/delete" method="post"><button type="submit">Delete Account</button></form> --->

// 2. If you're already in the `account` controller, CFWheels will assume the current controller
#buttonTo(text="Delete Account", action="delete")#
<!--- Outputs: <form action="/account/delete" method="post"><button type="submit">Delete Account</button></form> --->

// 3. Use `method` to send a DELETE request (a hidden `_method` field is added automatically)
#buttonTo(text="Remove Post", controller="blog", action="delete", key=99, method="delete")#
<!--- Outputs: <form action="/blog/delete/99" method="post"><input type="hidden" name="_method" value="delete" /><button type="submit">Remove Post</button></form> --->

// 4. Use a named route configured in `config/routes.cfm`
#buttonTo(text="Archive", route="archivePost", postId=12)#

// 5. Show a "please wait" state by disabling the button on click — pass extra attributes to the button using the `input` prefix
#buttonTo(text="Place Order", action="checkout", inputId="checkout-btn", inputClass="btn btn-primary", inputData-disable-with="Processing...")#

// 6. Use an image instead of text for the button
#buttonTo(image="icons/trash.png", action="destroy", key=params.id, method="delete")#

// 1. Cache the `termsOfUse` action for the default 60 minutes.
caches("termsOfUse");

// 2. Cache two actions for 30 minutes.
caches(actions="browseByUser,browseByTitle", time=30);

// 3. Cache the `termsOfUse` and `codeOfConduct` actions, including their filters.
caches(actions="termsOfUse,codeOfConduct", static=true);

// 4. Cache content separately based on region.
caches(action="home", appendToKey="request.region");

// 1. Inspect all registered callbacks for a model
info = model("Order").callbackInfo();
// info is a struct keyed by callback type, each containing an array of method names:
// {
//   beforeSave:               ["stampUpdatedAt"],
//   afterCreate:              ["sendConfirmationEmail"],
//   afterSave:                ["clearCacheEntries"],
//   beforeValidation:         [],
//   beforeValidationOnCreate: [],
//   afterValidation:          [],
//   afterFind:                [],
//   ...
// }

// 2. Check whether a specific callback type has any registered methods
info = model("User").callbackInfo();
if (arrayLen(info.beforeDelete)) {
    writeOutput("User model has beforeDelete callbacks.");
}

// 3. Loop over all callback types and their methods for debugging
info = model("Post").callbackInfo();
for (callbackType in info) {
    for (methodName in info[callbackType]) {
        writeOutput(callbackType & ": " & methodName);
    }
}

// 1. Capitalize the first character of a sentence
result = capitalize("wheels is a framework");
// result -> "Wheels is a framework"

// 2. Capitalize a lowercase word
result = capitalize("hello");
// result -> "Hello"

// 3. Returns an already-capitalized string unchanged
result = capitalize("CFWheels");
// result -> "CFWheels"

// 1. Alter existing columns on a table (default behavior — modifies columns that already exist)
t = changeTable(name='users');
	t.string(columnNames='email', limit=255, allowNull=false);
	t.boolean(columnNames='active', default=true, allowNull=false);
t.change();

// 2. Add new columns to an existing table using addColumns=true
t = changeTable(name='products');
	t.string(columnNames='sku', limit=100, allowNull=false);
	t.decimal(columnNames='discountPrice', precision=10, scale=2, allowNull=true);
t.change(addColumns=true);

// 3. Add a foreign key reference column to an existing table
t = changeTable(name='orders');
	t.references(columnNames='customer', allowNull=false);
t.change(addColumns=true);

// 1. Change a string column's length limit
changeColumn(table="members", columnName="status", columnType="string", limit=50);

// 2. Change a column type and set a default value
changeColumn(table="orders", columnName="quantity", columnType="integer", default=1);

// 3. Change a decimal column with precision and scale
changeColumn(table="products", columnName="price", columnType="decimal", precision=10, scale=2, allowNull=false);

// 4. Change a text column and explicitly allow NULL values
changeColumn(table="articles", columnName="summary", columnType="text", allowNull=true);

// 1. Get the previous value of a changed property
user = model("User").findByKey(params.userId);
user.email = params.newEmail;

// Returns the original email address before it was changed
oldEmail = user.changedFrom("email");
// oldEmail -> "original@example.com"

// 2. Use the dynamic shorthand method (equivalent to the above)
oldEmail = user.emailChangedFrom();

// 3. Check if a property changed before accessing the previous value
user = model("User").findByKey(params.userId);
user.firstName = params.firstName;

if (user.hasChanged("firstName")) {
	oldName = user.changedFrom("firstName");
	// oldName -> "Jane"
}
// Returns empty string if property has not changed or no previous value exists

// 1. Find a member, change some properties, then inspect which ones have changed
member = model("member").findByKey(params.memberId);
member.firstName = params.newFirstName;
member.email = params.newEmail;
changed = member.changedProperties();
// changed -> "firstName,email"

// 2. Only save when there are actually unsaved changes
user = model("User").findByKey(params.userId);
user.lastName = params.lastName;
if (Len(user.changedProperties())) {
    user.save();
}

// 3. Use changedProperties() alongside changedFrom() to build an audit log entry
post = model("Post").findByKey(params.postId);
post.title = params.title;
post.body = params.body;
changedList = post.changedProperties();
for (prop in ListToArray(changedList)) {
    writeOutput("Property '#prop#' was '#post.changedFrom(prop)#', now '#post[prop]#'.");
}

// 1. Add a new string column to an existing table
t = changeTable(name="employees");
t.string(columnNames="fullName", default="", allowNull=true, limit=255);
t.change();

// 2. Modify multiple columns at once (change type and nullability)
t = changeTable(name="products");
t.integer(columnNames="stock", default=0, allowNull=false);
t.boolean(columnNames="active", default=true, allowNull=false);
t.change();

// 3. Add a new column using addColumns=true so the migration fails gracefully if the column already exists
t = changeTable(name="orders");
t.datetime(columnNames="shippedAt", allowNull=true);
t.change(addColumns=true);

// 1. Add a single char column to a new table
t = createTable(name='countries');
	t.char(columnNames='code', limit=2, allowNull=false);
	t.string(columnNames='name', limit=100, allowNull=false);
	t.timestamps();
t.create();

// 2. Add multiple char columns at once
t = createTable(name='products');
	t.char(columnNames='sku,barcode', limit=12, allowNull=false);
	t.string(columnNames='title', limit=255, allowNull=false);
	t.timestamps();
t.create();

// 3. Add a char column with a default value when altering an existing table
t = changeTable(name='orders');
	t.char(columnNames='statusCode', limit=1, default='N', allowNull=false);
t.change();

// 1. Basic check box bound to a boolean model property
#checkBox(objectName="photo", property="isPublic", label="Display this photo publicly.")#

// 2. Custom checked and unchecked values (e.g. "yes" / "no" instead of 1 / 0)
#checkBox(objectName="user", property="agreedToTerms", checkedValue="yes", uncheckedValue="no", label="I agree to the terms of service.")#

// 3. Check boxes for a nested association (photos belonging to a user)
<cfloop from="1" to="#ArrayLen(user.photos)#" index="i">
    #checkBox(objectName="user", association="photos", position=i, property="isPublic", label="Make public: #user.photos[i].title#")#
</cfloop>

// 1. Basic usage with a label and a pre-checked state
<cfoutput>
	#checkBoxTag(name="subscribe", value="1", label="Subscribe to our newsletter", checked=true)#
</cfoutput>

// 2. Render an unchecked check box that also submits a value when unchecked
<cfoutput>
	#checkBoxTag(name="agreeToTerms", value="1", uncheckedValue="0", label="I agree to the terms")#
</cfoutput>

// 3. Loop over a query to render one check box per option, checking those already selected
// Controller
toppings = model("Topping").findAll(order="name");
selectedIds = "2,5,9"; // e.g. previously saved topping IDs as a comma-delimited list

// View
<cfoutput query="toppings">
	#checkBoxTag(
		name    = "toppingIds",
		value   = toppings.id,
		label   = toppings.name,
		checked = listFindNoCase(selectedIds, toppings.id) GT 0
	)#
</cfoutput>

// 1. Inspect all metadata for the User model
info = model("User").classInfo();
// info.modelName             -> "User"
// info.tableName             -> "users"
// info.primaryKeys           -> "id"
// info.propertyNames         -> "id,firstName,lastName,email,createdAt,updatedAt"
// info.properties            -> struct of column/type metadata keyed by property name
// info.calculatedProperties  -> struct of SQL-expression properties keyed by property name
// info.associations          -> struct of association definitions (belongsTo, hasMany, etc.)
// info.validations           -> struct keyed by trigger (onSave, onCreate, onUpdate) with arrays of rules
// info.enums                 -> struct of enum definitions keyed by property name
// info.scopes                -> struct of named scope definitions
// info.callbacks             -> struct of callback arrays keyed by callback type (beforeSave, afterCreate, etc.)
// info.softDeletion          -> false (true when the model has a deletedAt column)

// 2. List all association names and their types
info = model("Article").classInfo();

for (assocName in info.associations) {
    assoc = info.associations[assocName];
    writeOutput(assocName & " (" & assoc.type & ")");
}

// 3. Check soft-deletion and enumerate registered callbacks
info = model("Post").classInfo();

if (info.softDeletion) {
    writeOutput("Post uses soft deletion.");
}

for (callbackType in info.callbacks) {
    methods = info.callbacks[callbackType];
    writeOutput(callbackType & ": " & arrayToList(methods));
}

// 4. Inspect calculated properties defined on the model
info = model("Order").classInfo();

for (propName in info.calculatedProperties) {
    calcProp = info.calculatedProperties[propName];
    writeOutput(propName & " => " & calcProp.sql);
}

// 1. Clear all cached action metadata for the current controller.
clearCachableActions();

// 2. Clear the cached metadata for a single action.
clearCachableActions(action="termsOfUse");

// 3. Clear the cached metadata for a list of specific actions.
clearCachableActions(action="browseByUser,browseByTitle");

// 1. Clear change tracking for a single property
// Convert startTime to UTC in an afterFind callback, then tell Wheels to treat
// the converted value as the "original" so it won't be flagged as changed or
// saved unnecessarily.
this.startTime = dateConvert("Local2UTC", this.startTime);
this.clearChangeInformation(property="startTime");

// 2. Clear change tracking for all properties at once
// After manually adjusting values in an afterFind callback, reset Wheels'
// internal state so none of the touched properties appear as dirty.
this.clearChangeInformation();

// 3. Typical afterFind callback usage in a model
// In User.cfc config():
//   afterFind("normalizeTimestamps");
// The callback method:
function normalizeTimestamps() {
    if (structKeyExists(this, "createdAt")) {
        this.createdAt = dateConvert("Local2UTC", this.createdAt);
    }
    if (structKeyExists(this, "updatedAt")) {
        this.updatedAt = dateConvert("Local2UTC", this.updatedAt);
    }
    // Mark both properties as clean so hasChanged() returns false
    // and save() won't push them back to the database.
    this.clearChangeInformation(property="createdAt");
    this.clearChangeInformation(property="updatedAt");
}

// 1. Clear all errors on the object
this.clearErrors();

// 2. Clear all errors set on the `firstName` property
this.clearErrors(property="firstName");

// 3. Clear only errors that were set with a specific error name
this.clearErrors(name="invalidFormat");

// 4. Clear errors on a specific property that were also set with a specific name
this.clearErrors(property="email", name="duplicateEmail");

<cfscript>

// 1. Add a search route acting on the photos collection (GET /photos/search)
mapper()
    .resources(name="photos", nested=true)
        .collection()
            .get("search")
        .end()
    .end()
.end();

// 2. Add multiple collection routes (GET /articles/featured, POST /articles/bulk-delete)
mapper()
    .resources(name="articles", nested=true)
        .collection()
            .get("featured")
            .post("bulkDelete")
        .end()
    .end()
.end();

</cfscript>

// 1. Basic color picker bound to a model object property
#colorField(objectName="product", property="themeColor")#

// 2. Color picker with a custom label and a CSS class
#colorField(objectName="user", property="profileColor", label="Profile Color", class="color-picker")#

// 3. Color pickers for nested properties on a hasMany association (e.g., palette swatches)
<cfloop from="1" to="#ArrayLen(design.swatches)#" index="i">
	#colorField(objectName="design", association="swatches", position="#i#", property="hexValue", label="Swatch ##i#")#
</cfloop>

// 1. Basic color picker with a default value
#colorFieldTag(name="brandColor", value="##FF5733")#

// 2. Color picker with a label and a CSS class
#colorFieldTag(name="themeColor", value="##336699", label="Theme Color", class="color-input")#

// 3. Color picker with label placement and prepend/append wrappers
#colorFieldTag(name="highlightColor", label="Highlight", labelPlacement="before", prepend="<div class=""field"">", append="</div>")#

// 1. Add a generic string column to a new table
t = createTable(name='articles');
	t.column(columnName='title', columnType='string', limit=255, allowNull=false);
	t.column(columnName='body', columnType='text');
	t.timestamps();
t.create();

// 2. Add a column with a default value and precision/scale (for decimals)
t = createTable(name='products');
	t.column(columnName='name', columnType='string', limit=100, allowNull=false);
	t.column(columnName='price', columnType='decimal', precision=10, scale=2, default='0.00', allowNull=false);
	t.column(columnName='stock', columnType='integer', default='0', allowNull=false);
	t.timestamps();
t.create();

// 3. Add a custom column when altering an existing table
t = changeTable(name='users');
	t.column(columnName='bio', columnType='text', allowNull=true);
t.change();

// 1. Get all column metadata for a property
data = model("User").columnDataForProperty("email");
// Returns a struct like:
// { column: "email", validationtype: "string", label: "Email" }

// 2. Inspect metadata before using it
data = model("Product").columnDataForProperty("price");
if (isStruct(data)) {
    writeOutput("Column: " & data.column);
    writeOutput("Validation type: " & data.validationtype);
}

// 3. Handle the false return when the property does not exist on the model
data = model("User").columnDataForProperty("nonExistentProp");
if (!isStruct(data)) {
    writeOutput("Property not found on this model.");
}

// 1. Get the column name mapped to a model property
col = model("User").columnForProperty("firstName");
// col -> "first_name"

// 2. Check the column for a property before building a raw SQL fragment
col = model("Order").columnForProperty("placedAt");
if (col != false) {
    writeOutput("Column in the database: " & col);
}

// 3. Returns false when the property does not exist on the model
col = model("User").columnForProperty("nonExistentProperty");
// col -> false

// 1. Get the list of column names for the User model
cols = model("User").columnNames();
// cols -> "id,firstName,lastName,email,createdAt,updatedAt,deletedAt"

// 2. Check whether a specific column exists in the table
if (listFindNoCase(model("User").columnNames(), "email")) {
    writeOutput("The users table has an email column.");
}

// 3. Iterate over every column name
for (col in listToArray(model("User").columnNames())) {
    writeOutput(col);
}

// 1. Get all column names for the User model
cols = model("User").columns();
// cols -> ["id", "firstName", "lastName", "email", "createdAt", "updatedAt", "deletedAt"]

// 2. Check whether a specific column exists in the table
cols = model("User").columns();
if (arrayFindNoCase(cols, "deletedAt")) {
    writeOutput("Soft-delete column is present");
}

// 3. Iterate over all columns and output their names
cols = model("User").columns();
for (col in cols) {
    writeOutput(col);
}

// 1. Check if two model objects are the same instance
user1 = model("User").findByKey(1);
user2 = model("User").findByKey(1);
user3 = user1;

isSame = user1.compareTo(user2);
// isSame -> false (two separate fetches produce distinct instances)

isSame = user1.compareTo(user3);
// isSame -> true (user3 is the same object reference as user1)

// 2. Guard against processing the same object twice in a loop
users = model("User").findAll(returnAs="objects");
currentUser = model("User").findByKey(session.userId);

for (u in users) {
    if (!u.compareTo(currentUser)) {
        // process all users except the currently logged-in one
        sendNotification(u);
    }
}

<cfscript>

mapper()
    // 1. Constrain a dynamic segment to digits only
    .constraints(id="[0-9]+")
        .resources(name="articles")
    .end()

    // 2. Constrain multiple segments — numeric id and lowercase-only slug
    .constraints(id="[0-9]+", slug="[a-z\-]+")
        .get(name="article", to="articles##show")
        .get(name="articleBySlug", to="articles##showBySlug")
    .end()
.end();

</cfscript>

// 1. Store sidebar content for use in the layout
<cfsavecontent variable="mySidebar">
  <nav>Recent Posts</nav>
</cfsavecontent>
<cfset contentFor(sidebar=mySidebar)>

<!--- In your layout, output the stored section --->
<cfoutput>
  #includeContent("sidebar")#
  #includeContent()#
</cfoutput>

// 2. Push content onto a stack — multiple calls append by default
<cfsavecontent variable="firstScript">
  <script src="/js/base.js"></script>
</cfsavecontent>
<cfset contentFor(scripts=firstScript)>

<cfsavecontent variable="secondScript">
  <script src="/js/page.js"></script>
</cfsavecontent>
<cfset contentFor(scripts=secondScript)>

<!--- Both scripts are rendered in order --->
<cfoutput>#includeContent("scripts")#</cfoutput>

// 3. Prepend content to an existing section using position="first"
<cfsavecontent variable="criticalScript">
  <script src="/js/critical.js"></script>
</cfsavecontent>
<cfset contentFor(position="first", scripts=criticalScript)>

// 4. Overwrite an entire section with overwrite="all"
<cfsavecontent variable="replacementSidebar">
  <nav>Admin Sidebar</nav>
</cfsavecontent>
<cfset contentFor(overwrite="all", sidebar=replacementSidebar)>

// 5. Overwrite a specific position in the stack (position=1, overwrite=true)
<cfsavecontent variable="updatedScript">
  <script src="/js/updated.js"></script>
</cfsavecontent>
<cfset contentFor(position=1, overwrite=true, scripts=updatedScript)>

// 1. Include the view's generated content inside a layout file
// In `app/views/layout.cfm`, place this where the page body should appear
<!DOCTYPE html>
<html>
<head>
    <title>My App</title>
</head>
<body>
    #contentForLayout()#
</body>
</html>

// 2. Combine with includeContent to render named sections alongside the body
// In `app/views/layout.cfm`
<html>
<head>
    #includeContent("head")#
</head>
<body>
    #contentForLayout()#
    #includeContent("footer")#
</body>
</html>

// 1. Create a controller object for testing (no params)
usersController = controller("users");

// 2. Create a controller object with simulated request params for testing
params = {controller = "users", action = "show", key = 1};
usersController = controller(name = "users", params = params);

// 3. Use with processAction to test an action end-to-end
params = {controller = "users", action = "index"};
usersController = controller(name = "users", params = params);
usersController.processAction();
body = usersController.response();

// 1. Count all rows in the authors table
authorCount = model("author").count();

// 2. Count authors whose last name starts with "A"
authorOnACount = model("author").count(where="lastName LIKE 'A%'");

// 3. Count authors who have written books with titles starting with "A" (requires a hasMany association from author to book)
authorWithBooksOnACount = model("author").count(include="books", where="books.title LIKE 'A%'");

// 4. Count posts grouped by status, returning a query with one row per status
statusCounts = model("post").count(group="status");
// statusCounts is a query with columns: count, status

// 5. Count the number of comments on a specific post using a dynamic counter method
// (requires a hasMany association from post to comment)
aPost = model("post").findByKey(params.postId);
commentCount = aPost.commentCount();

// 1. Create a new author and save it to the database
newAuthor = model("author").create(params.author);

// 2. Create using named arguments
newAuthor = model("author").create(firstName="John", lastName="Doe");

// 3. Merge named arguments with a properties struct
newAuthor = model("author").create(active=1, properties=params.author);

// 4. Skip validation when creating (e.g. for seeding trusted data)
newAuthor = model("author").create(properties=params.author, validate=false);

// 5. Create inside a transaction that is rolled back (useful for dry-run testing)
newAuthor = model("author").create(properties=params.author, transaction="rollback");

// 6. Allow explicit createdAt / updatedAt values when importing legacy data
newAuthor = model("author").create(
	firstName="Jane",
	lastName="Smith",
	createdAt="2020-01-15 08:00:00",
	allowExplicitTimestamps=true
);

// 7. Scoped create via a hasOne / hasMany association
// (calls model("order").create(customerId=aCustomer.id, shipping=params.shipping) internally)
aCustomer = model("customer").findByKey(params.customerId);
anOrder = aCustomer.createOrder(shipping=params.shipping);

// 1. Create a blank migration file (uses timestamp prefix by default)
result = application.wheels.migrator.createMigration("CreateUsersTable");
// result -> "The migration 20240815123045_CreateUsersTable.cfc file was created"

// 2. Create a migration from a built-in template (e.g. create-table)
result = application.wheels.migrator.createMigration(
	migrationName="CreatePostsTable",
	templateName="create-table"
);

// 3. Create a migration using a sequential numeric prefix instead of a timestamp
result = application.wheels.migrator.createMigration(
	migrationName="AddIndexToUsers",
	migrationPrefix="numeric"
);
// result -> "The migration 001_AddIndexToUsers.cfc file was created"

// 1. Create a users table with standard columns and timestamps
t = createTable(name="users");
	t.string(columnNames="firstName,lastName", default="", allowNull=false, limit=50);
	t.string(columnNames="email", default="", allowNull=false, limit=255);
	t.string(columnNames="passwordHash", default="", allowNull=true, limit=500);
	t.boolean(columnNames="verified", default=false);
	t.integer(columnNames="roleId", default=0, allowNull=false);
	t.timestamps();
t.create();

// 2. Create a table with a custom string primary key (disabling the auto integer id)
t = createTable(name="tokens", id=false);
	t.primaryKey(name="id", allowNull=false, type="string", limit=36);
	t.string(columnNames="userId", allowNull=false, limit=36);
	t.datetime(columnNames="expiresAt", allowNull=false);
	t.timestamps();
t.create();

// 3. Create a join table with composite primary keys and force=true to recreate if it already exists
t = createTable(name="userRoles", id=false, force=true);
	t.primaryKey(name="userId", allowNull=false, limit=11);
	t.primaryKey(name="roleId", allowNull=false, limit=11);
t.create();

// 1. Create a simple database view that joins users and roles
v = createView(name="userRoles");
v.selectStatement(sql="SELECT u.id, u.firstName, u.lastName, r.name AS roleName FROM users u INNER JOIN roles r ON u.roleId = r.id");
v.create();

// 2. Create a view for active (non-deleted) users using method chaining
createView(name="activeUsers")
    .selectStatement(sql="SELECT id, firstName, lastName, email FROM users WHERE deletedAt IS NULL")
    .create();

// 3. Full up/down migration using createView and dropView
component extends="wheels.migrator.Migration" {
    function up() {
        createView(name="publishedArticles")
            .selectStatement(sql="SELECT id, title, body, authorId, publishedAt FROM articles WHERE publishedAt IS NOT NULL")
            .create();
    }
    function down() {
        dropView(name="publishedArticles");
    }
}

// 1. Include CSRF meta tags in your layout's <head> section
//    so that JavaScript AJAX requests can read the token and send it
//    as a request header when POSTing data to your application.
<head>
  <title>My App</title>
  #csrfMetaTags()#
</head>

// 2. Reading the token in JavaScript (e.g. with fetch) using the meta tags above
//    The rendered HTML will contain two meta tags like:
//    <meta name="csrf-param" content="authenticityToken">
//    <meta name="csrf-token" content="<generated-token>">
//
//    In your JavaScript you can then do:
//    const token = document.querySelector('meta[name="csrf-token"]').getAttribute('content');
//    fetch('/posts', { method: 'POST', headers: { 'authenticityToken': token }, body: ... });

// 1. Alternate CSS classes on table rows
// Outputs "odd" on the first row, "even" on the second, "odd" on the third, etc.
<table>
	<thead>
		<tr>
			<th>Name</th>
			<th>Phone</th>
		</tr>
	</thead>
	<tbody>
		<cfoutput query="employees">
			<tr class="#cycle("odd,even")#">
				<td>#employees.name#</td>
				<td>#employees.phone#</td>
			</tr>
		</cfoutput>
	</tbody>
</table>

// 2. Use named cycles when running multiple cycles simultaneously
// Cycle "row" and "highlight" advance independently
<cfoutput query="employees">
	<cfset rowClass = cycle(values="even,odd", name="row")>
	<cfset hlClass = cycle(values="highlight,normal,normal", name="highlight")>
	<tr class="#rowClass# #hlClass#">
		<td>#employees.name#</td>
	</tr>
</cfoutput>

// 3. Reset a cycle so it starts over from the first value
<cfoutput query="departments" group="departmentId">
	<div class="#cycle(values="even,odd", name="row")#">
		<ul>
			<cfoutput>
				<cfset rank = cycle(values="president,vice-president,director,manager,specialist,intern", name="position")>
				<li class="#rank#">#employees.name#</li>
			</cfoutput>
		</ul>
	</div>
	<cfset resetCycle("position")>
</cfoutput>

// 1. Override the data source for a model (basic usage).
// In models/User.cfc
config() {
	// Tell Wheels to use the data source named `users_source` instead of
	// the default one whenever this model makes SQL calls.
	dataSource("users_source");
}

// 2. Override the data source with explicit credentials.
// In models/LegacyOrder.cfc
config() {
	dataSource(datasource="legacy_db", username="app_reader", password="s3cr3t");
}

// 1. Add a single date column to a new table
t = createTable(name='events');
	t.string(columnNames='title', limit=255, allowNull=false);
	t.date(columnNames='eventDate', allowNull=false);
	t.timestamps();
t.create();

// 2. Add multiple date columns at once
t = createTable(name='subscriptions');
	t.string(columnNames='plan', limit=100, allowNull=false);
	t.date(columnNames='startDate,endDate', allowNull=false);
	t.timestamps();
t.create();

// 3. Add a date column with a default value to an existing table
t = changeTable(name='users');
	t.date(columnNames='birthDate', allowNull=true);
t.change();

// 1. Basic date field bound to a model object property
#dateField(objectName="event", property="startDate")#

// 2. Date field with a custom label, min/max constraints, and a CSS class
#dateField(objectName="event", property="startDate", label="Start Date", min="2024-01-01", max="2024-12-31", class="date-picker")#

// 3. Date fields for nested properties on a hasMany association (e.g., schedule items)
<cfloop from="1" to="#ArrayLen(project.milestones)#" index="i">
	#dateField(objectName="project", association="milestones", position="#i#", property="dueDate", label="Due Date ##i#")#
</cfloop>

// 1. Basic date field with a name and label
#dateFieldTag(name="startDate", label="Start Date")#

// 2. Pre-filled date value with min/max constraints
#dateFieldTag(name="eventDate", value="2024-06-15", min="2024-01-01", max="2024-12-31", label="Event Date")#

// 3. Date field with extra HTML attributes passed through
#dateFieldTag(name="dueDate", label="Due Date", class="form-control", id="due-date-input")#

<!--- Basic date select bound to a model object --->
#dateSelect(objectName="user", property="dateOfBirth")#

<!--- Show fields to select only month and year --->
#dateSelect(objectName="order", property="expirationDate", order="month,year")#

<!--- Display month as numbers and include a blank option --->
#dateSelect(objectName="event", property="startDate", monthDisplay="numbers", includeBlank=true)#

<!--- Restrict year range and use abbreviated month names --->
#dateSelect(objectName="reservation", property="checkInDate", startYear=2024, endYear=2030, monthDisplay="abbreviations")#

// 1. Basic date selection - the "Tag" version accepts `name` and `selected` directly instead of binding to a model object
#dateSelectTags(name="dateStart", selected=params.dateStart)#

// 2. Show only month and year fields (omit day)
#dateSelectTags(name="expiration", selected=params.expiration, order="month,year")#

// 3. Custom year range with a blank option and a label
#dateSelectTags(name="birthdate", selected=params.birthdate, startYear=1920, endYear=2024, includeBlank=true, label="Date of Birth")#

// 1. Add a single datetime column to a new table
t = createTable(name='orders');
	t.string(columnNames='status', limit=50, allowNull=false);
	t.datetime(columnNames='placedAt', allowNull=false);
	t.timestamps();
t.create();

// 2. Add multiple datetime columns at once
t = createTable(name='appointments');
	t.string(columnNames='title', limit=255, allowNull=false);
	t.datetime(columnNames='startAt,endAt', allowNull=false);
	t.timestamps();
t.create();

// 3. Add a nullable datetime column with a default to an existing table
t = changeTable(name='posts');
	t.datetime(columnNames='publishedAt', allowNull=true, default='NOW()');
t.change();

// 1. Basic date and time select for an article's published date
#dateTimeSelect(objectName="article", property="publishedAt")#

// 2. Show only month, day, hour, and minute (exclude year and second)
#dateTimeSelect(objectName="appointment", property="dateTimeStart", dateOrder="month,day", timeOrder="hour,minute")#

// 3. Use 12-hour time format with a blank option and a custom year range
#dateTimeSelect(objectName="event", property="startsAt", twelveHour=true, includeBlank=true, startYear=2020, endYear=2030)#

// 4. Display month as numbers, step minutes by 15, and add a label
#dateTimeSelect(objectName="meeting", property="scheduledAt", monthDisplay="numbers", minuteStep=15, label="Scheduled Date & Time")#

// 1. Basic usage - the "Tag" version accepts `name` and `selected` directly instead of binding to a model object
#dateTimeSelectTags(name="dateTimeStart", selected=params.dateTimeStart)#

// 2. Show only month/day for the date portion and hour/minute for the time portion
#dateTimeSelectTags(name="dateTimeStart", selected=params.dateTimeStart, dateOrder="month,day", timeOrder="hour,minute")#

// 3. Custom year range, 15-minute steps, 12-hour format, and a label
#dateTimeSelectTags(name="scheduledAt", selected=params.scheduledAt, startYear=2020, endYear=2030, minuteStep=15, twelveHour=true, label="Scheduled Date & Time")#

// 1. Basic usage: render a day-of-month select for a standalone form (not bound to a model)
#daySelectTag(name="day", selected=params.day)#

// 2. Pre-select day 15 and include a blank prompt at the top
#daySelectTag(name="birthDay", selected=15, includeBlank="-- Select Day --")#

// 3. Wrap the control with a label and surrounding HTML via prepend/append
#daySelectTag(name="day", selected=params.day, label="Day", prepend="<div class=""field"">", append="</div>")#

// 1. Add a single decimal column to a new table
t = createTable(name='products');
	t.string(columnNames='name', limit=255, allowNull=false);
	t.decimal(columnNames='price', precision=10, scale=2, allowNull=false);
	t.timestamps();
t.create();

// 2. Add multiple decimal columns at once
t = createTable(name='measurements');
	t.string(columnNames='label', limit=100, allowNull=false);
	t.decimal(columnNames='length,width,height', precision=8, scale=4, allowNull=false);
	t.timestamps();
t.create();

// 3. Add a nullable decimal column with a default to an existing table
t = changeTable(name='orders');
	t.decimal(columnNames='discount', precision=5, scale=2, allowNull=true, default='0.00');
t.change();

<cfscript>

mapper()
    // Route name:  articleReview
    // Example URL: /articles/987/reviews/12542
    // Controller:  Reviews
    // Action:      delete
    .delete(name="articleReview", pattern="articles/[articleKey]/reviews/[key]", to="reviews##delete")

    // Route name:  cookedBooks
    // Example URL: /cooked-books
    // Controller:  CookedBooks
    // Action:      delete
    .delete(name="cookedBooks", controller="cookedBooks", action="delete")

    // Route name:  logout
    // Example URL: /logout
    // Controller:  Sessions
    // Action:      delete
    .delete(name="logout", to="sessions##delete")

    // Route name:  clientsStatus
    // Example URL: /statuses/4918
    // Controller:  clients.Statuses
    // Action:      delete
    .delete(name="statuses", to="statuses##delete", package="clients")

    // Route name:  blogComment
    // Example URL: /comments/5432
    // Controller:  blog.Comments
    // Action:      delete
    .delete(
        name="comment",
        pattern="comments/[key]",
        to="comments##delete",
        package="blog"
    )
.end();

</cfscript>

// 1. Get a post object and then delete it from the database.
post = model("Post").findByKey(33);
post.delete();

// 2. Permanently delete a record even if the model uses soft deletes.
user = model("User").findByKey(params.userId);
user.delete(softDelete=false);

// 3. Delete a record without running callbacks (e.g. skip `beforeDelete` / `afterDelete`).
comment = model("Comment").findByKey(params.commentId);
comment.delete(callbacks=false);

// 4. If you have a `hasMany` association setup from `post` to `comment`, you can do a scoped call. (The `deleteComment` method below will call `comment.delete()` internally.)
post = model("Post").findByKey(params.postId);
comment = model("Comment").findByKey(params.commentId);
post.deleteComment(comment);

// 1. Delete all inactive users without instantiating them (skips callbacks and validations).
recordsDeleted = model("User").deleteAll(where="inactive=1");

// 2. Delete all inactive users and run their beforeDelete / afterDelete callbacks.
recordsDeleted = model("User").deleteAll(where="inactive=1", instantiate=true);

// 3. Permanently delete soft-deleted records (bypass the soft-delete column).
recordsDeleted = model("User").deleteAll(where="inactive=1", softDelete=false);

// 4. If you have a `hasMany` association from `Post` to `Comment`, you can use a scoped call. (The `deleteAllComments` method below calls `model("Comment").deleteAll(where="postId=#post.id#")` internally.)
post = model("Post").findByKey(params.postId);
howManyDeleted = post.deleteAllComments();

// 1. Delete the user with the primary key value of 1.
result = model("User").deleteByKey(1);
// result -> true (if the row was deleted), false otherwise

// 2. Permanently delete a soft-deletable record (bypass soft delete).
result = model("User").deleteByKey(key=1, softDelete=false);

// 3. Delete using a composite primary key (comma-separated values).
result = model("OrderItem").deleteByKey("42,7");

// 4. Delete within a transaction that can be rolled back (useful for testing).
result = model("User").deleteByKey(key=1, transaction="rollback");

// 1. Delete the user who signed up most recently.
result = model("User").deleteOne(order="signupDate DESC");

// 2. Delete the oldest unpaid invoice for a given customer.
result = model("Invoice").deleteOne(
	where="customerId=#params.customerId# AND status='unpaid'",
	order="createdAt ASC"
);

// 3. Permanently delete a soft-deletable record (bypass soft-delete behaviour).
result = model("User").deleteOne(
	where="status='banned'",
	order="createdAt ASC",
	softDelete=false
);

// 4. If you have a `hasOne` association set up from `User` to `Profile` you can do a scoped call.
// The `deleteProfile` method will call `model("Profile").deleteOne(where="userId=#aUser.id#")` internally.
aUser = model("User").findByKey(params.userId);
aUser.deleteProfile();

// 1. Deobfuscate a URL parameter to get the original numeric ID
// (Wheels automatically obfuscates numeric URL params when obfuscateUrls is enabled)
originalId = deobfuscateParam("b7ab9a50");
// originalId -> "35"

// 2. Round-trip: obfuscate a value, then deobfuscate it back
obfuscated = obfuscateParam("100");
original = deobfuscateParam(obfuscated);
// original -> "100"

// 3. Non-obfuscated values (e.g. already plain integers) are returned as-is
passthrough = deobfuscateParam("42");
// passthrough -> "42"

// 1. Compare two dates about a month apart
rightNow = Now();
aWhileAgo = DateAdd("d", -30, rightNow);
writeOutput(distanceOfTimeInWords(aWhileAgo, rightNow));
// -> "about 1 month"

// 2. Show a short gap with seconds included
justNow = Now();
fiveSecondsAgo = DateAdd("s", -5, justNow);
writeOutput(distanceOfTimeInWords(fiveSecondsAgo, justNow, includeSeconds=true));
// -> "less than 5 seconds"

// 3. Show various time ranges
now = Now();
writeOutput(distanceOfTimeInWords(DateAdd("n", -2, now), now));
// -> "2 minutes"

writeOutput(distanceOfTimeInWords(DateAdd("h", -3, now), now));
// -> "about 3 hours"

writeOutput(distanceOfTimeInWords(DateAdd("d", -5, now), now));
// -> "5 days"

writeOutput(distanceOfTimeInWords(DateAdd("yyyy", -2, now), now));
// -> "over 2 years"

// 1. Reverse a table creation by dropping the table
// Called automatically when rolling back this migration
function down() {
	var state = {};
	transaction {
		try {
			dropTable("employees");
		} catch (any e) {
			state.exception = e;
		}

		if (structKeyExists(state, "exception")) {
			transaction action="rollback";
			throw(
				errorCode = "1",
				detail    = state.exception.detail,
				message   = state.exception.message,
				type      = "any"
			);
		} else {
			transaction action="commit";
		}
	}
}

// 2. Reverse an addColumn() call by removing the column
function down() {
	var state = {};
	transaction {
		try {
			removeColumn(table="users", columnName="biography");
		} catch (any e) {
			state.exception = e;
		}

		if (structKeyExists(state, "exception")) {
			transaction action="rollback";
			throw(
				errorCode = "1",
				detail    = state.exception.detail,
				message   = state.exception.message,
				type      = "any"
			);
		} else {
			transaction action="commit";
		}
	}
}

// 3. Paired up() and down() inside a full migration component
component extends="[extends]" hint="Add status column to orders" {

	function up() {
		var state = {};
		transaction {
			try {
				addColumn(table="orders", columnType="string", columnName="status", limit=50, default="pending");
			} catch (any e) {
				state.exception = e;
			}

			if (structKeyExists(state, "exception")) {
				transaction action="rollback";
				throw(
					errorCode = "1",
					detail    = state.exception.detail,
					message   = state.exception.message,
					type      = "any"
				);
			} else {
				transaction action="commit";
			}
		}
	}

	function down() {
		var state = {};
		transaction {
			try {
				removeColumn(table="orders", columnName="status");
			} catch (any e) {
				state.exception = e;
			}

			if (structKeyExists(state, "exception")) {
				transaction action="rollback";
				throw(
					errorCode = "1",
					detail    = state.exception.detail,
					message   = state.exception.message,
					type      = "any"
				);
			} else {
				transaction action="commit";
			}
		}
	}

}

// 1. Drop a foreign key constraint by its explicit name
// In the down() function, remove a foreign key added in up()
dropForeignKey(table="orders", keyName="FK_orders_customers");

// 2. Drop a foreign key that was created via addReference()
// addReference() creates keys named FK_<table>_<pluralizedReference>
// So addReference(table="comments", referenceName="post") creates "FK_comments_posts"
dropForeignKey(table="comments", keyName="FK_comments_posts");

// 3. Use inside a migration's down() to reverse an addForeignKey() call
// up() called: addForeignKey(table="profiles", referenceTable="users", column="userId", referenceColumn="id")
// down() reverses it:
dropForeignKey(table="profiles", keyName="FK_profiles_users");

// 1. Drop the foreign key from comments.postId back to posts.id
// Removes the constraint named FK_comments_posts
dropReference(table="comments", referenceName="post");

// 2. Drop a foreign key from order_items back to orders
// Removes the constraint named FK_order_items_orders
dropReference(table="order_items", referenceName="order");

// 3. Use dropReference in the down() of a migration that added a reference in up()
// In your migration CFC:
//
// public void function up() {
//     addReference(table="comments", referenceName="post");
// }
//
// public void function down() {
//     dropReference(table="comments", referenceName="post");
// }

// 1. Drop a table in the down() migration (reversing a createTable in up())
component extends="wheels.migrator.Migration" hint="Add products table" {

	function up() {
		t = createTable(name="products");
		t.string(columnNames="name", allowNull=false);
		t.decimal(columnNames="price", precision=10, scale=2);
		t.boolean(columnNames="active", default=1);
		t.timestamps();
		t.create();
	}

	function down() {
		dropTable("products");
	}

}

// 2. Drop multiple tables in a single down() migration
component extends="wheels.migrator.Migration" hint="Add orders and line items tables" {

	function up() {
		t = createTable(name="lineItems");
		t.integer(columnNames="orderId");
		t.integer(columnNames="productId");
		t.integer(columnNames="quantity");
		t.timestamps();
		t.create();

		t = createTable(name="orders");
		t.integer(columnNames="userId");
		t.string(columnNames="status");
		t.timestamps();
		t.create();
	}

	function down() {
		dropTable("lineItems");
		dropTable("orders");
	}

}

// 1. Drop a view in the down() migration (reversing a createView in up())
component extends="wheels.migrator.Migration" hint="Add active users view" {

	function up() {
		createView(name="activeUsers")
			.selectStatement(sql="SELECT id, firstName, lastName, email FROM users WHERE deletedAt IS NULL")
			.create();
	}

	function down() {
		dropView(name="activeUsers");
	}

}

// 2. Drop multiple views in a single down() migration
component extends="wheels.migrator.Migration" hint="Add reporting views" {

	function up() {
		createView(name="publishedArticles")
			.selectStatement(sql="SELECT id, title, authorId, publishedAt FROM articles WHERE publishedAt IS NOT NULL")
			.create();

		createView(name="activeAuthors")
			.selectStatement(sql="SELECT id, firstName, lastName FROM users WHERE deletedAt IS NULL")
			.create();
	}

	function down() {
		dropView(name="publishedArticles");
		dropView(name="activeAuthors");
	}

}

// 1. Basic email field bound to an object property
#emailField(objectName="user", property="emailAddress")#

// 2. Email field with a custom label and a CSS class
#emailField(label="Email Address", objectName="user", property="emailAddress", class="form-control")#

// 3. Nested email field for a contacts association (hasMany)
<cfloop from="1" to="#ArrayLen(account.contacts)#" index="i">
	#emailField(label="Contact Email ##i#", objectName="account", association="contacts", position=i, property="email")#
</cfloop>

// 1. Basic email field with a name and pre-filled value
#emailFieldTag(name="userEmail", value="hello@example.com")#

// 2. Email field with a label
#emailFieldTag(label="Email Address", name="userEmail", value=params.userEmail)#

// 3. Email field with a CSS class and placeholder passed as extra HTML attributes
#emailFieldTag(name="contactEmail", value="", class="form-control", placeholder="you@example.com")#

<cfscript>

mapper()
    .namespace("admin")
        .resources("products")
    .end() // Ends the `namespace` block.

    .scope(package="public")
        .resources(name="products", nested=true)
          .resources("variations")
        .end() // Ends the nested `resources` block.
    .end() // Ends the `scope` block.
.end(); // Ends the `mapper` block.

</cfscript>

// 1. Close a form opened with startFormTag
#startFormTag(action="create")#
    <!--- your form controls --->
#endFormTag()#

// 2. Append a note after the closing form tag
#startFormTag(action="update", method="post")#
    <!--- your form controls --->
#endFormTag(append="<p>All fields are required.</p>")#

// 3. Wrap the closing tag with surrounding markup using prepend and append
#startFormTag(route="userSearch")#
    <!--- your form controls --->
#endFormTag(prepend="</div>", append="</section>")#

// 1. Map a `status` property to a comma-delimited list of allowed string values.
//    Wheels auto-validates that `status` is one of the listed values,
//    creates `isDraft()`, `isPublished()`, and `isArchived()` checker methods,
//    and registers `draft()`, `published()`, and `archived()` query scopes.
component extends="Model" {
	function config() {
		enum(property="status", values="draft,published,archived");
	}
}

// 2. Map a `priority` property using a struct so that the stored database value
//    differs from the human-readable name (0, 1, 2 are stored; low/medium/high are the names).
//    Generated methods: `isLow()`, `isMedium()`, `isHigh()`.
//    Generated scopes:  `model("Task").low()`, `model("Task").medium()`, `model("Task").high()`.
component extends="Model" {
	function config() {
		enum(property="priority", values={low: 0, medium: 1, high: 2});
	}
}

// 3. Using the generated checker methods and scopes at runtime.
//    `isPublished()` returns true/false; `published()` scopes a finder to that status.
post = model("Post").findByKey(key=42);
if (post.isPublished()) {
	writeOutput("This post is live.");
}

// Find all published posts using the auto-generated scope.
publishedPosts = model("Post").published().findAll();

// 1. Inspect all enum definitions on the Order model
info = model("Order").enumInfo();
// info -> {
//   status: {
//     property: "status",
//     names: "draft,published,archived",
//     values: {draft: "draft", published: "published", archived: "archived"}
//   }
// }

// 2. List all enum-mapped properties
info = model("Order").enumInfo();
for (propName in info) {
    writeOutput(propName & ": " & info[propName].names);
}
// status: draft,published,archived
// priority: low,medium,high

// 3. Use enum metadata to build a select list for a form
info = model("Order").enumInfo();
statusEnum = info["status"];
for (enumName in listToArray(statusEnum.names)) {
    storedValue = statusEnum.values[enumName];
    writeOutput(enumName & " -> " & storedValue);
}
// draft -> draft
// published -> published
// archived -> archived

// 1. Read a required environment variable
dbUrl = env("DATABASE_URL");
// dbUrl -> "postgres://user:pass@localhost/myapp" (or "" if not set)

// 2. Provide a default when the variable may be absent
smtpHost = env("SMTP_HOST", "localhost");
// smtpHost -> "localhost" when SMTP_HOST is not defined in .env or system env

// 3. Guard application startup based on an environment variable
appSecret = env("APP_SECRET_KEY");
if (!Len(appSecret)) {
	throw(type="App.ConfigError", message="APP_SECRET_KEY must be set.");
}

// 1. Check the total number of errors on an object
if (author.errorCount() GTE 10) {
    // Too many errors — bail out early
}

// 2. Check how many errors are associated with a specific property
if (author.errorCount(property="email") gt 0) {
    // The email property has at least one error
}

// 3. Count errors that were set with a specific error name
count = author.errorCount(name="invalidFormat");
// count -> 2 (two errors share the "invalidFormat" name)

// 1. Display the first error message (if any) on the email property
#errorMessageOn(objectName="user", property="email")#
// -> <span class="error-message">Email is not a valid email address.</span>
// -> (empty string when no error exists on that property)

// 2. Prepend and append custom text around the error message
#errorMessageOn(objectName="user", property="username", prependText="Problem:", appendText="Please try again.")#
// -> <span class="error-message">Problem: Username has already been taken. Please try again.</span>

// 3. Wrap the message in a div with a custom CSS class instead of the default span
#errorMessageOn(objectName="post", property="title", wrapperElement="div", class="field-error")#
// -> <div class="field-error">Title can't be blank.</div>

// 1. Display all error messages for a user object
#errorMessagesFor(objectName="user")#
// -> <ul class="error-messages"><li>Email is not a valid email address.</li><li>Username can't be blank.</li></ul>
// -> (empty string when the object has no errors)

// 2. Use a custom CSS class on the wrapping ul element
#errorMessagesFor(objectName="user", class="form-errors")#
// -> <ul class="form-errors"><li>Email is not a valid email address.</li></ul>

// 3. Suppress duplicate error messages
#errorMessagesFor(objectName="user", showDuplicates=false)#
// -> <ul class="error-messages"><li>can't be blank.</li></ul>
// (only one "can't be blank." entry even if multiple fields have the same message)

// 4. Include errors from associated objects as well
#errorMessagesFor(objectName="order", includeAssociations=true)#
// -> <ul class="error-messages"><li>Name can't be blank.</li><li>Line items quantity must be greater than zero.</li></ul>

// 1. Get all errors associated with the emailAddress property
errors = user.errorsOn("emailAddress");
// errors -> [{property: "emailAddress", message: "is invalid", name: ""}, ...]

// 2. Get only errors on emailAddress that were set with a specific error name
errors = user.errorsOn(property="emailAddress", name="formatCheck");
// errors -> [{property: "emailAddress", message: "must be a valid email", name: "formatCheck"}]

// 3. Check errors on a property and loop over them
errors = user.errorsOn("username");
for (error in errors) {
    writeOutput(error.message);
}

// 1. Get all general (base) errors for a model object after validation
user = model("User").new(params.user);
user.valid();
errors = user.errorsOnBase();
// errors -> [{property: "", message: "Account has been suspended", name: ""}]

// 2. Filter base errors by a specific error name
user.addErrorToBase(message="Account has been suspended", name="suspended");
user.addErrorToBase(message="Please accept the terms", name="terms");
suspendedErrors = user.errorsOnBase(name="suspended");
// suspendedErrors -> [{property: "", message: "Account has been suspended", name: "suspended"}]

// 3. Check for base errors and display them
errors = user.errorsOnBase();
if (arrayLen(errors)) {
    for (e in errors) {
        writeOutput(e.message);
    }
}

// 1. Extract text around a matching phrase with a custom radius
result = excerpt(text="CFWheels is a Rails-like MVC framework for Adobe ColdFusion and Lucee", phrase="framework", radius=5);
// result -> "...MVC framework for Ad..."

// 2. Use the default radius of 100 characters
result = excerpt(text="CFWheels is a powerful MVC framework built for ColdFusion developers who want to move fast.", phrase="powerful");
// result -> "CFWheels is a powerful MVC framework built for ColdFusion developers who want to move fast."

// 3. Customize the excerpt string used to indicate truncated text
result = excerpt(text="The quick brown fox jumps over the lazy dog", phrase="fox", radius=5, excerptString=" [...]");
// result -> " [...]brown fox jumps [...]"

// 1. Run a raw SQL statement during a migration
execute(sql = "UPDATE users SET active = 1 WHERE active IS NULL");

// 2. Create a database view with raw SQL
execute(sql = "CREATE VIEW active_users AS SELECT * FROM users WHERE active = 1");

// 3. Use execute() inside up() and down() to apply and reverse a custom SQL change
component extends="wheels.migrator.Migration" {
    function up() {
        execute(sql = "ALTER TABLE orders ADD COLUMN notes TEXT");
    }
    function down() {
        execute(sql = "ALTER TABLE orders DROP COLUMN notes");
    }
}

// 1. Check if any record exists in the table
anyUsers = model("User").exists();

// 2. Check if a record with a specific primary key exists
result = model("User").exists(key=params.key);

// 3. Check if a record matching a WHERE condition exists
joeExists = model("User").exists(where="firstName = 'Joe'");

// 4. Use the result in a conditional
if (model("User").exists(key=params.userId)) {
	// record was found, proceed
}

// 5. Include soft-deleted records in the check
deletedExists = model("User").exists(where="email='old@example.com'", includeSoftDeletes=true);

// 6. If you have a `belongsTo` association from `Comment` to `Post`, you can do a scoped call. (The `hasPost` method below calls `model("Post").exists(comment.postId)` internally.)
comment = model("Comment").findByKey(params.commentId);
commentHasAPost = comment.hasPost();

// 7. If you have a `hasOne` association from `User` to `Profile`, you can do a scoped call. (The `hasProfile` method below calls `model("Profile").exists(where="userId=#user.id#")` internally.)
user = model("User").findByKey(params.userId);
userHasProfile = user.hasProfile();

// 8. If you have a `hasMany` association from `Post` to `Comment`, you can do a scoped call. (The `hasComments` method below calls `model("Comment").exists(where="postId=#post.id#")` internally.)
post = model("Post").findByKey(params.postId);
postHasComments = post.hasComments();

// 1. Basic file upload field bound to an object and property
#fileField(objectName="photo", property="imageFile")#

// 2. Provide a custom label for the file field
#fileField(label="Profile Photo", objectName="user", property="avatar")#

// 3. Display file upload fields for a hasMany association using nested properties
<fieldset>
	<legend>Screenshots</legend>
	<cfloop from="1" to="#ArrayLen(site.screenshots)#" index="i">
		#fileField(label="File ##i#", objectName="site", association="screenshots", position=i, property="file")#
		#textField(label="Caption ##i#", objectName="site", association="screenshots", position=i, property="caption")#
	</cfloop>
</fieldset>

// 1. Basic file upload field with a label
#fileFieldTag(name="photo", label="Profile Photo")#

// 2. File upload field with a CSS class and no label
#fileFieldTag(name="attachment", class="upload-input")#

// 3. File upload field with label placement and wrapper HTML
#fileFieldTag(name="resume", label="Upload Resume", labelPlacement="before", prepend="<div class='field'>", append="</div>")#

// 1. Get the entire filter chain for the current controller
myFilterChain = filterChain();
// myFilterChain -> array of structs, each with keys: through, type, only, except, arguments
// e.g. [{ through: "checkLogin", type: "before", only: "", except: "" }, ...]

// 2. Get only the before-filters
beforeFilters = filterChain(type="before");
for (f in beforeFilters) {
    writeOutput(f.through);
}

// 3. Get only the after-filters
afterFilters = filterChain(type="after");
writeOutput(arrayLen(afterFilters));

// 1. Run `restrictAccess` before every action in this controller (declared inside config()).
filters("restrictAccess");

// 2. Run two before-filters on every action except `home` and `login`.
filters(through="isLoggedIn, checkIPAddress", except="home, login");

// 3. Run `auditLog` after only the `create`, `update`, and `delete` actions.
filters(through="auditLog", type="after", only="create, update, delete");

// 4. Prepend a filter so it runs before any already-registered filters.
filters(through="maintenanceCheck", placement="prepend");

// Note: filter functions must be declared as `private` in the controller
// to prevent them from being routed as public actions.
// Example controller setup:
// component extends="Controller" {
//     function config() {
//         filters("restrictAccess");
//     }
//     private function restrictAccess() {
//         if (!isLoggedIn()) {
//             redirectTo(route="login");
//         }
//     }
// }

// 1. Get all users ordered by last name
users = model("user").findAll(order="lastName ASC");

// 2. Get only 5 users in a random order
fiveRandomUsers = model("user").findAll(maxRows=5, order="random");

// 3. Include a belongsTo association and filter with a WHERE clause
articles = model("article").findAll(include="author", where="published=1", order="createdAt DESC");

// 4. Include a hasMany association in the opposite direction
bobsArticles = model("author").findAll(include="articles", where="firstName='Bob'");

// 5. Use pagination (records 26-50) with a nested include (song belongsTo album, album belongsTo artist)
songs = model("song").findAll(include="album(artist)", page=2, perPage=25);

// 6. Return results as an array of model objects instead of a query
activeUsers = model("user").findAll(where="active=1", order="lastName ASC", returnAs="objects");
for (user in activeUsers) {
	writeOutput(user.firstName & " " & user.lastName);
}

// 7. Return results as an array of structs
userStructs = model("user").findAll(where="active=1", returnAs="structs");

// 8. Use a dynamic finder to get all books released in a certain year
// (same as model("book").findAll(where="releaseYear=#params.year#"))
books = model("book").findAllByReleaseYear(params.year);

// 9. Use a dynamic finder with multiple criteria
// (same as model("book").findAll(where="releaseYear=#params.year# AND type='#params.type#'"))
books = model("book").findAllByReleaseYearAndType("#params.year#,#params.type#");

// 10. Use a scoped call via a hasMany association (calls findAll internally with a where clause)
post = model("post").findByKey(params.postId);
comments = post.comments();

// 11. Use GROUP BY with a calculated property (generates HAVING instead of WHERE)
// Order model has a calculated property: property(name="totalAmount", sql="SUM(amount)")
ids = model("order").findAll(group="productId", where="totalAmount > 1000", select="productId");

// 12. Include soft-deleted records
allUsers = model("user").findAll(includeSoftDeletes=true, order="lastName ASC");

// 13. Cache the query results for 10 minutes
cachedUsers = model("user").findAll(where="active=1", cache=10);

// 14. Return the generated SQL string instead of running the query
sql = model("user").findAll(where="active=1", order="lastName ASC", returnAs="sql");
// sql -> "SELECT ... FROM users WHERE active = 1 ORDER BY last_name ASC"

// 15. Use index hints (MySQL and SQL Server only)
indexes = {
	author="idx_authors_name",
	post="idx_posts_created"
};
posts = model("author").findAll(
	where="firstName LIKE '#params.q#%' OR subject LIKE '#params.q#%'",
	include="posts",
	useIndex=indexes
);

// 1. Get a comma-delimited list of all primary key values for the Artist model
primaryKeyList = model("artist").findAllKeys();
// primaryKeyList -> "1,2,3,4,5"

// 2. Get keys for active artists only, enclosed in single quotes, separated by a pipe
primaryKeyList = model("artist").findAllKeys(quoted=true, delimiter="|", where="active=1");
// primaryKeyList -> "'1'|'3'|'5'"

// 3. Use the result directly in a SQL IN clause for a subsequent query
keyList = model("artist").findAllKeys(quoted=true, where="genreId=7");
albums = model("album").findAll(where="artistId IN (#keyList#)");

// 1. Get the author with the primary key value `99` as an object
auth = model("author").findByKey(99);

// 2. Get an author based on a form/URL value and handle the not-found case
auth = model("author").findByKey(params.key);
if (!isObject(auth)) {
    flashInsert(message="Author #params.key# was not found");
    redirectTo(back=true);
}

// 3. Fetch only selected columns for a record
user = model("user").findByKey(key=params.id, select="id,firstName,email");

// 4. Include a belongsTo association when fetching by key
order = model("order").findByKey(key=params.orderId, include="customer");

// 5. Cache the lookup for 10 minutes and include soft-deleted records
product = model("product").findByKey(key=params.id, cache=10, includeSoftDeletes=true);

// 6. Use a scoped call via a belongsTo association (calls `model("post").findByKey(comment.postId)` internally)
comment = model("comment").findByKey(params.commentId);
post = comment.post();

// 1. Send a newsletter email to every subscriber one at a time
model("Subscriber").findEach(callback = function(subscriber) {
    sendEmail(
        to = subscriber.email,
        subject = "Monthly Newsletter",
        template = "/emails/newsletter",
        subscriber = subscriber
    );
});

// 2. Process users as structs and write a report entry for each one
model("User").findEach(
    where = "active = 1",
    order = "lastName ASC",
    returnAs = "struct",
    callback = function(user) {
        writeLog("Processing user: #user.firstName# #user.lastName#");
    }
);

// 3. Archive old orders in smaller batches to reduce memory pressure
model("Order").findEach(
    where = "createdAt < '#DateFormat(DateAdd('yyyy', -2, Now()), 'yyyy-mm-dd')#'",
    batchSize = 250,
    callback = function(order) {
        order.archived = true;
        order.save();
    }
);

// 1. Get the first user record (ordered by primary key ascending)
user = model("User").findFirst();
// Returns the model object with the lowest primary key value, or false if no records exist.

// 2. Get the first user ordered by a specific property
user = model("User").findFirst(property="createdAt");
// Returns the oldest user (lowest createdAt value).

// 3. Get the first active user ordered by last name, then first name
user = model("User").findFirst(properties="lastName,firstName", where="active = 1");
// Equivalent to: ORDER BY lastName ASC, firstName ASC with a WHERE clause applied.
// Returns a model object, or false if no matching record is found.

// 1. Process all users in batches of 500 (default), logging each batch
model("User").findInBatches(callback=function(batch) {
	writeOutput("Processing " & batch.recordCount & " users");
});

// 2. Process active orders in batches of 200, filtered with a WHERE clause
model("Order").findInBatches(
	batchSize=200,
	where="status='active'",
	order="createdAt ASC",
	callback=function(batch) {
		// batch is a cfquery result set by default
		for (local.i = 1; local.i <= batch.recordCount; local.i++) {
			writeOutput(batch.orderId[local.i] & ": " & batch.total[local.i]);
		}
	}
);

// 3. Receive each batch as an array of model objects instead of a query
model("User").findInBatches(
	batchSize=100,
	returnAs="objects",
	where="active=1",
	callback=function(batch) {
		for (user in batch) {
			user.sendNewsletter();
		}
	}
);

// 4. Receive each batch as an array of structs
model("Product").findInBatches(
	batchSize=250,
	returnAs="structs",
	select="id,name,price",
	callback=function(batch) {
		for (product in batch) {
			writeOutput(product.name & " costs " & product.price);
		}
	}
);

// 5. Include soft-deleted records while processing in batches
model("User").findInBatches(
	includeSoftDeletes=true,
	callback=function(batch) {
		writeOutput("Batch has " & batch.recordCount & " records (including deleted)");
	}
);

// 1. Get the last user record (ordered by primary key descending)
lastUser = model("User").findLastOne();
// Returns a User object for the record with the highest primary key, or false if none exist.

// 2. Get the most recently created post by ordering on a different property
latestPost = model("Post").findLastOne(property="createdAt");
// Returns the Post object with the latest createdAt value.

// 3. Get the last active product, using a where clause alongside the property order
lastActive = model("Product").findLastOne(property="updatedAt", where="isActive = 1");
// Returns the most recently updated active product, or false if none exist.

// 1. Get the most recent order as an object from the database
order = model("Order").findOne(order="datePurchased DESC");

// 2. Use a where clause to find the first user with a specific email address
user = model("User").findOne(where="email='someone@example.com'");

// 3. Use a dynamic finder to get the first person with the last name Smith.
// Equivalent to: model("User").findOne(where="lastName='Smith'")
person = model("User").findOneByLastName("Smith");

// 4. Use a dynamic finder to match on two columns.
// Equivalent to: model("User").findOne(where="email='someone@example.com' AND password='mypass'")
user = model("User").findOneByEmailAndPassword("someone@example.com", "mypass");

// 5. Return false when no matching record is found (the default returnAs="object" behavior)
user = model("User").findOne(where="email='unknown@example.com'");
if (!isObject(user)) {
    writeOutput("No user found.");
}

// 6. Return as a query result set instead of an object
userQuery = model("User").findOne(where="role='admin'", returnAs="query");

// 7. Use a scoped call via a hasOne association from User to Profile.
// The profile() method calls model("Profile").findOne(where="userId=#user.id#") internally.
user = model("User").findByKey(params.userId);
profile = user.profile();

// 8. Use a scoped call via a hasMany association from Post to Comment.
// The findOneComment() method calls model("Comment").findOne(where="postId=#post.id#") internally.
post = model("Post").findByKey(params.postId);
comment = post.findOneComment(where="approved=1");

//--------------------------------------------------------------------
// Example 1: Basic usage — show a "First" link at the top of a
// paginated list; renders a disabled span when already on page 1

// Controller code
param name="params.page" type="integer" default="1";
posts = model("Post").findAll(page=params.page, perPage=10, order="createdAt DESC");

// View code
<cfoutput>
    #firstPageLink()#
    #previousPageLink()#
    #pageNumberLinks()#
    #nextPageLink()#
    #lastPageLink()#
</cfoutput>


//--------------------------------------------------------------------
// Example 2: Custom link text and CSS classes

// View code
<cfoutput>
    #firstPageLink(
        text="&laquo;&laquo; First",
        class="page-link",
        disabledClass="page-link disabled"
    )#
</cfoutput>


//--------------------------------------------------------------------
// Example 3: Hide the disabled element entirely when on the first page

// View code
<cfoutput>
    #firstPageLink(showDisabled=false)#
</cfoutput>


//--------------------------------------------------------------------
// Example 4: Use a named route so page numbers appear in the URL path
// instead of as a query-string param (e.g. /articles/page/3)

// Route setup in app/config/routes.cfm
mapper()
    .get(name="paginatedArticles", pattern="articles/page/[page]", to="articles##index")
    .get(name="articles", pattern="articles", to="articles##index")
.end();

// Controller code
param name="params.page" type="integer" default="1";
articles = model("Article").findAll(page=params.page, perPage=20, order="title");

// View code
<cfoutput>
    #firstPageLink(route="paginatedArticles", pageNumberAsParam=false)#
</cfoutput>

// 1. Get the current value of a specific key in the Flash
notice = flash("notice");
// notice -> "Your profile was updated successfully."

// 2. Get the entire Flash as a struct when no key is passed
flashContents = flash();
// flashContents -> {notice: "Record saved.", error: "Something went wrong."}

// 3. Check for a key before reading it to avoid an empty-string fallback
if (flashKeyExists("error")) {
    errorMessage = flash("error");
}

// 1. Clear all flash data
flashClear();

// 2. Insert some messages, then clear them all before redirecting
flashInsert(notice="Record saved.");
flashInsert(warning="Check your settings.");
// Oops — wipe everything and start fresh
flashClear();
// flash() is now an empty struct: {}

// 3. Clear flash conditionally inside a controller action
function checkout() {
    if (!isLoggedIn()) {
        flashClear();
        flashInsert(error="You must be logged in to check out.");
        redirectTo(action="login");
    }
}

// 1. Check how many keys are currently in the Flash
count = flashCount();
// count -> 0 (Flash is empty), or a positive integer when keys exist

// 2. Only render a Flash notice section when there is something to show
if (flashCount()) {
    writeOutput("You have " & flashCount() & " flash message(s).");
}

// 3. Use alongside flashIsEmpty() — flashCount() powers the isEmpty check
flashInsert(notice="Saved successfully", warning="Check your email");
count = flashCount();
// count -> 2

// 1. Delete a key from the Flash
flashDelete(key="errorMessage");

// 2. Check the return value — true if the key existed, false if it did not
wasPresent = flashDelete(key="notice");
// wasPresent -> true  (key existed and was removed)
// wasPresent -> false (key did not exist in the Flash)

// 3. Conditionally act on whether the key was actually removed
if (flashDelete(key="warning")) {
    // key existed; it has now been removed from the Flash
} else {
    // key was not present; nothing was changed
}

// 1. Insert a single key / value into the Flash
flashInsert(notice="Your profile has been updated.");

// 2. Insert multiple keys at once
flashInsert(success="Account created.", hint="Check your email to confirm.");

// 3. Read back a Flash value in the next action or view
// (After a redirect, in the destination action or its view:)
msg = flash("notice");
// msg -> "Your profile has been updated."

// 1. Check whether the Flash is empty before rendering a notice area
if (!flashIsEmpty()) {
    writeOutput(flash("notice"));
}

// 2. Insert a message and confirm the Flash is no longer empty
flashInsert(notice="Record saved successfully.");
empty = flashIsEmpty();
// empty -> false

// 3. After clearing the Flash, confirm it is empty again
flashClear();
empty = flashIsEmpty();
// empty -> true

// 1. Keep the entire Flash for the next request
flashKeep();

// 2. Keep the "error" key in the Flash for the next request
flashKeep("error");

// 3. Keep both the "error" and "success" keys in the Flash for the next request
flashKeep("error,success");

// 1. Check for an "error" key before reading it
if (flashKeyExists("error")) {
    errorMessage = flash("error");
}

// 2. Conditionally display a success notice
if (flashKeyExists("success")) {
    writeOutput(flash("success"));
}

// 3. Guard before deleting a specific flash key
if (flashKeyExists("notice")) {
    flashDelete("notice");
}

// 1. Display all Flash messages in a view
// In the controller action:
flashInsert(success="Your post was successfully submitted.");
flashInsert(alert="Don't forget to tweet about this post!");
flashInsert(error="This is an error message.");

// In the layout or view:
writeOutput(flashMessages());

// Generates (keys sorted alphabetically):
// <div class="flash-messages">
//   <p class="alert-message">Don't forget to tweet about this post!</p>
//   <p class="error-message">This is an error message.</p>
//   <p class="success-message">Your post was successfully submitted.</p>
// </div>


// 2. Show only a single Flash key using the `key` alias
writeOutput(flashMessages(key="success"));

// Generates:
// <div class="flash-messages">
//   <p class="success-message">Your post was successfully submitted.</p>
// </div>


// 3. Show a specific set of keys in a defined order using `keys`
writeOutput(flashMessages(keys="success,alert"));

// Generates (in the order supplied, not alphabetically):
// <div class="flash-messages">
//   <p class="success-message">Your post was successfully submitted.</p>
//   <p class="alert-message">Don't forget to tweet about this post!</p>
// </div>


// 4. Always render the container div, even when the Flash is empty
writeOutput(flashMessages(includeEmptyContainer=true));

// Generates:
// <div class="flash-messages"></div>


// 5. Use a custom CSS class on the outer container
writeOutput(flashMessages(class="notifications"));

// Generates:
// <div class="notifications">
//   <p class="alert-message">Don't forget to tweet about this post!</p>
//   <p class="error-message">This is an error message.</p>
//   <p class="success-message">Your post was successfully submitted.</p>
// </div>

// 1. Add a single float column to a new table
t.float("price");

// 2. Add a float column with a default value
t.float(columnNames="rating", default="0.0");

// 3. Add multiple float columns at once
t.float("latitude,longitude");

// 4. Add a float column that does not allow NULL values
t.float(columnNames="score", allowNull=false);

// 5. Use float() within a createTable migration
t = createTable("measurements");
t.float("temperature");
t.float(columnNames="humidity,pressure", default="0.0");
t.timestamps();
t.create();

// 1. Generate a UUID and store it in a variable
newId = generateUUID();
// newId -> "550e8400-e29b-41d4-a716-446655440000" (36-character UUID)

// 2. Use generateUUID() to assign a unique identifier before saving a record
post = model("Post").new(title="Hello World");
post.externalId = generateUUID();
post.save();

// 3. Generate a UUID compatible with SQL Server's uniqueidentifier column
// Useful when inserting records that need a GUID primary key
token = generateUUID();
// token -> "a1b2c3d4-e5f6-7890-abcd-ef1234567890"