Enjoy!

Easy enough. With one little line of code, you can very simply convert ORM entities to a ColdFusion query…just like so:

// get the orm entities
ormstuff = EntityLoad( "Art" );
// convert the orm goodness to a CF query
anicequery = EntityToQuery( ormstuff );

Cake, right? If I were to hand this query off to CF’s spreadsheet functions, I could easily prepare and export a nice Excel file full of the data I just converted. But of course, nothing is that simple…and that’s where the potential bug announced itself.

A Dark Foreboding

You see, instead of simply dumping all the data for all the columns of the query-which-was-once-an-entity, I wanted to pare down the list of columns that would be output in the Excel export. Since I already had a query handy, I figured passing a list of column names to a Query-of-Queries would make short work of this. However, the moment I tried this…

BOOM!

I received the following error:

Query Of Queries runtime error. Unsupported SQL type java.sql.Types.UNKNOWN

The Weirdness Begins

So what happened? Turns out that one of my columns (a BIT column on the database) was being converted to an “UNKNOWN” data type in the query result. You can see this easily by viewing the metadata of the query object (notice the “ISSOLD” column):

writedump( getMetaData( anicequery ) );

The Weirdness Grows

As strange as this is, it gets weirder.

• If I do a non-entity query of the database and the dump the result, the data type for “ISSOLD” is not UNKNOWN, but the correct data type.
• If I pass a “*” in the Q-of-Q instead of a list containing the offending column’s name, no error occurs
• CAST() the column, you say? Yep, tried that. No dice.
• Changing the “type” and “ormtype” attributes of the BIT column’s properties in the ORM mapping don’t help. I tried a number of combinations, but could not get the “TypeName” to ever NOT be “UNKNOWN”
• Ok, that’s not 100% true. if I leave those attributes off, the TypeName is set to “JAVA_OBJECT”, and the QofQ is able to execute without error. Of course, this is only for MySQL…in SQL Server, I couldn’t get it to change, even with the same settings as what “worked” for MySQL. Ugh.

The Weirdness Ends

After several unfruitful experiments and dozens of minutes Googling to no avail, I put an end to the madness by simply writing my own version of EntitytoQuery(). It’s ugly and still a work in progress, but it at least by-passes the issue I encountered.

If you’re interested in seeing this issue in action, check out the demo pages I put up (each page has a dump of the code for the entities):

• SQL Server 2008
• MySQL

I’ve also submitted a bug for this, so if you think it’s crazy, feel free to vote!

Some Context

Let’s say that you have two entities that are related via a one-to-many relationship (Artists and Art, for example). You can easily create this relationship in your model by doing something like the following:

property name="art" fieldtype="one-to-many" fkcolumn="artistid" cfc="Art" remotingfetch="true";

If we were to dump the result of an EntityLoad() of “Artists”, we’d see a nice structured relationship: First, an array of all Artist entities, and then an array of all Art entities related to the particular ArtistID. Additionally, I’ve specified remotingfetch=true, which will force CF to load the Art entities for each Artist.

The Bug

The bug, however, comes into play when you try to serialize the result of EntityLoad(). While it properly composes the relationships, it represents the first two entities in the “art” array; any subsequent entities in the given array are returned simply as “{}”.  Whether you have 3 “Art” entities for an artists, or 20, only the first 2 will ever be serialized properly.

See this happening in CF10:

• Regular, correct composition of entities via straight CFDUMP – LINK
• “First two” problem via dump of serializeJSON() – LINK

It Gets Worse

The worst part about this is that it is a relatively old bug. It was first submitted for CF9 back in October 2010, was deferred, and was apparently not fixed for the public beta of CF10.

I think this is a huge issue, and should be a priority to be fixed. Until it is (or a suitable workaround is devised), it will be incredibly difficult to create applications of any complexity that depend upon serialization of entities.

Vote, Vote, Vote

The best way to get it fixed, of course, is to make your voice heard and vote up the bug. Here are some links for that:

