Creating a Searchable Data Source

You must do the following steps to create a searchable data source:

Create a collection.
You can do this either through the ColdFusion Administrator or programmatically.
Populate and index the collection.
You must select the data and generate the index. You can perform this task either through the ColdFusion Administrator or programmatically.
Design a search interface and a results page so that users can access the searchable data source.

You can use the Verity Wizard in ColdFusion Studio to create ColdFusion pages that index and search a collection. (The wizard does not create a page for creating the collection.) To run the wizard, select File > New and select the Verity Wizard from the CFML tab in the New Document dialog box.

Creating a Collection

The Verity engine performs searches against collections. A collection is a special database created by Verity that contains pointers to the indexed data that you specify for that collection. ColdFusion's Verity implementation supports collections of three basic data types:

Text files such as HTML pages and CFML pages
Binary documents (see "Supported File Types")
Result sets returned from cfquery, cfldap, and cfpop queries

You can build a collection from individual documents or from an entire directory tree. Collections can be stored anywhere, so you have a great deal of flexibility in accessing indexed data.

You can use either of the following methods to create a Verity collection:

Make selections on the ColdFusion Administrator Verity Collections page
Code the cfcollection tag

Using the ColdFusion Administrator to create a collection

You can use the ColdFusion Administrator to create a new collection or map an existing collection.

Creating a new collection

Use the following procedure to create a new collection.

To create a collection:

Open the ColdFusion Administrator Verity Collections page.
If you checked the option to install the ColdFusion documentation, the documentation collection is listed by default. The Verity engine is used to search the online documents.
In the top section of the page, enter a name for the collection.
Enter a path for the directory location of the new collection.
By default, new collections are added to \Cfusion\Verity\Collections\ in Windows and /opt/coldfusion/verity/collections in UNIX.
If you have an International Language Search Pack installed, you can select a language other than English for the collection from the drop-down list.
Make sure Create a new collection is selected.
Click Submit Changes.
When the collection is created, the name and full path of the new collection appear in the Verity Collections list at the top of the page.

Enabling access to an existing collection

You can easily enable access to a collection on the network by creating a local reference (an alias) for that collection. The collection only needs to be a valid Verity collection; it does not matter whether the collection was created within ColdFusion or another tool.

Use the following procedure to enable access to an existing collection.

To add an existing collection:

Open the ColdFusion Administrator Verity Collections page.
In the top section of the ColdFusion Administrator Verity Collections page, enter the collection alias.
Enter the full path to the collection.
Select a language, if needed.
Click Map an existing collection.
Click Submit Changes.

Creating a collection with the cfcollection tag

Creating and maintaining collections from a CFML application eliminates the need to access the ColdFusion Administrator. You might prefer this technique if you need to schedule collection creation. It also allows you to allow users to create collections without exposing them to the ColdFusion Administrator.

To create a simple collection form page:

Open a new file in ColdFusion Studio.

Modify the file so that it appears as follows:

<html>

<head>

  <title>Collection Creation Input Form</title>

</head>



<body>

<h2>Specify a collection</h2>

<form action="collectioncreateaction.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="Repair">Repair<br>

  <input type="radio" 

    name="CollectionAction" 

    value="Optimize">Optimize<br>

  </p>

  <input type="submit" 

    name="submit" 

    value="Submit"> 

</form>



</body>

</html>

Save the file as collectioncreateform.cfm.

Note that this file simply shows how the form variables are used and does not perform error checking.

To create a collection action page:

Open a new file in ColdFusion Studio.

Modify the file so that it appears as follows:

<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:\CFUSION\Verity\Collections\">

      <p>The collection #Form.CollectionName# is created.

    </cfcase>



    <cfcase value="Repair">

      <cfcollection action="Repair"

      collection="#Form.CollectionName#">

      <p>The collection #Form.CollectionName# is repaired.

    </cfcase>



    <cfcase value="Optimize">

      <cfcollection action="Optimize"

      collection="#Form.CollectionName#">

      <p>The collection #Form.CollectionName# is optimized.

    </cfcase>



    <cfcase value="Delete">

      <cfcollection action="Delete"

      collection="#Form.CollectionName#">

      <p>Collection deleted.

    </cfcase>

  </cfswitch>

</cfoutput>

</body>

</html>

Save the file as collectioncreateaction.cfm.
View the file collectioncreateform.cfm in your browser, enter values and submit the form.

Populating and indexing a collection

When you create a new collection, it is just an empty shell. You can use either of the following methods to populate a Verity collection:

Use the ColdFusion Administrator Verity Collections page.
Code the cfindex tag.

Note

You can index and search against Verity collections created outside of ColdFusion by using the external attribute of cfindex and cfsearch.

Selecting an indexing method

Use the following guidelines to determine which method to use:

Use the Administrator if

Use the cfindex tag if

You want to index document files.
You want to index ColdFusion query results.

The collection will not be updated frequently.
Your collection needs to be updated frequently.

You want to generate the collection without writing any CFML code.
You need to dynamically populate or update a collection from a ColdFusion application page.

You want to generate a one-time collection.
Your collection needs to be updated by other people.

Use the Administrator if	Use the cfindex tag if
You want to index document files.	You want to index ColdFusion query results.
The collection will not be updated frequently.	Your collection needs to be updated frequently.
You want to generate the collection without writing any CFML code.	You need to dynamically populate or update a collection from a ColdFusion application page.
You want to generate a one-time collection.	Your collection needs to be updated by other people.

Using ColdFusion Administrator

To use ColdFusion Administrator to index a collection:

