Whitebeam Template Reference Documentation

Site Map
 
Home
 
Application Guide
Reference
  Installation
  Configuration
  XML Markup
  JavaScript Classes
  ROM
  Templates
  Environment
  Dev Process
  Tools
  External Links
  Example libraries
Community
Contact Whitebeam
To-Do
Download
Credits
Licence
Whitebeam Users
 
 
 

Whitebeam Template Reference Documentation

rb.contact.searchFlags

Flags controlling contact search operations

Elements

The rb.contact.searchFlags struct has 40 elements:

Name Type/Value Range/Length Description
rootIDnumberinteger Optional, default = 0
0, meaning search the whole contacts tree, or a valid OU ID, meaning search only for entities under that OU or in that community
minIDnumber  Optional, default = 0
If specified the template will not return any contact records with an ID less that this specified value. Use this field if you need to walk a large contact list split over a number of requests and do not want to read the same contact more than once (can happen if an earlier record is removed between requests).

Available from version : 1.3.4

minTimedateJavaScript Date object Optional. If this is specified then only return records with a modifiedTime greater than or equal to this time.

Available from version : 1.3.12

maxTimedateJavaScript Date object Optional. If this is specified then only return records with a modifiedTime less than or equal to this time.

Available from version : 1.3.12

minDateTimedateJavaScript Date object Optional. If this is specified then only return records with a dateTime greater than or equal to this time.

Available from version : 1.3.28

maxDateTimedateJavaScript Date object Optional. If this is specified then only return records with a dateTime less than or equal to this time.

Available from version : 1.3.28

allLevelsbool0,1 Optional, default = 1
0: Search only among immediate children of rootID 1: search whole tree below rootID
searchDescriptionbool0,1 Optional, default = 0
If 1, search within Description field
searchOUbool0,1 Optional, default = 0
If 1, return any matching OUs found
searchIndividualbool0,1 Optional, default = 1
If 1, return any matching individuals found
searchCommunitybool0,1 Optional, default = 0
If 1, search for any matching communities. Note that rootID and allLevels are ignored for the purposes of finding communities
searchNamebool0,1 Optional, default = 1
If 1, search for the keyword within the Name field
searchuNamebool0,1 Optional, default = 0
If 1, return any matching uNames found
searchPhonebool0,1 Optional, default = 0
If 1, return any matching phone numbers found
searchFaxbool0,1 Optional, default = 0
If 1, return any matching fax numbers found
searchEmailbool0,1 Optional, default = 0
If 1, search for any matching Email addresses
searchCustombool0,1 Optional, default = 0
If 1, search for the keyword within the Name field
searchParentNamebool0,1 Optional, default = 0
If 1, search the parent name for a record. Setting this field to 1 automatically adds '8' to the allData field to return the parent name.
searchParentDescriptionbool0,1 Optional, default = 0
If 1, search the description field of any parent OU record.
searchKeywordsbool0,1 Optional, default = 0
If 1, search for the keywords within the 'keywords' field
searchMethodstring"and" | "or" | "nand" | "nor" | rank | distance Optional, default = or

Determines how the template should use multiple entries in the keyword array. By default records will only be returned *if* they contain all of the keywords in the list. The alternatives are:

and Records must contain ALL of the keywords.
or Records must contain at least one of te keywords
nand Records that do *not* contain all of the keywords
nor Records that contain none of the keywords
rank Search *and* sort based on keyword ranking function. This overrides the 'sort' attribute.
distance†

Restrict search to a [location,radius] pair. If not specified then [long,lat] of [0,0] is used and a radius of 10 miles.

Only available since releaes 1.3.4

exactMatchnumber0,4 Optional, default = 0

The default value (0) will perform a case-insensitive search for substrings within a SQL string, so example, searching for 'fred' will match 'Fred Bloggs' and 'FRED'. The other values work as follows:

  • 1: Case insensitive but matching whole string. 'Fred' will match 'FRED' but not 'FRED BLOGGS'. '%' and '_' SQL wild-card characters are allowed so '%fred%' will is the equivalent to using 'fred' with exactMatch:0
  • 2: Case sensitive of whole string. 'Fred' will match 'Fred' but not 'Fred Bloggs'. '%' and '_' wild cards are allowed as with 1 and 2.
  • 3: Case sensitive match of the whole string but using the expanded SQL 'SIMILAR TO' regular expression syntax so in addition to '%' and '|' subexpressions are allowed, '|' for alternative forms, '*', '+' and '?' for optional/repetition. Refer to the PostgreSQL documentation for a full description of the syntax.
  • 4: An exact match - testing for equivalence. The string contains no special characeters, no wild cards and must match the entire string.

