Creating a search tool for ColdFusion applications

There are three main tasks in creating a search tool for your ColdFusion application:

1. Create a collection.
2. Index the collection.
3. Design a search interface.

You can perform each task programmatically--that is, by writing CFML code. Alternatively, you can use the ColdFusion MX Administrator to create and index a collection.

This chapter presents the noncoding methods for developing a search tool, followed by code examples that perform the same task.

Creating a collection with the ColdFusion MX Administrator

Use the following procedure to quickly create a collection with the ColdFusion MX Administrator:

To create a collection with the ColdFusion MX Administrator:

1. In the ColdFusion MX Administrator, select Data & Services > Verity Collections.

   The Verity Collections page appears.

2. Enter a name for the collection; for example, DemoDocs.
3. Enter a path for the directory location of the new collection; for example, C:\CFusionMX7\verity\collections\.

   By default in the server configuration, ColdFusion stores collections in cf_root\verity\collections\ in Windows and in cf_root/verity/collections on UNIX. In the multiserver configuration, the default location for collections is cf_webapp_root/verity/collections. In the J2EE configuration, the default location for collections is verity_root/verity/collections, where verity_root is the directory in which you installed Verity.

   Note: This is the location for the collection, not for the files that you will search.

4. (Optional) Select a language other than English for the collection from the Language drop-down list.

   For more information on selecting a language, see Specifying a language.

5. (Optional) Select Enable Category Support to create a Verity Parametric collection.

   For more information on using categories, see Narrowing searches using categories.

6. Click Create Collection.

   The name and full path of the new collection appears in the list of Verity Collections.

You have successfully created an empty collection. A collection becomes populated with data when you index it. For more information, see the next section, About indexing a collection.

About indexing a collection

In order for information to be searched, it must be indexed. Indexing extracts both meaning and structure from unstructured information by indexing each document that you specify into a separate Verity collection that contains a complete list of all the words used in a given document along with metadata about that document. Indexed collections include information such as word proximity, metadata about physical file system addresses, and URLs of documents.

When you index databases and other record sets that you generated using a query, Verity creates a collection that normalizes both the structured and unstructured data. Search requests then check these collections rather than scanning the actual documents and database fields. This provides a faster search of information, regardless of the file type and whether the source is structured or unstructured.

Just as with creating a collection, you can index a collection either programmatically or using the ColdFusion MX Administrator. Use the following guidelines to determine which method to use:

You can use cfcollection action="optimize" if you notice that searches on a collection take longer than they did previously.

Updating an index

Documents are modified frequently in many user environments. After you index your documents, any changes that you make are not reflected in subsequent Verity searches until you re-index the collection. Depending on your environment, you can create a scheduled task to automatically keep your indexes current. For more information on scheduled tasks, see Configuring and Administering ColdFusion MX.

Creating a ColdFusion search tool programmatically

You can create a Verity search tool for your ColdFusion application in CFML. Although writing CFML code can take more development time than using these tools, there are situations in which writing code is the preferred development method.

Creating a collection with the cfcollection tag

The following are cases in which you might prefer using the cfcollection tag rather than the ColdFusion MX Administrator to create a collection:

• You want your ColdFusion application to be able to create, delete, and maintain a collection.
• You do not want to expose the ColdFusion MX Administrator to users.
• You want to create indexes on servers that you cannot access directly; for example, if you use a hosting company.

When using the cfcollection tag, you can specify the same attributes as in the ColdFusion MX Administrator:

You can create a collection by directly assigning a value to the collection attribute of the cfcollection tag, as shown in the following code:

<cfcollection action = "create"
   collection = "a_new_collection"
   path = "c:\CFusionMX7\verity\collections\">

If you want your users to be able to dynamically supply the name and location for a new collection, use the following procedures to create form and action pages.

To create a simple collection form page:

1. Create a ColdFusion page with the following content:

   <html>
   <head>
   	<title>Collection Creation Input Form</title>
   </head>
   
   <body>
   <h2>Specify a collection</h2>
   <form action="collection_create_action.cfm" method="POST">
   	
   	<p>Collection name: 
   	<input type="text" name="CollectionName" size="25"></p>
   	
   	<p>What do you want to do with the collection?</p>
   	<input type="radio" 
   		name="CollectionAction" 
   		value="Create" checked>Create<br>
   	<input type="radio" 
   		name="CollectionAction" 
   		value="Optimize">Optimize<br>
   	<input type="submit" 
   		name="submit" 
   		value="Submit"> 
   </form>
   
   </body>
   </html>
   

2. Save the file as collection_create_form.cfm in the myapps directory under the web root directory.

Note: The form will not work until you write an action page for it, which is the next procedure.

To create a collection action page:

1. Create a ColdFusion page with the following content:

   <html>
   <head>
   	<title>cfcollection</title>
   </head>
   
   <body>
   <h2>Collection creation</h2>
   
   <cfoutput>
   
   	<cfswitch expression=#Form.collectionaction#>
   		<cfcase value="Create">
   			<cfcollection action="Create"
   			collection="#Form.CollectionName#"
   			path="c:\CFusionMX7\verity\collections\">
   			<p>The collection #Form.CollectionName# is created.</p>
   		</cfcase>
   
   		<cfcase value="Repair">
   			<cfcollection action="Repair"
   			collection="#Form.CollectionName#">
   			<p>The collection #Form.CollectionName# is repaired.</p>
   		</cfcase>
   
   		<cfcase value="Optimize">
   			<cfcollection action="Optimize"
   			collection="#Form.CollectionName#">
   			<p>The collection #Form.CollectionName# is optimized.</p>
   		</cfcase>
   
   		<cfcase value="Delete">
   			<cfcollection action="Delete"
   			collection="#Form.CollectionName#">
   			<p>The collection is deleted.</p>
   		</cfcase>
   	</cfswitch>
   </cfoutput>
   </body>
   </html>
   

