CSP and HTML Tag Reference
<CSP:SEARCH>
[Back] [Next]
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Defines a JavaScript function that invokes the CSP Search Page.
Synopsis
<CSP:SEARCH>
Attributes
General Attributes
Attribute Description Value
CAPTION A string displayed on the standard Search Page. String.
CLASSNAME Required. Class name upon which the search is performed. Note that this is a class name and not a table name. String.
FEATURES The value of the features argument to the JavaScript window.open call for the popup search window. String.
FORM The name of the form associated with the search. This is used to update a bound form on the page that invoked the Search Page String.
IDNAME Deprecated. The name of the id field of the object being searched. String.
MAXROWS Specifies the maximum number of rows to display in the search results table. The default is 100. An integer.
NAME The name of the search function. The default name is search. Valid JavaScript function name.
NODISPLAY Used with the ORDER attribute, it prevents the query from being run automatically when the search page is displayed, such as ORDER="City" OPTIONS="NODISPLAY" String.
OBJID Object Identifier value used to identify an object on the initial page. This is used to update a bound form on the page that invoked the Search Page. String.
OBJIDATTR Name of the object identifier attribute of the associated form. Default is OBJID. String.
ONSELECT An optional JavaScript function, on the page that invoked the Search Page, to execute after an item has been selected within the Search Page. JavaScript function name.
OPTIONS A comma-separated list of search window options. These include popup, clearbtn, display, nodisplay, predicates, sortbox, leaveopen, and showcount. String.
ORDER A comma-delimited list of fields used to sort the search results in the form of propname|direction where propname is the name of the property and direction is either ASC (ascending) or DESC (descending). If direction is not specified then the default from the SELECT or WHERE attribute is used. If ORDER is specified, then the query is run automatically when the search window is displayed. This automatic running can be turned off by specifying NODISPLAY in the OPTIONS attribute, such as ORDER="City" OPTIONS="NODISPLAY" String.
PREDICATES A comma-delimited list of search predicates (comparison operators) corresponding to and used for each of the fields in the WHERE list. String.
SELECT A comma-delimited list of fields to display in the search results in the form of propname|direction. where propname is the name of the property alias is an optional alias, and direction is the optional default direction, either ASC (ascending) or DESC (descending), to be used in the ORDER attribute if not specified there. If SELECT is not specified, the WHERE attribute is used as the select list. String.
SHOWSQL Show SQL used for search to help with debugging. 0, or 1.
STARTVALUES A comma-delimited list of fields whose initial value comes from the form. String.
TARGET Specifies the page to which the links in the search result window point. The default is the page invoking the search. String.
WHERE A comma-delimited list of fields used as search criteria in the form of propname|direction where propname is the name of the property, alias is an optional alias, and direction is the optional default direction, either ASC (ascending) or DESC (descending), to be used in the ORDER attribute if not specified there. String.
Description
The CSP:SEARCH tag defines a client-side JavaScript function that invokes the CSP Search Page. The name of the JavaScript function is specified by the value of the NAME attribute.
The Caché Web Form Wizard places the CSP:SEARCH tag within the pages it generates. This gives users the ability to perform database searches from the generated pages. You can use the attributes of the CSP:SEARCH tag to customize the behavior of the search page within pages generated by the Form Wizard. You can also use it to invoke the CSP Search Page from pages built without the Form Wizard. You are also free to implement your own search page (using CSP) and to invoke it if the CSP Search Page is not appropriate for your application.
CSP Search Page
CSP provides a generic Search Page that is implemented via the %CSP.PageLookup class. The Search Page prompts the user for input values, executes an SQL query, and displays the results within an HTML table. Typically, a user invokes the Search Page from a CSP page containing a form that is bound to an object. When the user chooses an object from the results displayed in the Search Page, the form page is updated to display the object's data.
Within a CSP page, you can use the CSP:SEARCH tag to automatically define a JavaScript function that invokes the CSP Search Page. You can then invoke this function in response to a client-side event, such as a button press.
For example, the following defines a JavaScript function, my_search:
<CSP:SEARCH NAME="my_search" CLASSNAME="MyApp.Person" WHERE="Name,Home_City">
Within the same page, you can invoke this function in response to a client-side event such as a button press:
<INPUT TYPE="button" NAME="Search" VALUE="Search" ONCLICK="my_search();">
When you click the Search button, the CSP Search Page is displayed and allows you to search for instances of MyApp.Person by Name or Home.City as specified by the CLASSNAME and WHERE attributes of the CSP:SEARCH tag.
Specifying the Search Page Query
The CSP Search Page creates and executes an SQL query based on the values of CSP:SEARCH tag attributes.
CLASSNAME
The required CLASSNAME name attribute specifies the name of the class against which the query is executed, that is the FROM clause of the SQL query. Note that this is a class name and not the SQL table name—they may be different.
WHERE
The WHERE attribute contains a comma-delimited list of one or more field names (SQL names and not property names—there may be a difference) that are used as search criteria (the fields in the WHERE clause of the SQL query). For each field, the Search Page displays an input field in which you can enter a search value.
If you omit the WHERE attribute, the Search Page uses the Object ID column for a search field. If you omit the SELECT attribute then the WHERE attribute also specifies the SELECT list for the SQL query.
Within the WHERE attribute (as well as the SELECT attribute) you can use certain expressions as field names. These include:
Expression Example
Alias for Field WHERE="FName As FirstName"
Field in Embedded Object WHERE="Home.City"
Field in Referenced Object WHERE="Company->Name"
Here is an example using the WHERE attribute:
<!-- Define a search function -->
<CSP:SEARCH NAME="mySearch" CLASSNAME="Sample.Person"
WHERE="Name,SSN,Spouse->Name">