Values 2, 3 and 4 are only available in Whitebeam 1.3.29 onwards.

hasNodeIDnumber-1, positive integer Optional, default = -1
If >= 1, return only those records that have been linked to this Catalogue Node ID
hasNodeFromListarray of numbers  Optional. A list of catalogue nodeIDs. A contact must have at least one of these to pass this test
hasContactIDFromListarray of numbers  Optional. A list of CONTACT IDs. Only return contacts that are in this list. This is a way of constraining returned contacts to a test set of values. One common use of this is when validating contact IDs returned from forms. isIn could be used to achieve the same ends but that requires interrogating the contact_att table, which isn't necessary when you know the explicit contacts you're requesting. Also use this to load a contact with a specific contact ID.

Available from version : 1.3.4

hasItemIDnumber-1, positive integer Optional, default = -1
If >= 1, return only those records that have been linked to this Catalogue Item ID
hasItemFromListarray of numbers  Optional. List of catalogue itemIDs. A contact must have at least one of these to pass this test
isInarray of numbers0-20 valid IDs Optional. If this array exists and is populated, then only contacts which are within any of the specified Communities, IDs or Individuals are returned
inAllbooltrue | false Optional, default = 0
If set and true, then returned contacts must be in all containers specified in the isIn array, otherwise contacts in any container will be returned
randomSeednumber  Optional, default = 0
Optionally used to seed the random number generator. Primarily useful for testing. The seed is used if the 'sort' field contains the value 'random'. Use this parameter to create repeatable random sequences.

Available from version : 1.3.4

firstIndexnumber0, or positive integer Optional, default = 0
Skip the first n results (used in multiple page sequences to skip previously fetched results)
sortstring  Optional, default = contact_id

A description of how to sort the results returned to the application. The attribute is a comma separated list of terms in the form :

[^]field[,[^]field]*

'field' is one of the following field names on which to sort : ID, name, description, type, value, random, time, dateTime

By default the order of a field in the sort is 'ascending'. This can be reversed by placing a ^ before the field name. Examples would be :

  • 'name' : sort by name
  • '^name' : Reverse alphabetic sort on name
  • '^value,name' : Sort first on 'value' (decending) then on 'name' ascending

random is only available from version 1.3.4

excludeInheritedbool0,1 Optional, default = 0
If 1, isIn and memberOf searches will only match entities which have direct membership, not indirect inherited membership of a Community
Care needs to be taken with the exact meaning of inherited here, everything that an Individual or OU is a member of by virtue of its parent OU is inherited including membership of the parent OU thus the only things that will be returned by an excludeInherited isIn get with a community as the root will be OUs or Individuals which have been directly linked to that community.
An even more astonishing side effect is that a excludeInherited isIn search on an OU will never return any results as all entities below it will have inherited their membership from it and thus be excluded.
Similarly an excludeInherited memberOf search will never return any OUs as these relationships are by definition inherited.
allDatanumbersubsetN, N=0:all Optional.

Marker to select extent of contact item data returned.

Subset 0 is everything
Subset 1 is everything except customData
Subset 2 is ID and uName only
Subset 3 is ID and email only

In addition, you can add '4' to these values to also receive an array of member information for a particular contact.

Add '8' to return the name of the parent OU for an individual or OU

Add '16' to return the keywords field

Add '32' to return the location field

Add '64' to return the calculated distance in miles from specified origin (or [0,0] if not specified)

Add '128' to return the password hash stored in the Whitebeam database for this contact (null if none stored) - version 1.3.9 onwards

maxRowsnumber  Optional, default = -1
This is a 'hint' to indicate the number of rows that are going to be used. This can improve performance if for example a result set can include thousands of rows, but the application will only display the first 20.
memberOfnumbervalid Individual ID Optional. If this parameter exists, then only communities and OUs containing this individual will be returned.
containsarray of numbersList of contact IDs Optional. Returns all OU or Community containers that contain any of the contacts in this list. If this parameter is specified then 'memberOf' is ignored.
minValuenumber  Optional. If specified then only return contacts in which the 'value' field is greater than or equal (>=) this value
maxValuenumber  Optional. If specified then only return contacts in which the 'value' field is less than or equal (<=) this value
locationstruct searchLocationsee definition Optional. Longitude, latidude, search radius and rest. If specified, return only records that have a location and where the location passes the search criteria

Available from version : 1.3.4


Whitebeam release 1.3.36
(loadtime : 189ms)