The mgiSearchDatabase Tag
Tag Behavior
Use the mgiSearchDatabase tag is used to search a database
and display the results.
Tag Syntax
The mgiSearchDatabase tag has a beginning tag with one required
parameter and thirteen optional parameters, a body, and an ending
tag . The tag form is:
<mgiSearchDatabase databaseName="Database"
keyFieldName="Field Name" fieldValue="Value"
keyFieldName="Field Name" pageVariableName="Variable Name"
keyFieldName="Field Name" pathArgumentName="Path Argument Name"
keyFieldName="Field Name" postArgumentName="Post Argument Name"
orderByField="Field Name" reverseOrder="Yes/No"
resultsPerPage="Integer" page="Integer"
resultVariableName="Variable Name" odbcDatasource="Source Name"
odbcUsername="Name" odbcPassword="Password">
Template for Results Display
</mgiSearchDatabase>
or
<mgiSearchDatabase databaseName="Database"
searchString="String" resultsPerPage="Integer"
page="Integer" resultVariableName="Variable Name"
odbcDatasource="Source Name" odbcUsername="Name"
odbcPassword="Password">
Template for Results Display
</mgiSearchDatabase>
Required Parameters:
- databaseName - The database is the name of the database
to search.
Optional Parameters:
- keyFieldName - The keyFieldName is the name of the
database field to search. Multiple keyFieldName parameters may
be included in one mgiSearchDatabase tag, but each keyFieldName
parameter must be immediately followed by a fieldValue,
pageVariableName, pathArgumentName, or postArgumentName parameter
that contains the search criteria for that field. When multiple
keyFieldName and value pairs are present, an AND search is performed.
To perform an OR search, you must use the searchString parameter.
- fieldValue - The fieldValue is the search criteria
for the preceding keyFieldName parameter in the mgiSearchDatabase
tag.
- pageVariableName - The pageVariableName is the name
of the page variable that contains the search criteria for the
preceding keyFieldName parameter in the mgiSearchDatabase tag.
- pathArgumentName - The pathArgumentName is the name
of the path argument that contains the search criteria for the
preceding keyFieldName parameter in the mgiSearchDatabase tag.
- postArgumentName - The postArgumentName is the name
of the post argument that contains the search criteria for the
preceding keyFieldName parameter in the mgiSearchDatabase tag.
- searchString - The search string is a fully formatted
search string containing the field names to search, the search
criteria, and the search operations. If
the searchString parameter is specified, the keyFieldName, pageVariableName,
pathArgumentName, postArgumentName, orderByField, and reverseOrder
parameters are ignored. Search strings should contain
field name and search criteria in the format keyFieldName='criteria'.
Valid operators are "=" (equals), ">"
(greater than), "<" (less than), ">="
(greater than and equal to), and "<=" (less than
and equal to). Field name and search criteria pairs should be
separated by the search operator "AND", "OR",
or "NOT". To order the results from a search string,
include the order by field in the format ORDER BY keyFieldName.
By default, search results are in asending order (ASC). To reverse
the order of results in a search string, specify descending order
by including DESC after the ORDER BY field. You may not enter
quotes ("") in the value of the search string parameter.
The following are example search strings:
searchString="LastName='J*' OR LastName='L'
AND Registration='Yes' ORDER BY CustID DESC"
searchString="FirstName='Ken' AND NOT LastName='Barker'
- orderByField - The orderByField is the name of the
database that is used to order search results. Only
indexed fields can be used to order search results.
- reverseOrder - The reverseOrder parameter specifies
if the results are listed in ascending or descending order. If
the reverseOrder parameter value is "Yes", then
results are listed in descending order. If the reverseOrder parameter
value is "No", then results are listed in ascending
order. The default value is "No".
- resultsPerPage - The resultsPerPage is the number
of search results to display. The default value is 25. The maximum
value of this parameter is controlled by the region settings for the
Database Module. The default maximum is 100 and must be specifically
overridden in the region settings to be able to return more than
100 records.
- page - The page is the set of search results to display.
For example, if the resultsPerPage is set to "25",
then page 1 displays results 1 to 25 and page 2 displays results
26 to 50. The default value is 1.
- resultVariableName - The resultVariableName is the
name prepended to result variables that contain information about
the search. You may choose any name for the result variable prefix.
To display result variables use the mgiGet
tag. In the following list of available result variables, the
resultVariableName value is "resultvar". Result
variables are created and available anywhere on the page after
the mgiSearchDatabase tag.
- resultvar_ResultCount - A page variable with the total
number of results.
- resultvar_FirstIndex - A page variable with the index
number of the first result shown on the page.
- resultvar_LastIndex - A page variable with the index
number of the last result shown on the page.
- resultvar_PrevPage - A page variable with the number
of the page preceding the current page. The value of this variable
is zero (0) if the current page is 1.
- resultvar_Page - A page variable with the number of
the page currently displaying
- resultvar_NextPage - A page variable with the number
of the page following the current page. The value of this variable
is zero (0) if the current page is the last page.
- resultvar_LastPage - A page variable with the number
of the last page.
- displayPrecision - The displayPrecision parameter
specifies the precision that should be used to display a decimal
number. The format is "fieldName, precision". Multiple
displayPrecision parameters may be specified, one for each decimal
number field that is to be formatted with a certain number of
decimal places. If the specified precision has less decimal places
than the actual number, the number is rounded. If the specified
precision has more decimal places than the actual number, the
number is padded with trailing zeroes. For example, use displayPrecision="Price,
2" to display the Price field formatted with two decimal
places.
- odbcDatasource (NT only) - The odbcDatasource is the name of
datasource on the server that provides access information for
an external ODBC database. If the odbcDatasource parameter is
included, database information will be searched in the specified
ODBC database rather than the internal MGI database. Inquire
with the server administrator for additional information about
the use of ODBC databases. If you include
the odbcDatasource parameter, the odbcUsername and odbcPassword
parameters are required.
- odbcUsername (NT only) - The odbcUsername is the username required
to access the ODBC datasource. The odbcUsername
parameter is required if you include the odbcDatasource parameter.
- odbcPassword (NT only) - The odbcPassword is the code required
to access the ODBC datasource. The odbcPassword
parameter is required if you include the odbcDatasource parameter.
Results Display:
The body of the mgiSearchDatabase tag contains a template
display that is repeated for each search result. To retrieve
a field value for a result, use the placeholder format of &mgiDBFieldEnterFieldNameHere;
in the body of the mgiSearchDatabase tag. Each placeholder will
be replaced with the specific information in that field for each
result. For example, to include values from the FirstName field
in the database for each result, you would enter the following
in your template:
&mgiDBFieldFirstName;
To display the unique database ID for a result, use the field
name "MGIIDFIELD".
Example Usage and Output
<mgiSearchDatabase databaseName="Homes"
keyFieldName="Style" postArgumentName="StyleSearch"
resultsPerPage="25" page="1"
resultVariableName="HomeSearch">
<P>House Address: &mgiDBFieldAddress;
<P>House Style: &mgiDBFieldStyle;
<P>Price: &mgiDBFieldPrice;
<BR>
</mgiSearchDatabase>
Results found: <mgiGet name="HomeSearch_ResultCount">
In this example, a user selects search criteria for a home
based on home styles. The Homes database is searched and the
following would display if there were three matching results:
House Address: 128 B Lane Ave
House Style: Ranch
Price: 120,000
House Address: 8827 Main St
House Style: Ranch
Price: 80,000
House Address: 3289 Octavia St
House Style: Ranch
Price: 200,000
Results found: 3
In the following example, the Homes database is searched using
a string search with ordering.
<mgiSet name="SearchString">
Style='<mgiPostArgument name="StyleSearch">'
ORDER BY Price DESC
</mgiSet>
<mgiSearchDatabase databaseName="Homes"
searchString={mgiGet name="SearchString"}
resultsPerPage="25" page="1"
resultVariableName="HomeSearch">
<P>House Address: &mgiDBFieldAddress;
<P>House Style: &mgiDBFieldStyle;
<P>Price: &mgiDBFieldPrice;
<BR>
</mgiSearchDatabase>
The results of the string search would be:
House Address: 3289 Octavia St
House Style: Ranch
Price: 200,000
House Address: 128 B Lane Ave
House Style: Ranch
Price: 120,000
House Address: 8827 Main St
House Style: Ranch
Price: 80,000
Suggested Usage
|