1 of 8

Active Entity

This class allows you to simulate the Active Record pattern in your ORM entities by inheriting from our Active Entity class. This will make your ORM entities get all the functionality of our Virtual and Base ORM services so you can do finds, searches, listings, counts, execute queries, transaction safe deletes, saves, updates, criteria building, and even validation right from within your ORM Entity. The idea behind the Active Entity is to allow you to have a very nice abstraction to all the ColdFusion ORM capabilities (hibernate) and all of our ORM extensions like our ColdBox Criteria Builder. With Active Entity you will be able to:

Find entities using a variety of filters and conditions
ORM paging
Specify order, searches, criterias and grouping of orm listing and searches
Use DLM style hibernate operations for multiple entity deletion, saving, and updating
Check for existence of records
Check for counts using criterias
Use our extensive ColdBox Criteria Builder to build Object Oriented HQL queries
Validate your entity using our awesome validation engine

Enabling Active Entity

To work with Active Entity you must do a few things to tell ColdBox you want to use Active Entity and enable validation and injections:

Enable the ORM in your Application.cfc with event handling turned on, manage session and flush at request end as false.
Enable the orm configuration structure in your ConfigurationCFC to allow for ColdBox to do entity injections

1.Application.cfc

The following are vanilla configurations for enabling the ORM in ColdFusion:

// Enable ORM
this.ormEnabled       = true;
// ORM Datasource
this.datasource          = "contacts";
// ORM configuration settings
this.ormSettings      = {
    // Location of your entities, default is your convention model folder
    cfclocation = ["models"],
    // Choose if you want ORM to create the database for you or not?
    dbcreate    = "none",
    // Log SQL or not
    logSQL         = true,
    // Don't flush at end of requests, let Active Entity manage it for you
    flushAtRequestEnd = false,
    // Don't manage session, let Active Entity manage it for you
    autoManageSession = false,
    // Active ORM events
    eventHandling       =  true,
    // Use the ColdBox WireBox Handler for events
    eventHandler = "cborm.models.EventHandler"
};

2.ORM Config Settings

Open your config/ColdBox.cfc and either uncomment or add the following settings:

Building

Please remember that you can use ANY method found in the Base ORM Service except that you will not pass an argument of entityName anymore as you have now binded to an ORM entity. You can also visit our API for all the methods.

component persistent="true" table="your_table" extends="cborm.models.ActiveEntity"{

}

The inheritance is what will make your Entity come alive with tons of useful methods!

Constructor Properties

If you override the constructor in your ORM entity, then make sure that you call the super.init() with the optional arguments below:

component persistent="true" table="your_table" extends="coldbox.system.orm.hibernate.ActiveEntity"{

    function init(){

        setCreatedDate( now() );

        super.init(useQueryCaching=true);

        return this;
    }

}

Usage

You just use entityNew() like you would with any ORM entity and then just call our cool methods:

// get a new User entity
user = entityNew("User");
// Count all the users in the database
usersFound = user.count();

// create a new user entity and pre-populate it with data
coolUser = user.new( {firstName="Luis",lastName="Majano",Awesome=true} );
// save the user object
coolUser.save();

// Retrieve a user with an ID of 123
luis = user.get("123");

Validation

Our active entity object will also give you access to our validation engine by giving your ORM entities the following functions:

/**
* Validate the ActiveEntity with the coded constraints -> this.constraints, or passed in shared or implicit constraints
* The entity must have been populated with data before the validation
* @fields.hint One or more fields to validate on, by default it validates all fields in the constraints. This can be a simple list or an array.
* @constraints.hint An optional shared constraints name or an actual structure of constraints to validate on.
* @locale.hint An optional locale to use for i18n messages
* @excludeFields.hint An optional list of fields to exclude from the validation.
*/
boolean function isValid(string fields="*", any constraints="", string locale="", string excludeFields="");

/**
* Get the validation results object.  This will be an empty validation object if isValid() has not being called yet.
*/
coldbox.system.validation.result.IValidationResult function getValidationResults();

Important In order for validation to work, WireBox ORM entity injection must be enabled first!
ColdBox ORM Entity Injection
WireBox Standalone ORM Entity Injection

This makes it really easy for you to validate your ORM entities.

Sample:

import coldbox.system.orm.hibernate.*;
component persistent="true" extends="ActiveEntity"{
    // Properties
    property name="firstName";
    property name="lastName";
    property name="email";
    property name="username";
    property name="password";

    // Validation Constraints
    this.constraints = {
        "firstName" = {required=true}, 
        "lastName" = {required=true},
        "email" = {required=true,type="email"},
        "username" = {required=true, size="5..10"},
        "password" = {required=true, size="5..10"}
    };
}

Handlers Sample:

component{

        property name="Messagebox" inject="id:messagebox@cbmessagebox";

    function index(event,rc,prc){
        prc.users = entityNew("User").list(sortOrder="lastName asc");
        event.setView("users/list");
    }

    function save(event,rc,prc){
        event.paramValue("id","");
        var user = populateModel( entityNew("User").get( rc.id ) );

        if( user.isValid() {
            user.save();
            flash.put("notice","User Saved!");
            setNextEvent("users.index");
        }
        else{
            Messagebox.error(messageArray=user.getValidationResults().getAllErrors());
            editor(event,rc,prc);
        }

    }

    function editor(event,rc,prc){
        event.paramValue("id","");
        prc.user = entityNew("User").get( rc.id );
        event.setView("users/editor");
    }

    function delete(event,rc,prc){
        event.paramValue("id","");
        entityNew("User").deleteById( rc.id );
        flash.put("notice","User Removed!");
        setNextEvent("users.index");
    }
}

Please refer to the ORM:BaseORMService for all the cool methods and functionality you can use with Active Entity. Like always, refer to the latest CFC Docs for methods and arguments.