Bug Report – CF 9: https://bugbase.adobe.com/index.cfm?event=bug&id=3042650

Bug Report – CF 10: https://bugbase.adobe.com/index.cfm?event=bug&id=3175667

Ext.define('Validations.model.Person', {
    extend: 'Ext.data.Model',
    fields: [
        {name:"name", type:'string'},
        {name:"age", type:"int"},
        {name:"hobby", type:"string"}
    ]
})

Also, assume we have a form defined like so:

Ext.define('Validations.view.people.Form', {
    extend: 'Ext.form.Panel',
    alias: 'widget.peopleform',
    bodyPadding: 10,
    border: false,
    initComponent: function() {
        var me = this;
        Ext.applyIf(me, {
            defaults: {
                width: 250,
                labelWidth: 70
            },
            items: [
                {
                    xtype: 'textfield',
                    name: 'name',
                    id: 'name',
                    fieldLabel: 'Name'
                },
                {
                    xtype: 'numberfield',
                    name: 'age',
                    id: 'age',
                    fieldLabel: 'Age',
                    value: 20
                },
                {
                    xtype: 'textfield',
                    name: 'hobby',
                    id: 'hobby',
                    fieldLabel: 'Hobby'
                }
            ]
        });
        me.callParent(arguments);
    }
})

NOTE: Notice that the “name” properties of each form field maps 1:1 with the “name” properties in my Model.

Now, let’s say that we want to edit a Model instance. We could, of course, manually set the value of each form field to that of the corresponding field in the Model. However, this is clunky and unnecessary, given that the form itself has a method for doing this automatically. Consider the following:

// get first model instance in store
 myrecord = somestore.getAt(0)
 // load form with data from selected model instance
 myform.loadRecord(myrecord)

Pretty simple, right? When calling the loadRecord() method on the form, any field in the form whose name value matches the name definition in the specified Model will be loaded with the data of that particular field.

Try it out. Open the demo, and double-click on any record in the grid. On the itemdblclick event of the grid, the form’s loadRecord() method is invoked, and the Model data corresponding to the clicked row in the grid is applied to the form’s fields

Validation, Validation, Validation

So that’s pretty easy. But of course, when dealing with data–whether on the Model or in a form–you’re going to want to validate it to make sure that you have the data you’re expecting, and that the data is in the right format.

In ExtJS, there are a few different ways you can validate Model data.

First, you can apply validations directly to the model itself. For example, let’s add in a few to the Model already setup:

Ext.define('Validations.model.Person', {
    extend: 'Ext.data.Model',
    fields: [
        {name:"name", type:'string'},
        {name:"age", type:"int"},
        {name:"hobby", type:"string"}
    ],
    ,
    validations: [
        {type: 'presence', field: 'name', message: 'You have to enter a name, silly'},
        {type: 'presence', field: 'age', message: 'You must specify an age'},
        {type: 'presence', field: 'hobby', message: 'You must enter a hobby'},
        {type: 'length', field: 'hobby', min:5, message: 'You must specify a hobby with more than 4 characters'}
    ]
})

In this example, I’ve applied a “presence” validation to each field, which requires that each field has a value, as well as a “length” validation to the “hobby” field. When calling the Model’s validate() method, the instance’s current data will be run through the validations.

The second, albeit indirect, way to validate the Model is to apply validations to the form fields themselves, such as defining properties like allowBlank (e.g., “presence”), specifying a custom vType for the field, using a regex, etc.

While both of these approaches are great, they are not particularly related. For example, if we have NO validations whatsoever on the form, we could submit perfectly valid Form data, but this data may yet trigger validations when the Model is validated. By default, the form doesn’t care about the Model-level validations, and will only trigger Form-level validations that have been defined.

Applying Model Validation to Form Fields

While this disconnect is certainly understandable, I thought it would be cool if both validations could be supported when the form is being validated. Here’s a short list of my requirements:

• Model validations should be enforced at a field by field level (e.g., if there are two validations for “name”, these should both be enforced on the “name” field in the form)
• Both Model and Form field validations should be respected
• Both Model and Form field validations should be communicated to the user

