Whitebeam Template Reference Documentation

Site Map
Application Guide
  XML Markup
  JavaScript Classes
  Dev Process
  External Links
  Example libraries
Contact Whitebeam
Whitebeam Users

Whitebeam Template Reference Documentation


Search criteria for category nodes.


The rb.catalogue.category.categorySearchType struct has 17 elements:

Name Type/Value Range/Length Description
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.

Available from version : 1.3.5

allDatanumbersubsetN, N=0=all Optional, default = 0
Marker to select extent of catalogue item data returned.
Subset 0 is all data
Subset 1 is everything except nodeData
idMkrstringI=item, N=node, C=contact. Required. Marker to qualify ID as an item, a category node or a contact respectively.
IDnumberinteger Required. Identifier of reference (starting) item, category node or contact.
allLevelsnumber-1..1 Optional, default = 0
Set to 1 to search through all sub categories of the specified reference category node (overrides nextLevel) or to -1 to search through all its 'parent' nodes in path up to but excluding the virtual root node. Ignored if idMkr=I.
nextLevelnumber-1..1 Optional, default = 0
Set to 1 to search through the first level of sub categories of the specified reference category node or to -1 to search through its immediate parent. Ignored if idMkr=I or =C or if allLevels=1 or =-1.
keywordarray of strings10 strings max. Optional. Minimum keywords does not perform a text search (i.e. searchIn... flags are ignored).
Similarly, keywords are ignored if none of the searchIn... flags is set. Any excess search keywords are ignored.
searchInNamebool0 = FALSE, 1 = TRUE Optional, default = 0
Flag requesting a search to include category names.
searchInDescriptionbool0 = FALSE, 1 = TRUE Optional, default = 0
Flag requesting a search to include category descriptions.
searchInDatabool0 = FALSE, 1 = TRUE Optional, default = 0
Flag requesting a search to include custom category data.
sortByNamebool0 = FALSE, 1 = TRUE Optional, default = 0
Flag requesting the search response to be sorted by name. Ignored for count.
firstIndexnumber0.. Optional, default = 0
Index (zero based) of the first node matching the search criteria to be returned by iterator. Ignored for count.
hasNodeIDnumber0.. Optional, default = 0
Used if idMkr is 'C' and specifies an additional catalogue node to which resultant items must be attached in order to satisfy this request.
hasContactIDnumber0.. Optional, default = 0
Not currently used
isInContactarray of numbers  Optional.

List of contact IDs that nodes must be in to pass this search. A node must be attached to at least *one* of the contact IDs in the list in order to be returned to the caller.

New from version 0.9.37

sortBystring"nodeID" | "name" | "description" | "none" Optional.

If this optional field is specified then it overrides the default ordering or the 'sortByName' field. The first 3 options specify which of the available fields to sort the request results by. The last 'none' specifies that the data is not to be ordered. This is the fastest option if the application wishes to scan a large data set and doesn't care about the order.

In addition - with the exception of 'none' - each of these order specifiers may optionally have a '^' preceeding them. If this character is present then the order of the search is reversed. So for example "^name" sorts by the name field in reverse alphabetic order.

This field is ignored if 'searchMethod' is 'rank'. In the case of a ranked search the most relevant results are returned first.

searchMethodstring"and" | "or" | "nand" | "nor" Optional, default = and

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


A category node can be directly retrieved or a search conducted either from a category node or for nodes to which a specified item or contact entity is linked.

Note that the virtual root node (nodeID=0) is the highest category in a catalogue. Each category that is created with a parentID=0 is attached to the virtual root node. Also, each item is implicitly linked to the virtual root node and is referred to as an 'orphan' item . Similarly, an item becomes an orphan when it is explicitly unlinked from all category nodes.

Wildcards of % and _ can be included in the keywords and therefore these characters cannot themselves be searched for.


(idMkr, ID, allLevels, nextLevel, ...) settings and type of search:

(I, itemID, ., .): Any category nodes with the specified item.
(I, 0, ., .): Any category nodes with any item.
(N, nodeID, 0, 0): A specific category node.
(N, nodeID, 1, .): Any 'sub' nodes in a single category.
(N, nodeID, 0, 1): Any 'sub' nodes in a category hierarchy.
(N, nodeID, -1, .): All 'parent' nodes in path up to (and excluding) virtual root.
(N, nodeID, 0, -1): Immediate parent of specified category (same as N, parentID, 0, 0).
(C, contact ID, 0, .): Any category nodes associated with a contact.
(C, contact ID, 1, .): Any category nodes associated with a contact and its relations.
(C, 0, , ): Any category nodes associated with any contact.

Whitebeam release 1.3.36
(loadtime : 185ms)