FilterExpression
The FilterExpression object represents the expression that is used to 'find' an item that matches its defined condition. A FilterExpression object contains two fields, an operator and optional a Boolean flag that indicates whether the condition should be evaluated negatively.
Supported Platform(s)
- BlackBerry OS 5.0+
- Ripple Emulator
API | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
---|---|---|---|---|---|
blackberry.find.FilterExpression | Y | Y | Y | Y | |
leftField | Y | Y | Y | Y | |
negate | Y | Y | Y | Y | |
operator | Y | Y | Y | Y | |
rightField | Y | Y | Y | Y |
Configuration Document Settings
To use all of the API described for this object, you must ensure the following settings are in your configuration document:
You must declare the feature element(s) below in your configuration document:
Feature ID | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
---|---|---|---|---|---|
<feature id="blackberry.find" /> | Y | Y | Y | Y |
Permission Elements (PlayBook Only) |
---|
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application. |
API Summary
Constructors
Properties
blackberry.find.FilterExpression
blackberry.find.FilterExpression (leftField : Object, operator : Object, rightField : Object, [negate: Boolean]) |
Supported Platform(s)
- BlackBerry OS 5.0+- Ripple Emulator
Description
The FilterExpression object is an instance object, where if a new instance is desired, it must be created using the new keyword.
Parameter | Type | Description |
---|---|---|
leftField | Object | an object of String or FilterExpression class. |
operator | Object | the operator used for comparing or combining. |
rightField | Object | a value of to be comared or an object of FilterExpression class to be combined. |
negate |
Boolean
Optional |
optional (default value is false), the flag that indicates whether the condition of the FilterExpression object should be evaluated negatively. |
Code Example(s)
<script type="text/javascript"> // Find all appointments with "start" date later than current time var d = new Date(); var fe1 = new blackberry.find.FilterExpression("start", ">", d); var appt = blackberry.pim.Appointment.find(fe1, 10); // Find all contacts with "firstName" lead by "John" var fe2 = new blackberry.find.FilterExpression("firstName", "REGEX", "John[a-zA-Z_0-9 ]*"); var result = blackberry.pim.Contact.find(fe2); for (i = 0; i < result.length; i++) { alert(result[i].firstName); } </script>
<script type="text/javascript"> // Find all contacts except "John Smith" var feFirst = new blackberry.find.FilterExpression("firstName", "==", "John"); var feLast = new blackberry.find.FilterExpression("lastName", "==", "Smith"); // Create a FilterExpression with "feFirst && feLast", with negateExpression set to "true" var feNotJohnSmith = new blackberry.find.FilterExpression(feFirst, "AND", feLast, true); // result contains all contacts except "John Smith" var result = blackberry.pim.Contact.find(feNotJohnSmith ); for (i = 0; i < result.length; i++) { alert(result[i].firstName); } </script>
<script type="text/javascript"> // Create a FilterExpression with "firstName" equals to "John" and "lastName" equals to "Smith" var feFirst = new blackberry.find.FilterExpression("firstName", "==", "John"); var feLast = new blackberry.find.FilterExpression("lastName", "==", "Smith"); var feJohnSmith = new blackberry.find.FilterExpression(feFirst, "AND", feLast); // Create a FilterExpression with "firstName" equals to "Jack" and "lastName" equals to "Brown" var feJackBrown = new blackberry.find.FilterExpression (new blackberry.find.FilterExpression("firstName", "==", "Jack"), "AND", new blackberry.find.FilterExpression("lastName", "==", "Brown")); // FilterExpression can be nested or combined var feCombined = new blackberry.find.FilterExpression(feJohnSmith, "OR", feJackBrown); // Find all contacts either "John Smith" or "Jack Brown" var result = blackberry.pim.Contact.find(feCombined); for (i = 0; i < result.length; i++) { alert(result[i].firstName); } </script>
<script type="text/javascript"> // Create a FilterExpression with "firstName" equals to "John" and "lastName" equals to "Smith" var feFirst = new blackberry.find.FilterExpression("firstName", "==", "John"); var feLast = new blackberry.find.FilterExpression("lastName", "==", "Smith"); var feJohnSmith = new blackberry.find.FilterExpression(feFirst, "AND", feLast); // Find all contacts either "John Smith" or with the firstName of "Jack" var feCombined2 = new blackberry.find.FilterExpression(feJohnSmith, "OR", new blackberry.find.FilterExpression("firstName", "==", "Jack")); var result2 = blackberry.pim.Contact.find(feCombined2); for (i = 0; i < result2.length; i++) { alert(result2[i].firstName); } </script>
<script type="text/javascript"> // Create a FilterExpression with "Business" being one of the categories var fe = new blackberry.find.FilterExpression("categories", "CONTAINS", "Business"); // Find all contacts that belong to the "Business" category var result = blackberry.pim.Contact.find(fe); for (i = 0; i < result.length; i++) { alert(result[i].firstName); } </script>
<script type="text/javascript"> // Create a FilterExpression for uncategorized items var fe = new blackberry.find.FilterExpression("categories", "==", null); // Find all uncategorized tasks var result = blackberry.pim.Task.find(fe); for (i = 0; i < result.length; i++) { alert(result[i].summary); } </script>
Properties:
Property | Type | Description | Supported Platform(s) |
---|---|---|---|
leftField |
Object
readonly |
1. (Either) contains the interested field for "Find."
It supports "." to define the subfield to be matched, for example "homeAddress.zipPostal" for a find towards pim.Contact;
It also supports the JAM predefined fields for the attribute of Date type (using "."),
so the user can "find" towards a Date attribute to match "any appointments that start at 12 o'clock" or
"all reminders that will alarm in Oct" without creating complex expression objects.
For example, for a find towards pim.Appointment, if its "start" attribute is a Date of "Dec. 4, 2008 16:30:00"
2. (Or) contains another FilterExpression object to be combined with "rightField."
|
- BlackBerry OS 5.0+
- Ripple Emulator |
negate |
Boolean
readonly |
The Boolean flag that indicates whether the condition of the FilterExpression object should be evaluated negatively. This should only be used when you have nested expressions. On regular field/value comparisons, negate isn't necessary as the != is sufficient.
|
- BlackBerry OS 5.0+
- Ripple Emulator |
operator |
Object
readonly |
Contains the operator, which is either an integer or a string, used for comparing or combining:
0, "!=" - Not equal 1, "==" - Equal 2, "<" - Less than 4, ">" - Greater than 3, "<=" - Equal | Less than (Less or Equal) 5, ">=" - Equal | Greater than (Greater or Equal) 8, "REGEX" - Regular expression. Please refer to java.lang.String.matches() API for details of how to create the correct regular expression and expected behavior. 16, "AND" - AND 32, "OR" - OR 64, "CONTAINS" - CONTAINS |
- BlackBerry OS 5.0+
- Ripple Emulator |
rightField |
Object
readonly |
1. (Either) contains the value that used for comparing with the field that is specified by "leftField."
2. (Or) contains another FilterExpression object to be combined with "leftField." |
- BlackBerry OS 5.0+
- Ripple Emulator |