So how to do this? While there are probably a dozen ways to accomplish this goal, the approach I took was to simply override Ext.form.Basic and Ext.form.field.Base.

The first step is to make the form aware of Model validations. Since we really only care about this when the Model data is loaded to the form via loadRecord(), we can start by overriding this method like so:

Ext.override(Ext.form.Basic, {
    loadRecord: function(record) {
        this._record = record;
        this.setModelValidations(record.validations);
        return this.setValues(record.data);
    },
    setModelValidations: function(validations) {
        var fields = this.getFields(), i;
        for(i=0;i<validations.length;i++) {
            if(fields.map[validations[i].field]) {
                fields.map[validations[i].field].setModelFieldValidation(validations[i])
            }
        }
    }
})

When loadRecord() is invoked, we pass the record to a new custom method, setModelValidations(). This custom method will iterate over the validations object of the specified Model, and will invoke the setModelFieldValidation() method of any form field it finds whose mapping matches that of the Model validation.

The next override is on the base definition for form fields, and looks like so:

Ext.override(Ext.form.field.Base, {
    setModelFieldValidation: function(validation) {
        this.modelValidations = Ext.isArray(this.modelValidations) ? this.modelValidations : [];
        this.modelValidations.push(validation);
    },
    getModelErrors: function(value) {
        var errors      = Ext.create('Ext.data.Errors'),
            validations = this.modelValidations,
            validators  = Ext.data.validations,
            length, validation, field, valid, type, i;

        if (validations) {
            length = validations.length;

            for (i = 0; i < length; i++) {
                validation = validations[i];
                field = validation.field || validation.name;
                type  = validation.type;
                valid = validators[type](validation, value);

                if (!valid) {
                    errors.add({
                        field  : field,
                        message: validation.message || validators[type + 'Message']
                    });
                }
            }
        }
        return errors;
    },
    validateValue: function(value) {
        var me = this,
            errors = me.getErrors(value),
            modelErrors = me.getModelErrors(value),
            isValid = Ext.isEmpty(errors) && modelErrors.isValid();
        if (!me.preventMark) {
            if (isValid) {
                me.clearInvalid();
            }
            else {
                if(!modelErrors.isValid()) { modelErrors.each(function() { errors.push(this.message); }) }
                me.markInvalid(errors);
            }
        }
        return isValid;
    }
})

There’s a lot going on here, so let’s go method by method.

setModelFieldValidation(): This is method that is called from the Form’s setModelValidations() method, and it simply adds a new property to the instance of the form field (modelValidations). This modelValidations is an array which will store any Model-level validations which have been configured for the Model field which matches this form field’s “name”.

getModelErrors(): This method is almost identical to the Model’s getErrors() method. The primary difference is that instead of iterating over every validation defined for the Model, this method only iterates over the Model validations which have been assigned to this form field (via setModelFieldValidations()).

validateValue(): This is an override of the field’s existing validateValue() method, which is invoked everything a validation occurs. The only additions are to add the Model validation to the check for whether the form “isValid”, as well as a short section to append the model validation error messages to the main “errors” array (which is ultimately used for communicating the form’s validation errors to the user).

Demo and Source

If you’d like to see this in action, check out the demo. If you’d like to see the full source for this mini-app, grab it from GitHub.

Wrapping Up

In all honesty, I’m not sure how practical this approach actually is, or whether you’d actually want to forge this relationship between the form and model validations. But regardless of the practicality, I think it does, at the very least, demonstrate precisely how stupid simple it is to extend ExtJS to do pretty much whatever you want it to do. And notwithstanding the usefulness of this particular example, this extensibility is precisely why I love this framework.

When I saw the news about the release, I have to say I was a bit hesitant to look much further. I’ve tried Sencha Designer several times in the past, and I’ve been somewhat disappointed with it. Sure, it was great for laying out apps, but when you actually needed to *code*, it was lackluster at best. But even worse, I found it to be very buggy; it would crash at random times, and overall I found the process of trying to mockup an app to be more frustrating than anything else.