<!-- invoke the search function -->
<FORM>
<INPUT TYPE="button" VALUE="Search" ONCLICK="mySearch();">
</FORM>
The conditions used for each field in the WHERE clause are determined by the PREDICATES attribute.
Here is an example using the WHERE attribute with an alias. Let's assume that you have a class with a property called ISCLName and another property called ISCLFName. If you want these properties to appear on the Search page as "Last Name" and “First Name” respectively instead of "ISCLName” and “ISCLFName”, specify aliases as follows:
<csp:search NAME="my_search" CLASSNAME="Test.NewClass4" 
WHERE="ISCLName Last Name, ISCFName First Name">
SELECT
You can control the values that are displayed in the search results using the SELECT attribute. This contains a comma-delimited list of one or more SQL field names used as the SELECT list of the search query.
For example:
<CSP:SEARCH NAME="mySearch" CLASSNAME="Sample.Person"
WHERE="Name" SELECT="Name,SSN,Spouse->Name Spouse,Home.City City">
In this case, the Search Page results displays the 4 columns specified by the SELECT attribute:
Name SSN Spouse City
Note that, as with the WHERE attribute, you can use -> (reference) syntax to refer to properties defined in related classes, such as Spouse->Name. You can refer to embedded object properties using dot syntax: Home.City. You can define an alias (name used as a column header) by placing it after the field name: Name Alias.
If you omit the SELECT attribute, the fields specified by the WHERE attribute are used.
PREDICATES
You can use the PREDICATES attribute to control how the Search Page uses fields in the WHERE attribute. This attribute contains a comma-separated list of operator names (see table below) that correspond to the fields listed in the WHERE attribute.
If you omit the PREDICATES attribute, then the Search Page uses %startswith for all string properties and = for all other properties. The default operators are used for any items in the WHERE list that do not have corresponding items in the PREDICATES list.
You can use any of the following comparison operators within the PREDICATES attribute:
Operator Matches
%startswith All values that start with the user input. This is only useful for strings.
= All values that are equal to the user input.
<> All values that are not equal to the user input.
> All values that are greater than (collate after) to the user input.
< All values that are less than (collate before) to the user input.
between All values that are between two values entered by the user. The two values are separated by an ampersand.
contains All values that contain the user input. This is only useful for strings.
select All values that are equal to a selection made from a drop down list.
Here is an example using the PREDICATES attribute:
<CSP:SEARCH NAME="mySearch" CLASSNAME="Sample.Person"
WHERE="Name,SSN,Spouse->Name"
PREDICATES="%startswith,=,contains"
>
In this case, the Search Page searches for all instances of Sample.Person whose Name starts with a value, whose SSN is equal to a value, and whose Spouse.Name contains a value.
The select operator merits special attention: if present in the list of predicates, the Search Page displays a drop down list containing all possible values of the appropriate field. For example:
<CSP:SEARCH NAME="mySearch" CLASSNAME="Sample.Employee"
WHERE="Name,Company->Name Company"
PREDICATES="%startswith,select"
>
In this case, the Search Page displays a drop down list containing every possible Company Name. The list is created by issuing the appropriate SQL query at runtime, in this case:
SELECT %ID, Name FROM Sample.Company ORDER BY Name
 
