Mura ORM Entity

In a nutshell, a Mura ORM entity is described by creating a ColdFusion component (.CFC). Mura leverages some of the standard attributes of a Mura ORM component, and also utilizes some custom attributes, as outlined in the table below.

Example Mura ORM Component

1. component
2.   extends="mura.bean.beanORM"
3.   entityname="something"
4.   table="somethings"
5.   bundleable="true"
6.   displayname="SomethingBean"
7.   public=true
8.   orderby="{someproperty}" {
9.  
10. // Properties & Methods
11.  
12. }

Mura ORM Component Properties

To describe the various properties/attributes and relationships of Mura ORM entities, use CFML properties. The following table describes the available attributes for Mura ORM component properties.

property name="site"
  cfc="site"
  fieldtype="many-to-one"
  fkcolumn="siteid";

property name="addresses"
  singularname="address"
  cfc="address"
fieldtype="one-to-many";

Validation Attributes

If property has a "validate" attribute, you may include additional attributes to the property for validation.

The example below illustrates how to use a validation attribute, when a property has a "validate" attribute.

1. property name="year" datatype="int" validate="numeric" minvalue="1900" maxvalue="2017";

Related Entity Synthesized Methods

If the property is a related entity, and the fieldtype attribute is either "one-to-many" or "many-to-many", the following methods are automatically available to the entity itself. The methods below are executed for both the property's name and singularname.

If the property is a related entity, and the fieldtype attribute is either "one-to-one" or "many-to-one", the following methods are automatically available to the entity itself.

Example Mura ORM Component With Properties

The following code defines an entity named "something" that contains a few basic properties.

1. component
2.   extends="mura.bean.beanORM"
3.   entityname="something"
4.   table="somethings"
5.   bundleable="true"
6.   displayname="SomethingBean"
7.   public=true
8.   orderby="namefirst,namelast" {
9.  
10.   // primary key
11. property name="somethingid" fieldtype="id";
12.  
13.   // attributes
14. property name="namefirst" datatype="varchar" length="255" required=true;
15.   property name="namelast" datatype="varchar" length="255" required=true;
16.  
17. // methods could go here
18. }

Working With Entities

The code examples below demonstrate various methods for working with entities. As you'll see, the syntax is no different than working with any other Mura bean object.

1. // Loading entities
2. entity = m.getBean('entityName')
3. .loadBy(someAttribute='Something');
4.  
5. // Getting attributes
6. entity.get('attributeName');
7.  
8. // Setting attributes
9. entity.set('attributeName', 'Some Value')
10.  
11. // Deleting entities
12. entity.delete();
13.  
14. // Saving entities
15. entity.save();
16.  
17. // Get a feed of entites
18. m.getFeed('entityName');

Error Handling

As previously mentioned, working with entities is no different than working with any other Mura bean object. We've already covered a bit of error handling, but it doesn't hurt to review it once again here.

Errors are returned as a structure, where each key in the struct represents the object's attribute "name", and the value contains the error message itself.

1. entity.save();
2.  
3. // If the bean has errors, then it did not save...
4. if ( entity.hasErrors() ) {
5.  
6. // errors are returned as a struct
7. errors = entity.getErrors();
8.  
9. WriteOutput('<h3>Please review the following errors:</h3><ul>');
10.  
11.   // Loop over the errors
12. for ( e in errors ) {
13. WriteOutput('<li>Attribute: #e# <br> Message: #errors[e]#</li>');
14.   }
15.  
16.   WriteOutput('</ul>');
17. } else {
18. WriteOutput('<h2>Success :: No Errors!</h2>');
19. }

Custom Validation

Mura also allows you to include your own custom validation rules. In order to do so, you simply include a custom validate() method in your entity's component file (.CFC), and when a save() call is made on your entity, it will trigger your custom method. The key is you don't "return" anything, you simply add your custom errors to the existing errors struct.

You could also use this to do complex validation requirements. For example, maybe you have a custom radio button or checkbox, and when it's selected, your form displays additional form fields that you will then want to be "required". You could simply check for the existence and/or value of the triggering field, and if it exists, run through each of the additional required form fields in your own validation.

The example below demonstrates how to create your own error messages when validating an attribute of your entity.

1. public any function validate() {
2.  
3. // This runs the standard validation ...
4.   // which will use your property definition's "validate" requirements, etc.
5.   // and it also gives you a way to reference the entity object itself
6.   var obj = super.validate();
7.  
8.   // Obtain a reference to any errors
9.   var errors = obj.getErrors();
10.  
11.   // Now, you can check anything you want on your properties or entity attributes
12. // For example, if you have a property labeled "wantsmoreoptions" and it's true,
13. // You could check for the other fields
14.   if ( obj.get('wantsmoreoptions') ) {
15.  
16.   // Yes, they want more options!
17.   // Make sure they completed them ...
18.   if ( !Len(obj.get('option99')) ) {
19. errors.option99 = 'Option 99 is required.';
20.   } 
21.  
22.   // etc. ...
23.   }
24.  
25. }