So initially, I wasn’t planning on even trying out the newest iteration. But then I noticed that one of the biggest additions to the product is  support for creating a full ExtJS or Touch app–not just the UI. I felt I had to take a closer look, and I’m glad I did.

UI

Out of the box, Architect 2 is worlds better than its previous iterations. The interface is slick and responsive, and the way the UI is organized makes the process of laying out and configuring components feel much more intuitive. One especially nice feature is that in the “Property” panel, you can toggle between commonly used configurations and the comprehensive list. Additionally, the configuration options are nicely grouped by inheritance, so you know precisely where your configs are being applied.

Application Flow

The coolest part of Architect 2 (to me) is that you can now *really* build applications with it. If you drink the MVC architecture Kool-Aid (and you should!), Architect 2 makes it very simple to build full-on applications.

For example, you can very simply choose to add controllers to your app. Within the controllers, you can customize handlers and custom methods to take care of the all of the business logic of your application.

Best Practices

But perhaps the best part of Architect 2 is that in the course of adding components, wiring up event handlers, and just fleshing out your app, you can instantly switch to “Code” view to see how the entire app is getting constructed behind the scenes. This gives a much welcome insight into “best practices” for developing ExtJS and Touch apps within the MVC architecture–a much desired feature that many devs have been begging for for quite a while.

I was happy to see that my methodology that was about 95% on point; however, the differences that I’ve noticed while reviewing the code have filled in some gaps in my understanding, which will simply make building ExtJS and Touch apps that much more fun

So…Will I Buy It?

At $399, the price tag for Sencha Architect 2 initially feels a little steep. Personally, I would not have paid that much for previous versions, purely based on my lackluster experiences during the trials. However, given how much more solid Architect 2 feels, and based on the fact that it is now geared toward full soup-to-nuts app development, I’ll have to seriously consider it.

Sure, I can do a fair amount of things in PHP…you know, querying databases, echoing content, that kind of stuff. Where I really get hurt, though, is when things start to get complex.

NOTE: If you don’t particularly feel like reading and just want to see some code, be sure to check out my GitHub repo for this.

Some Context

For example, I recently needed to build out an ExtJS View, and I wanted to have some pretty heavily-nested data. My ideal outcome would print something to the page like so:

Main Group 1
   Category 1
      Name 1
      Name 2
         Fav Color 1
         Fav Color 2
Main Group 2
   Category 1
      Name 1
      Name 2
Main Group 3
   Category 2
      Name 1
   Category 3
      Name 1

And so on. In other words, each step in the “tree” can have multiple children, which can themselves have multiple children, ad infinitum.

Now in ExtJS, creating a View is dead simple. You simply have to pass the View a JSON structure wherein each level is an array of objects. My problem, however, was not with the ExtJS side. Rather, it was turning a MySQL query result set into a structure that could be serialized into the proper format and sent off to ExtJS.

An Initial Attempt

Unfortunately, there is nothing in PHP like ColdFusion’s amazing “group” attribute in the <cfoutput> tag. So not knowing what to do, I headed out to The Google, and asked it to tell me about “creating nested json” and “nested data” and the like. For the most part, the answers I found suggested doing something like this:

• Set a “flag” for the group (this will be updated when you move to a different group)
• Loop over record set. When you reach a new “group” (e.g., group value != flag), reset the group flag, create a new array for the group data, nest child data, etc.

While this approach certainly works (I used it in my first several *attempts*), it gets hairy really quickly. Sure, it’s not a huge deal when you have a simple “group” -> “item” relationship. However, when you have to start nesting data in more complex fashions, it becomes incredibly unwieldy. Not only is it unsustainable as you have to replicate the functionality for EVERY change in data, but it’s also a nightmare because there are only so many “flags” and “nested flags” that the human brain can keep track of at a single time.

A Better Approach…But Still Not Great