Select a collection name in the Verity Collections box.
Click Index to open the index page.
Edit the File Extensions box so that it lists the types of files to index, either as a single file type or multiple file types separated by commas.
Type in the directory path containing the files to be indexed or click Browse Server and navigate to the directory in which to begin the index.
Select the Recursively Index Sub Directories box if you want to extend the indexing operation to all directories below the selected path.
(Optional) Enter a Return URL to prepend to all indexed files. This step lets you easily create a link to any of the files in the index. A typical entry is http://localhost/wwwroot/.
(Optional) Select a language. You must have the International Language Search Pack installed.
Click Submit Changes to begin the indexing process.
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.

In your ColdFusion application, you can populate and search multiple collections, each of which can focus on a specific group of documents or queries, according to subject, document type, location, or any other logical grouping. Because searches can be performed against multiple collections, you have substantial flexibility in designing your search interface.

Using cfindex

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

To select which collection to index:

Open a new file in ColdFusion Studio.

Modify the file so that it appears as follows:

<html>

<head>

  <title>Select the Collection to Index</title>

</head>



<h2>Specify the index you want to build</h2>



<form method="Post" action="collectionindexaction.cfm">

  <p>Enter the collection you want to populate:

  <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>



  <input type="submit" name="submit" value="Index"> 



</form>



</body>

</html>

Save the file as collectionindexform.cfm

To use cfindex to index a collection:

Open a new file in ColdFusion Studio.

Modify the file so that it appears as follows:

<html>

<head>

<title>Creating Index</title>

</head>

<body>

<h2>Indexing Complete</h2>



<cfindex collection="#Form.IndexColl#"

  key="#Form.IndexDir#"

  action="refresh"

  type="path"

  urlpath="#Form.IndexDir#"

  extensions=".htm, .html"

  recurse="Yes"

  language="English">



<cfoutput>

  The collection #Form.IndexColl# has been indexed.

</cfoutput>

</body>

</html>

Save the file as collectionindexaction.cfm.
View collectionindexform.cfm in your browser, enter values, and then click Index.

Building a search interface

After you create and index a searchable data source, you need to build a search interface to allow users to access the data source. The cfsearch tag provides users with a set of operators and modifiers to create sophisticated query expressions. This section describes how to get a basic search application up and running. Later sections explore these options in detail.

Using the Verity Wizard in ColdFusion Studio

To quickly create a search application for an existing collection, select File > New in ColdFusion Studio and select the Verity Wizard in the CFML tab of the New Document dialog box. The wizard creates a set of application pages based on the entries you make in the wizard pages.

You can customize the search interface by adding instructional text for users and applying styles to the form pages.

Basic search operations

The following procedure describes the basic search operations.

To search the collection:

Create a file in ColdFusion Studio.

Modify the file so that it appears as follows:

<html>

<head>

  <title>Select the collection to search</title>

</head>



<body>

<h2>Search</h2>



<form method="Post" action="collectionsearchaction.cfm">

  <p>Enter the collection you want to search:

  <input type="text" name="collection" size="25" maxlength="35"></p>

  <p>Select the type of search:<br>

  <input type=radio

    name=type

    value=simple checked> Simple<br>

  <input type=radio

    name=type

    value=explicit> Explicit<br>



  <p>Enter a search string:</p>

  <input type=text 

    name=searchstring size=50>



  <p><input type=submit

    name=search1 

    value="Search">

  <input type=reset 

    value="Reset">

</form>



</body>

</html>

Save the file as collectionsearchform.cfm.

Note

To use cfsearch to search a Verity K2 Server collection, the collection attribute must be the collection's unique alias name as defined in the k2server.ini and the external attribute must be "No" (the default).

To present the results of the search to the user:

Create a new file in ColdFusion Studio.

Modify the file so that it appears as follows:

<html>

<head>

  <title>Search output page</title>

</head>



<body>

<cfsearch name="Search1"

  collection="#form.collection#"

  form type="#form.type#"

  criteria="#form.searchstring#">



<h2>Search Results</h2>



<cfoutput>

  #Search1.RecordCount# found out of

  #Search1.RecordsSearched# searched.

</cfoutput>



<hr noshade>

  <cfoutput query="Search1">

    <a href="#Search1.URL#">#Search1.title#</a><br>

  </cfoutput>

<hr noshade>

</body>

</html>

Save the file as collectionsearchaction.cfm.
View the file collectionsearchform.cfm in your browser, enter values in the form, and then submit it.

Creating summaries

As part of the indexing process, Verity automatically produces a summary of every document file or every query result set that gets indexed. The default summarization selects the best sentences, based on internal rules, up to a maximum of 500 characters. Summarization information is returned by default with every cfsearch operation. For more information on this topic, see the Knowledge Base article "Verity Custom1, Custom2 and Summary Fields" (ID# 1081) at
http://www.coldfusion.com/Support/KnowledgeBase/SearchForm.cfm.

The cfsearch tag returns the summary for each found document in the query variable search_query.Summary. For example, to add a summary for each search result returned by the collectionsearchaction.cfm page, change the cfoutput query tag as follows:

<cfoutput query="Search1">

  <a href="#Search1.URL#">#Search1.title#</a><br>

  #Summary#<br>

</cfoutput>

For information on an advanced summarization technique, see the Knowledge Base article "Verity: Synchronizing information stored in Verity Collection" (ID# 1116) at http://www.coldfusion.com/Support/KnowledgeBase/SearchForm.cfm.

cfsearch properties

Each cfsearch query object includes three variables that provide information about the query:

RecordCount The total number of records returned by the query.
CurrentRow The current row of the query being processed by cfoutput.
RecordsSearched The total number of records in the index that were searched. If no records were returned in the search, this property returns a null value.

Developing ColdFusion Applications
Indexing and Searching Data