2. Save the file as collection_create_action.cfm in the myapps directory under the web root directory.
3. In the web browser, enter the following URL to display the form page:

   http://hostname:portnumber/myapps/collection_create_form.cfm

4. Enter a collection name; for example, CodeColl.
5. Verify that Create is selected and submit the form.
6. (Optional) In the ColdFusion MX Administrator, reload the Verity Collections page.

The name and full path of the new collection appear in the list of Verity Collections.

You successfully created a collection, named CodeColl, that currently has no data. For information on indexing your collection using CFML, see Indexing a collection using the cfindex tag.

Indexing a collection using the cfindex tag

You can index a collection in CFML using the cfindex tag, which eliminates the need to use the ColdFusion MX Administrator. The cfindex tag populates the collection with metadata that is then used to retrieve search results. You can use the cfindex tag to index either physical files (documents stored within your website's root folder), or the results of a database query.

Note: Prior to indexing a collection, you must create a Verity collection using either the ColdFusion MX Administrator, or the cfcollection tag. For more information, see Creating a collection with the ColdFusion MX Administrator, or Creating a collection with the cfcollection tag.

When using the cfindex tag, the following attributes correspond to the values that you would enter using the ColdFusion MX Administrator to index a collection:

collection

action

type

extensions

key

URLpath

recurse

language

You can use form and action pages similar to the following examples to select and index a collection.

To select which collection to index:

1. Create a ColdFusion page with the following content:

   <html>
   <head>
   	<title>Select the Collection to Index</title>
   </head>
   <body>
   
   <h2>Specify the index you want to build</h2>
   
   <form method="Post" action="collection_index_action.cfm">
   	<p>Enter the collection you want to index:
   	<input type="text" name="IndexColl" size="25" maxLength="35"></p>
   	<p>Enter the location of the files in the collection:
   	<input type="text" name="IndexDir" size="50" maxLength="100"></p>
   	<p>Enter a Return URL to prepend to all indexed files:
   	<input type="text" name="urlPrefix" size="80" maxLength="100"></p>
   
   	<input type="submit" name="submit" value="Index"> 
   
   </form>
   
   </body>
   </html>
   

2. Save the file as collection_index_form.cfm in the myapps directory under the web_root.

Note: The form does not work until you write an action page for it, which is the next procedure.

To use cfindex to index a collection:

1. Create a ColdFusion page with the following content:

   <html>
   <head>
   <title>Creating Index</title>
   </head>
   <body>
   <h2>Indexing Complete</h2>
   
   <cfindex collection="#Form.IndexColl#"
   	action="refresh"
   	extensions=".htm, .html, .xls, .txt, .mif, .doc"
   	key="#Form.IndexDir#"
   	type="path"
   	urlpath="#Form.urlPrefix#"
   	recurse="Yes"
   	language="English">
   
   <cfoutput>
   	The collection #Form.IndexColl# has been indexed.
   </cfoutput>
   </body>
   </html>
   

2. Save the file as collection_index_action.cfm.
3. In the web browser, enter the following URL to display the form page:

   http://hostname:portnumber/myapps/collection_index_form.cfm

4. Enter a collection name; for example, CodeColl.
5. Enter a file location; for example, C:\CFusionMX7\wwwroot\vw_files.
6. Enter a URL prefix; for example, http://localhost:8500/vw_files (assuming that you are using the built-in web server).
7. Click Index.

   A confirmation message appears on successful completion.

Note: For information about using the cfindex tag with a database to index a collection, see Working with data returned from a query.

Indexing a collection with the ColdFusion MX Administrator

As an alternative to programmatically indexing a collection, use the following procedure to index a collection with the ColdFusion MX Administrator.

To use ColdFusion MX Administrator to index a collection:

1. In the list of Verity Collections, select a collection name; for example, CodeColl.
2. Click Index to open the index page.
3. For File Extensions, enter the types of files to index. Use a comma to separate multiple file types; for example, .htm, .html, .xls, .txt, .mif, .doc.
4. Enter (or Browse to) the directory path that contains the files to be indexed; for example, C:\Inetpub\wwwroot\vw_files.
5. (Optional) To extend the indexing operation to all directories below the selected path, select the Recursively index subdirectories check box.
6. (Optional) Enter a Return URL to prepend to all indexed files.

   This step lets you create a link to any of the files in the index; for example, http://127.0.0.1/vw_files/.

7. (Optional) Select a language other than English.

   For more information, see Specifying a language.

8. Click Submit Changes.

   On completion, the Verity Collections page appears.

   Note: The time required to generate the index depends on the number and size of the selected files in the path.

This interface lets you easily build a very specific index based on the file extension and path information you enter. In most cases, you do not need to change your server file structures to accommodate the generation of indices.

View comments in LiveDocs