I quickly abandoned this process. it was a headache to write, and the thought of having to do it N times for each query was maddening. So I stepped back a bit, and tried to think a bit more critically about my approach. One big problem, in my estimation, is that I was getting tripped up by the conversion from the flat result set from MySQL to the nested-array model I needed. The flags became a mess really quickly, because they were each trying to keep track of their place within the whole data set, instead of a “parent” only being concerned about whatever children it might have.

With this in mind, my second approach took the form of trying to iteratively reduce the data being dealt with at any particular “level” of the process. My first step was to create a quick function to transform the result set from MySQL into a super-dumb array.

function convertquerytoarray($query) {
   while($row = mysql_fetch_assoc($query)) {
      $rows[] = $row;
   }
   return $rows;
}

With this done, I proceeded to leverage PHP’s foreach() to loop over each record:

$gidx = '';
$groups = array();
$allrows = convertquerytoarray($sqlresult);
foreach($allrows as $row) {
   if($row['group'] != $gidx) {
      $carr = filterarraybykey($allrows,'group',$row['group']);
      ...
   }
}

Now you’ll notice that in the midst of the “group” foreach() loop, I create a new array ($carr) and assign to it the value returned from the filterarraybykey() method. Here’s what that looks like:

function filterarraybykey($array,$key,$val) {
   return array_filter($array,function($row) use($key,$val) {
      return $val==$row[$key];
   });
}

As I mentioned, the idea here is that for each “parent”, evaluating the children (and children’s children) would seem to be much easier if we limit down the data being evaluated within that relationship to only that data which is contained within the relationship.

So, let’s say that we have 3 groups: “Cats, Dogs, Hamsters”. When the “Cats” group is being evaluated, the filterarraybykey() method will take the full result set ($allrows), and return an array that has only the values that have a “group” value of “Cats”…maybe 5 records instead of the whole 20 of the full result set.

Now that I’ve limited the result set, I can continue the pattern farther down, applying the same technique to “categories” and “names”:

$gidx = '';
$groups = array();
$allrows = convertquerytoarray($sqlresult);
foreach($allrows as $row) {
   if($row['group'] != $gidx) {
      $carr = filterarraybykey($allrows,'group',$row['group']);
      $cidx = '';
      $categories = array();
      foreach($carr as $row) {
         if($row['category'] != $cidx) {
            $narr = filterarraybykey($carr,'category',$row['category']);
            $nidx = '';
            $names = array();
            foreach($narr as $row) {
               if($row['name'] != $nidx) {
                  $name = array('name'=>row['name'];
                  array_push($names,$name);
                  $nidx = $row['name'];
               }
            }
            $category = array('category'=>$row['category'],'names'=>$names);
            array_push($categories,$category);
            $cidx = $row['category'];
          }
      };
      $group = array('group'=>$row['group'],'categories'=>$categories);
      array_push($groups,$group);
      $idx = $row['group'];
   }
}

Alright, this feels a little better. Even though it still has a bunch of “flags,” the logic is pretty easy to follow. Since the result set being evaluated at each “level” of the nesting is constantly getting whittled, it eases the burden of trying to figure out where the particular record exists within the WHOLE data set. In this approach, you only have to worry about the current parent and siblings. Plus, since we have nested foreach() loops, each “level” is more or less self-contained.

Although this is a bit better, it still suffers from many of the same issues as the first. Namely, every time this needs to be changed, or every time I need something like this elsewhere (perhaps a grouping of only groups and names, with no categories), I have to recreate this nesting nightmare. If at any point along the way my flags or row pointers get off (via typo, omission, etc.), things will break, and frustration will ensue.

A Final (Hopefully Better) Solution

So while the last approach is still kind of kludgy, I think it’s moving in the right direction. Since each “level” of nesting represents a thin, relationally isolated slice of the total data set, it’s easier to drop things in and out of it to get the results you want. Therefore, with this as a basis, my last shot at a solution was an attempt to abstract the philosophy of this approach. I’ll paste the whole example, and then explain what’s going on:

function makenestedarray($array,$model) {
   // check if array is a mysql result; if so, convert it to a flat array
   $array = gettype($array)=='resource' ? convertquerytoarray($array) : $array;
   // set blank index for tracking which rows we've already added
   $idx = '';
   // blank array to store all the data
   $master = array();
   // retrieve value of "key" for the current iteratin of the data model
   $key = $model['key'];
   // loop over each row in the passed data array
   foreach($array as $row) {
      // if the value is not equal to the index value, evaluate row
      if($row[$key] != $idx) {
         // retrieve data for row based on model definition
         $item = makerowdata($row,$model);
         // if current level has "children" defined, evaluate each child
         if(isset($model['children'])) {
            // loop over array of children
            foreach($model['children'] as $child=>$val) {
            // whittle it down based on the child's data key
               $childarr = filterarraybykey($array,$key,$row[$key]);
               // recursively call makenestedarray()
               $children = makenestedarray($childarr,$val);
               // add nested data to parent array
               $item[$child]=$children;
            }
         }
         // done with all the looping; add current data item to master array
         array_push($master,$item);
         // update the index and kip rows if they have the same index
         $idx = $row[$key];
      }
   }
   // yay! all finished; return the completed data object
   return $master;
}

function makerowdata($row,$struct) {
   $columns = array();
   $keys = array_keys($struct);
   foreach($keys as $pos=>$key) {
      if($key != 'key' && $key != 'children') {
         $columns[$struct[$key]] = $row[$key];
      }
   }
   return $columns;
}

$model = array(
   'key'=>'group',
   'group'=>'group',
   'groupid'=>'id',
   'children'=>array(
      'categories'=>array(
      'key'=>'category',
      'category'=>'category',
      'children'=>array(
         'names'=>array(
            'key'=>'names',
            'nameid'=>'id',
            'name'=>'name'
         )
      )
   )
);
$data = makenestedarray($sqlresult,$model);
$returnjson = array("groups" => $data);
// serialize this mug, and return the string
return json_encode($returnjson);

My solution involves creating a recursive method to do what the last approach did–whittle down the data set being evaluated as the “level” increases. The big difference, of course, is that the recursive method couldn’t care less what the data being thrown at it is, and doesn’t particularly care how many levels of nesting there might be.

And this is what I like about this approach. Instead of manually looping and nesting data, all I have to do is define a “model” of the data in the form I’d like it be prepared, and the recursive makenestedarray() will do the rest.

This has a couple big benefits.

First, if I need to create various nested data arrays for ExtJS of different configurations (and I definitely do), I no longer have to worry about the headache of creating the nested nightmares of the first two “solutions.” I simply plot out exactly the data model that I want to return, and the method takes care of it for me.

And second, the “model” provides a nice visual verification of how the data I’m preparing is going to look when it’s returned as JSON. And if I need to make a quick tweak (like adding an additional data column to be returned at some level within this structure), it’s easy to add as I only need to update the model, and not the mechanism creating the ultimate output.

Wrapping Up

So what are your thoughts? This is the result of a lot of pain, headaches, and trial and error. Since I’m a total PHP noob, I acknowledge that it’s entirely possible (if not probable) that there are much cleaner, easier, and elegant solutions to this seemingly routine need. However, I wanted to write this up, if for nothing else than for my own benefit of reminiscing about the process I went through to get from absolute frustration to a sustainable solution that I feel pretty happy about.

Anyway, with that in place, I’ve uploaded my examples of ArrayEach(), StructEach(), and ArrayFilter(). I’ve also put them out on GitHub, so feel free to take a look if it suits you.

Enjoy!

Like ArrayEach() and StructEach(), the new filter methods have a “function” parameter (which can also be either an inline function or a named function). However, unlike ArrayEach() and StructEach() which return nothing, the new filter functions return a new array, list, or struct, respectively.

To accomplish this, you need to return a boolean from the function parameter. If the current array element, list item, or structure value matches some criteria and returns “true”, it will be added to the new returned array/list/structure. Conversely, if it fails the criteria and returns “false,” it will be excluded from what is returned.

NOTE:  The array/list/struct filter() functions return NEW arrays/lists/structures. The original arrays/lists/structs against which the filter() functions are called are unaffected.

An Example

Let’s say that we have a simple set of “circles” for a Google+ account which includes a circle for friends, one for co-workers, and another for family. We might model this data like so:

'circles' = {
    'friends': ['Lucas','Phil','Dave','Brian','Dillon'],
    'coworkers': ['Tyler','Mike','Doug'],
    'family': ['Dean','Jared','Jason']
};

Now, let’s imagine that for some reason, we want to filter all of the people in our circles, and return all the contacts (regardless of circle) whose names start with the letter “D”.  One approach might be as so:

// create an array to hold all the names
allDnames = [];
// use structeach() to evaluate each "circle" 
structeach(circles,function(key,value) {
     // "matched" names will be the new array returned from the arrayfilter()
     // which is applied to each circle in the structeach() loop
     matchednames = arrayfilter(value,function(obj) {
         // if the first letter is a "D", return true; otherwise, return false;
         return left(obj,1)=='D';
     });
     // now let's add each filtered name to our master array of "D" names 
     arrayeach(matchednames,function(obj) {
          arrayappend(allDnames,obj);
     });
});

See the live example or grab the code from GitHub

Wrapping Up

As you can see, using CF10′s new ArrayFilter() function is pretty simple, and the ListFilter() and StructFilter() functions work exactly the same, just with slightly different parameters and return types.

But perhaps more importantly, this example shows how functions like StructEach() and ArrayFilter() can make processing of complex data structures a snap. Instead of bothering with messy for-loops in which it would be incredibly easy to lose our place, this approach feels much more sane and easy to follow.

NOTE: The ArrayEach() and StructEach() functions act on the original array/struct. Therefore, if you make changes to the array/struct within these functions (as in the ArrayEach() example below), the original array/struct will be affected (thanks Andy!).

ArrayEach()

So, for example, let’s say you have an array of friends’ names, and you want to make the list all uppercase. Pre-CF10, you might approach this by looping over the array, and executing a function at each iteration. Fine, easy enough, and it works. However, with ArrayEach(), you can ditch the clunkiness of the for-loop, and keep everything self-contained to the array. And, you can execute either an “inline” function, or call a named function. The two examples (which produce the same results) are below:

names = ['John','mary','JOseph','Glenda','Mike'];

// named function
// notice that the function takes one argument, the value of the current iteration of the array
function makeLowercase(obj) {
    names[arrayfind(names,obj)] = lcase(obj);
}

//  run arrayeach() with an inline function
arrayeach(names,function(obj) {
    names[arrayfind(names,obj)] = lcase(obj);
});
writedump(names);

// run arrayeach() with a named function
arrayeach(myarray,makeLowercase);
writedump(myarray);

See the live example or grab the code from GitHub

StructEach()

Not to be outdone, structures get some each() lovin’ in CF10 as well. But instead of iterating over an array, the StructEach() function executes for every key-value pair in the structure. As with ArrayEach(), you can use either use an inline function or a named function.

In this example, we have a simple collection of “favorites,” which we want to print to the screen.

favs = {color: 'blue', food: 'pizza', sport: 'basketball'};

// named function
// notice that the function takes two arguments, the key and value pair of the current iteration of the structure's key-value pairs
function getFavorites(key, value) {
    writeoutput('My favorite ' & key & ' is ' & value);
} 
// run structeach() with a named function
structeach(favs,getFavorites);
// run structeach() with an inline function
structeach(favs, function(key,value) { 
    writeoutput('My favorite ' & key & ' is ' & value);
});

See the live example or grab the code from GitHub

Wrapping Up

While these two functions probably won’t garner the attention that other additions will, I think they’re pretty dang awesome. Not only are they a long time coming (honestly, how often do you loop over an array…like 20 times every hour!!), but they help to make developing with these basic data types just a bit easier as they more closely align methodologies in CF with those you’d find elsewhere.

At some point, however, you’ll need to retrieve data from your Store in a query-like manner. That is, instead of looking up a record by a known ID or position within the store, you may need to find one or more records based on a search term, a category, or whatever else is required by your app.

Of course, as with everything else, ExtJS makes this pretty simple. Let’s suppose that we have the following Model:

Ext.define("MyApp.model.Bookmark", {
     extend: "Ext.data.Model",
     idProperty: "id",
     fields: [
         {name: "id", type: "int"},
         {name: "target", type: "string"},
         {name: "title", type: "string"},
         {name: "category", type: "string"},
         {name: "created", type: "date"}
     ]
});

Nothing to crazy here. Just a simple model with some standard kinds of fields for storing data, in this case, “bookmarks.” Now, let’s define our data store:

Ext.define("MyApp.store.Bookmarks", {
    extend: "Ext.data.Store",
    model: "MyApp.model.Bookmark",
    autoLoad: true,
    storeId: 'bookmarks',
    proxy: {
        type: 'localstorage',
        id  : 'myapp-bookmarks'
    }
});

As with the model, this is very straightforward. We’ve configured a simple store which happens to have a localStorage proxy (change it if you want–ExtJS doesn’t care!).

Simple Data Lookup

Ok, so now that we’re up and running with our model and store, let’s pretend we’ve created a simple app to save bookmarks into our data store. As we’re plugging along, we find that we need to put some kind of tollgate in place to prevent the same bookmark from being entered over and over: after all, having one bookmark to Charlie the Unicorn 2 is certainly enough!

How can we prevent this? In our addBookmark() method, we can do a simple lookup on our data store to see if a bookmark with the same title already exists. This might look something like so:

function addBookmark(target,title,category) {
    var store = Ext.data.StoreManager.lookup('bookmarks');
    var match = store.find('title','title');
    if(match == -1) {
        ...add the bookmark
    }
}

In this simple example, we use the store’s find() method to search through the store’s records. The find() method takes two required arguments–the column to search, and the value to be used in the search–but has more flexibility for case-sensitivity, partial matches, etc. Based on whether the index of a record in our store is returned, we decide whether or not to add the new data to our store.

Of course, if we don’t care about the index of the record and simply want to get a matched record, we could use findRecord() instead. It functions in the same way, but returns a model instance instead of a record index.

More Complex Data Lookup

The store’s find() and findRecord() methods are great if you only need to find matches based on a single data column. What if you need to match on more than one column, though? For example, let’s say that we want to be able to store bookmarks with the same title as long as they belong to a different category. Obviously, our previous method will not work, since the method will prevent insertions of records with already-existent titles. Nope, we need something a bit more robust. Thankfully, ExtJS data stores have just the ticket: findBy().

The findBy() method’s power lies in the fact that you can specify a custom function that will be executed against every record in the data store. Within this custom function, you can do any manner of checks on the entire data record (not just the value of one column). If the conditions you specify succeed, the method will return the index of the first matching record.

So here’s what that might look like for our scenario of checking for the uniqueness of both bookmark title AND category:

function addBookmark(target,title,category) {
    var store = Ext.data.StoreManager.lookup('bookmarks');
    // custom function for finding record with complex criteria
    var match = store.findBy(function(record,id) {
        if(record.get('target')==target && record.get('category')==category) {
            return true;
        }
    });
    if(match == -1) {
        ...add the bookmark
    }
}

As you can see, the custom function is passed two arguments: the model instance of the currently-evaluated record, and the id of the record. Since we want to check to make sure that the combination of bookmark title and bookmark category are unique, we can simply check the “title” and “category” values of the would-be-bookmark against each model in our data store. If no match is found, we know the record is unique and we can add it to the data store. Magical

Wrapping Up

Obviously, the example provided above is very simple; however, I hope it shows just how easy it is to not only query data from a data store, but moreover to create custom functions to apply more complex query logic to the data in your stores.