< documentation

Plugins

Extension Points

filters 1.0.x

usage

Filters are defined by passing an array of individual filters to the $.filter plugin. Filters are merged so the plugin may be used many times to add filters using the same method. By convention it is recommended that filters be defined in app/configs/filters.js so other developers will know where to look for them, and the entire file be defined within it's own closure.

(function($)&#x7B; 

    $.filters([
        /**
         &#x7B;  individual filter configurations here },
         &#x7B;  and here },
         &#x7B;  and here },
         &#x7B;  etc }
        */
    ])

})(jQuery);

common_options

In general, individual filter configurations support some very powerful regular expression syntax, so you can apply a filter across an entire namespace (called the target), and on any functions of the target that match the given expression (specified by around, before, or after). Each type of filter is defined below:

Name Type
id String
A unique id for the filter across the application
target String
Either the name of a global function, a dot-delimited name of a class (as a string), an application managed object id (prefixed with 'ref://'), or a namespace followed by ".*", which implies the filter will be applied to every object in the namespace. (see example below for illustration)
around|before|after String
Treated as a RegExp, you can apply the filter to multiple methods of the target.

around

Around is type of filter that allows you to intercept a function call before it is made, inspect the arguments, and either allow the function call to continue naturally, or prevent the function being called, perhaps calling another function in its place. You can also then inspect the returned value and either modify it, return it, or return another value entirely.

Name Type
advice Function
The advice is the function that will be called at the interception point. this function will have the argument: 'invocation
invocation.proceed function
You must call invocation.proceed to allow the intercepted function to be called as expected.
invocation.arguments function
is the array of args as presented to the intercepted function
invocation.object function
is a refernece to the object the intercepted function was called on.

In the following example we have a data access object that has a requirement of needing a valid session id in order for ajax calls to happen successfully. we simply intercept the call, establish a session if it has timed out, and proceed with the call as usual

/*
 * @file app/configs/filters.js
 * @description If you need to intercept calls to portions
 *     of you application and modify the behavior based on
 *     state or other conditions, filters are the place to do it
 */
(function($)&#x7B;
    
    var contactModel;

    $.filters([&#x7B;   
 
        id      : "session-filter",
        target  : "MyApp.Models.Contact",
        around  : "(find|save|create|delete)",
        advice  : function(invocation)&#x7B;
            contactModel = contactModel||$.$("#contactModel");
            if(contactModel && contactModel.sessionExpired)&#x7B;
                $.$("#searchController").init(function(session)&#x7B;
                    if(session)&#x7B;
                        invocation.proceed();
                    }else&#x7B;
                alert('session invalid, please login');
                    }
                });
            }else&#x7B;
                alert('session invalid, please login');
            }
        }

    }]);
    
})(jQuery);

before

'before' filters allow you to intercept a collection of function calls and optionally modify the arguments passed to them.

Name Type
before String
Treated as a RegExp, you can apply the filter to multiple methods of the target.

In the following example we are intercepting a call to a particular view rendering and passing some additional information and sorting the name alphabetically.

/*
 * @file app/configs/filters.js
 * @description If you need to intercept calls to portions
 *     of you application and modify the behavior based on
 *     state or other conditions, filters are the place to do it
 */
(function($)&#x7B;
    
    var userModel;

    $.filters([&#x7B;   
 
        id      : "user-decoration-filter",
        target  : "MyApp.Views.Contacts",
        before  : "(update)",
        advice  : function()&#x7B;
            userModel = userModel||$.$("#userModel");
            userModel.sort(arguments[0], arguments[0].sortMode);
            $.extend(true, arguments[0], &#x7B;
                lastAdded:userModel.lastAdded
            });
        }    

    }]);
    
})(jQuery);

after

After filters allow you to intercept the return value of a set of functions and either modify them or just use them to trigger additional events etc.

Name Type
after String
Treated as a RegExp, you can apply the filter to multiple methods of the target.

In the following example we are intercepting a the return value of a network call that indicates if the submission is successful. Based on the return value we trigger additional events.

/*
 * @file app/configs/filters.js
 * @description If you need to intercept calls to portions
 *     of you application and modify the behavior based on
 *     state or other conditions, filters are the place to do it
 */
(function($)&#x7B;

    $.filters([&#x7B;   
 
        id      : "status-filter",
        target  : "MyApp.Models.Search",
        after   : "(submit)",
        advice  : function(retval)&#x7B;
            if(retval > 0)&#x7B;
                $(document).trigger('searching');
            }else&#x7B;
                $(document).trigger('network-unavailable');
            }
        }    

    }]);
    
})(jQuery);
filters releases

Project

Guides

This guide is applicable to both the jquery-claypool client and server application frameworks. Where the two differ functionally the documentation will provide notes and examples of usage in each environment.