The Search Page uses the value selected by the user to perform the main search in the most efficient way that it can. For example, in this case, it most likely searches for all instances of Sample.Employee with a given Company ID value (to avoid a JOIN).
Obviously you should not use the select operator for fields with many (possibly thousands) of potential values.
ORDER
You can control the initial ordering of the search results using the ORDER attribute. This contains a comma-delimited list of one or more SQL field names to be used as the ORDER BY clause of the search query.
SHOWSQL
When troubleshooting applications, it is sometimes helpful to view the actual SQL query used by the CSP Search Page. To do this, set the SHOWSQL attribute to 1. This displays the text of the SQL query along with the query results within the Search Page.
Specifying the Features of the Search Page
You can control the appearance and behavior of the CSP Search using attributes of the CSP:SEARCH tag. Some of these as described below.
OPTIONS
The OPTIONS attribute lets you control aspects of CSP Search Page. Its value is a comma-delimited list containing one or more of the following:
Option Description
clearbtn If present, the Search Page includes a Clear button that resets the contents of the search criteria fields.
display If present, the Search Page displays a list of results when it is initially displayed.
leaveopen If present, the Search Page is not be closed when the user makes a selection.
nodisplay If present with the ORDER attribute, the query is not run automatically when the search window is displayed.
popup If present, the Search Page is displayed as a popup window. For an example see the popform.csp CSP sample. You can control the size and appearance of the popup window using the FEATURES attribute.
predicates If present, the Search Page displays a combobox of search predicates (such as startswith, greater than, and so on) next to each search criteria input box.
showcount If present, the Search Page displays the number of records found by the query.
sortbox If present, the Search Page displays a set of radio buttons that allows the user to choose how to sort the results.
For example, here is the definition of a search function that invokes a popup Search Page with a set of radio buttons to specify sorting:
<!-- Define a search function -->
<CSP:SEARCH NAME="mySearch" CLASSNAME="Sample.Person" 
WHERE="Name,SSN" OPTIONS="popup,sortbox">

<!-- invoke the search function -->
<FORM>
<INPUT TYPE="button" VALUE="Search" ONCLICK="mySearch();">
</FORM>
CAPTION
The CAPTION attribute lets you change the caption displayed at the top of the Search Page. For example:
<!-- Define a search function -->
<CSP:SEARCH NAME="mySearch" CLASSNAME="Sample.Person" 
WHERE="Name,SSN" CAPTION="This is my Search Page:">

<!-- invoke the search function -->
<FORM>
<INPUT TYPE="button" VALUE="Search" ONCLICK="mySearch();">
</FORM>
FEATURES
The FEATURES attribute lets you specify the size and appearance of a popup search window. CSP creates a popup search window by calling the JavaScript function, window.open. This function takes an argument,features, which controls aspects of the new window. CSP uses the value of the FEATURES attribute for the features argument.
The FEATURES attribute contains a list of comma-separated feature values. There should be no spaces or other whitespace. Each element in the list has the format:
feature[=value]
For a list of available feature names, refer to the Window.open method within a JavaScript function reference.
For example, the following defines a popup Search Page with an initial height and width of 350 pixels:
<!-- Define a search function -->
<CSP:SEARCH NAME="mySearch" CLASSNAME="Sample.Person" WHERE="Name,SSN"
OPTIONS="popup" FEATURES="height=350,width=350">

<!-- invoke the search function -->
<FORM>
<INPUT TYPE="button" VALUE="Search" ONCLICK="mySearch();">
</FORM>
MAXROWS
The MAXROWS attribute lets you specify the maximum number of rows to display in the search results table.