FilterExpression

- BlackBerry OS 5.0+
- Ripple Emulator

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

blackberry.find.FilterExpression

---

blackberry.find.FilterExpression (leftField : Object, operator : Object, rightField : Object, [negate: Boolean])

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

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" start.Year - returns a string of 4 digits of the Year value of the date attribute: "2008" start.Month - returns a string of the Month value: "12" start.Day - returns a string of the Date value: "4" start.Hour - returns a string of the Hour value: "16" start.Minute - returns a string of the Minute value: "30" start.Second - returns a string of the Second value: "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

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 13:31:17 GMT-0500 (EST)