Mura Beans & Objects

The term "bean" is borrowed from the Java programming language. According to Wikipedia, JavaBeans are reusable software components. They are used to encapsulate many objects into a single object (the bean), so that they can be passed around as a single bean object instead of multiple individual objects.

In CFML, a bean can be a ColdFusion Component (CFC). However, there are a few characteristics the CFC must have to differentiate itself from other types of CFCs:

Serializable
A no-argument constructor
Allows access to properties using getter and setter methods

In short, beans hold information about the object or entity they represent, and allow developers the ability to quickly and easily access and manipulate some of its attributes. For example, a bean could represent a person, and its attributes might contain data such as the person's name, age, height, weight, birthdate, etc.

Mura Bean Objects

In Mura, developers can use its software components without necessarily having to understand their inner workings. Mura bean objects provide developers the ability to directly access and manipulate their associated records in the database. This is most easily accomplished using the bean's associated helper methods. As you'll see in the Custom Objects section, developers may also create their own bean objects too.

Syntax

Here we cover the basic syntax that applies to all Mura bean objects. When you want to work with a specific bean object, you will first want to load it by a specific attribute. However, as each bean object is slightly different, the attributes you may load by will vary.

Loading Bean Objects

As illustrated in the examples below, you should use the special Mura scope (m) method labeled getBean, when you wish to work with a Mura bean object.

someBean = m.getBean('someBean')
.loadBy(someAttribute='someAttributeValue');

You may optionally include a siteid parameter to load a bean from another Mura site, managed under the same installation.

someBean = m.getBean('someBean')
  .loadBy(someAttribute='someAttributeValue', siteid='SomeSiteID');

Getting an Attribute of a Bean Object

The "getter" examples below illustrate how to "get" a specific attribute of a bean object.

someBean.get('attributeName');
someBean.get{AttributeName}();
someBean.getValue('attributeName');

Setting an Attribute of a Bean Object

The "setter" examples below illustrate how to "set" a specific attribute of a bean object.

someBean.set('attributeName', 'Some Value');
someBean.set{AttributeName}('Some Value');
someBean.setValue('attributeName', 'Some Value');

Verify Existence of a Bean Object

Most bean objects have a couple of helper methods to verify whether the bean object exists, or if it's new. Whichever method you choose, is entirely personal preference.

// returns `true` if bean exists, or `false` if it does not
someBean.exists();
// returns `true` if bean is new, or `false` if bean already exists
someBean.getIsNew();

Deleting Bean Objects

The basics for deleting a bean object is to simply call the delete helper method. The following example assume you have a properly loaded bean to delete.

someBean.delete();

Creating, Updating, & Saving Bean Objects

The basics for saving a bean object is to simply call the save helper method. The following example assumes you have a properly loaded bean to save, and may have made some changes to one or more attributes using one of the setter methods above.

someBean.save();

Error Handling

When saving an entity, if an error occurs, you'll need to figure out how you want to deal with the error(s). Keep in mind, if an error is returned, the save did not occur!

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.

someBean.save();
// If the bean has errors, then it did not save...
if ( someBean.hasErrors() ) {
// errors are returned as a struct
errors = someBean.getErrors();
WriteOutput('<h3>Please review the following errors:</h3><ul>');
  // Loop over the errors
for ( e in errors ) {
WriteOutput('<li>Attribute: #e# <br> Message: #errors[e]#</li>');
  }
  WriteOutput('</ul>');
} else {
WriteOutput('<h2>Success :: No Errors!</h2>');
}