Developing ColdFusion MX Applications with CFML
Building a Search Interface

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 Administrator to create and index the collection. Also, ColdFusion Studio has a Verity Wizard that generates ColdFusion pages that index the collection and design a search interface. The following table summarizes the steps and available methods for creating the search tool:

Step	CFML	ColdFusion MX Administrator	Verity Wizard
Creating a collection	Yes	Yes	No
Indexing a collection	Yes	Yes	Yes
Designing a search interface	Yes	No	Yes

This chapter presents the non-code methods for developing a search tool, followed by code examples that perform the same task. If you have ColdFusion Studio and access to the ColdFusion Administrator, the fastest development method is as follows:

1. Create the collection with the ColdFusion Administrator.
2. Use the Verity Wizard to index the collection and design a search interface.

Creating a collection with the ColdFusion MX Administrator

Use the following procedure to quickly create a collection with the ColdFusion 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:\cfusionmx\verity\collections\.

   By default, ColdFusion stores collections in \cf_root\verity\collections\ in Windows and in /cf_root/verity/collections in UNIX.

   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.
5. Click Create Collection.

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

   

   Note:   You can map a collection currently available on your network or local disk by creating a local reference (an alias) for that collection. In this procedure, enter the collection alias as the collection name, and enter a UNC (Universal Naming Convention) path to the folder for the collection.

You have successfully created a collection, DemoDocs, that currently has no data. 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

A new collection is an empty shell that must be indexed before you search it. The indexing procedure also populates the collection with data contained in the collection's files. Similar to creating a collection, you can index a collection either in the ColdFusion Administrator or programmatically.

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

Use the following guidelines to determine which method to use:

Use the Administrator	Use the cfindex tag
To index document files	To index ColdFusion query results
When the collection does not require frequent updates	When the collection requires frequent updates
To create the collection without writing any CFML code	To dynamically update a collection from a ColdFusion application page
To create a collection once	When the collection requires updating by others

The cfcollection tag has the following action attribute values that can fix or improve your index:

• repair  Repairs the internal index files of a collection. This might take a few minutes for large collections.
• optimize  Optimizes a collection. Use this if you notice that your searches on a collection take longer than 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 reindex 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 Administering ColdFusion MX.

Indexing and building a search interface with the Verity Wizard

If you have ColdFusion Studio, you can use the Verity Wizard to generate a basic search and index interface. Use the following procedure to quickly create a search application for a collection. This procedure assumes the following:

• There is an empty Verity collection to hold the indexed data. For details on how to use the ColdFusion Administrator to create a collection, see "Creating a collection with the ColdFusion MX Administrator".
• A directory contains files of several types, such as text, word processing, spreadsheet, and HTML. If this directory is within your web_root, then you can view the files from the web browser.
• Some of these files contain a search target word(s).
• There is an available directory to hold the four ColdFusion pages that the wizard generates.

To build a search interface using the Verity Wizard:

1. In ColdFusion Studio, select File > New.
2. In the New Document window, click the CFML tab.
3. Double-click the Verity Wizard.

   The Verity Application window appears:

   

4. Enter the following information:

   Field	Description	Example
   Title	Appears at the top of each generated ColdFusion page.	Search CF Documentation
   Directory	Contains the generated ColdFusion pages. The directory should be under your web_root so that you can view ColdFusion pages in the web browser.	web_root\vw_generated

5. Click Next.

   The Select Collection window appears:

   

6. Enter the following information:

   Field	Description	Example
   Collection Name	The name of the collection you created in the ColdFusion Administrator (or by using the cfcollection tag).	DemoDocs
   Language	The language used to create the collection (English is the default).	english

7. Click Next.

   The Indexing Settings window appears:

   

8. Enter the following information:

   Field	Description	Example
   Directory Path	The directory that contains the documents to be indexed.	C:\CFusionMX\wwwroot\cfdocs
   Recursively Index Subdirectories	(Optional) Extends the indexing operation to all directories below the selected path.	enabled (default)
   File Extensions	The type(s) of files to index. Use a comma to separate multiple file types.	.htm, .html, .xml
   Return URL	(Optional) If your documents are beneath the web_root, enter a URL that corresponds to the Directory Path.	http://127.0.0.1:8500/cfdocs/

9. Click Finish.

   The wizard generates four ColdFusion pages to the directory you specified in step 4, and displays an output summary:

   

   Note:   The file names are in the format pagetitle_Vpagename.cfm, where pagetitle is the value you specified in step 4 and pagename is SearchForm, SearchResult, OpenFile, or PathIndexing.

10. Click Close.

    The wizard closes and the files open in ColdFusion Studio (you can adjust its size to display all file tabs).

11. Browse the SearchForm page in ColdFusion Studio.

    Alternatively, you can use the web browser; if you do so, enter an HTTP URL that corresponds to your SearchForm, such as:
    http://127.0.0.1:8500/vw_generated/SearchCFDocumentation_VSearchForm.cfm:

    

12. Click the Index link at the bottom of the page.

    A confirmation message appears when indexing successfully completes.

13. Click the web browser's back button to return to the search form.
14. Enter your search term(s); for example, Verity AND data source.

    Tip:   For more information on the Verity search syntax, see "Using Verity Search Expressions".

15. Click Search.

    In ColdFusion Studio 4.x, the following compilation error might display:

    Invalid parser construct found on line 46 at position 49. ColdFusion was looking at the following text:'

    To correct this error, do the following:

    1. In ColdFusion Studio, open the SearchResult page in Edit mode; for example, WizardDocDemo_VSearchResult.cfm.
    2. In line 46, delete the pound signs that precede the hexadecimal color codes. The correct code is:

       <TR bgcolor="#IIf(CurrentRow Mod 2, DE('FFFFFF'), DE('FFFFCF'))#">

    3. Save the file.
    4. Browse the SearchForm page and enter the search target.

       Your search results appear:

       

       If you entered a Return URL value and your documents are beneath your web_root (as in this procedure), you can click the link to open them.

You now have Verity search capability for your ColdFusion application. You can edit the generated ColdFusion pages or copy the generated code into the current pages to better integrate with your application.

You can create a search interface without using the Verity Wizard. The remainder of this chapter describes how to write CFML code that is functionally identical to the pages generated by the wizard. You can write the code using your text editor and preview it in the web browser.

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:

• action  (Optional) The action to perform on the collection (create, delete, repair, or optimize). The default value for the action attribute is list. For more information, see CFML Reference.
• collection  The name of the new collection, or the name of a collection upon which you will perform an action.
• path  The location for the Verity collection.
• language  (Optional) The language used to create the collection (English, by default).

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

<cfcollection action = "create"

  collection = "a_new_collection"
  path = "c:\CFusionMX\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="Repair">Repair<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:\cfusionmx\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>
   

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://127.0.0.1/myapps/collection_create_form.cfm

   The following figure shows how the output appears:

   

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

   The name and full path of the new collection appears in the list of Connected 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. When using this tag, the following attributes correspond to values entered in the ColdFusion MX Administrator:

• collection  The name of the collection. If you are indexing an external collection (external = "Yes"), you must also specify the fully qualified path for the collection.
• action  (Optional) Can be update (the default action), delete, purge, or refresh.
• extensions  (Optional) The delimited list of file extensions that ColdFusion uses to index files if type="Path".
• key  (Optional) The path containing the files you are indexing if type="path".
• URLpath  (Optional) The URL path for files if type="file" and type="path". When the collection is searched with cfsearch, the pathname is automatically prefixed to filenames and returned as the url attribute.
• recurse  (Optional) Yes or No. Yes specifies, if type = "Path", that directories below the path specified in the key attribute are included in the indexing operation.
• language  (Optional) The language of the collection. English is the default.

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>
   
     <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 will 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.IndexDir#"
     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://127.0.0.1/myapps/collection_index_form.cfm

   The following figure shows how the output appears:

   

4. Enter a collection name; for example, CodeColl.
5. Enter a file location; for example, C:\CFusionMX\wwwroot\vw_files.
6. Click Index.

   A confirmation message appears upon successful completion.

Note:   For information about using the cfindex tag with a database to index a collection, see "Using database-directed indexing".

Indexing a collection with the ColdFusion Administrator

As an alternative to programmatically indexing a collection and to using the Verity Wizard, use the following procedure to quickly index a collection with the ColdFusion Administrator.

To use ColdFusion Administrator to index a collection:

1. In the list of Connected Verity Collections, select a collection name; for example, CodeColl.
2. Click Index to open the index page.
3. For File Extensions, enter the type(s) 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 "Support for international languages".

8. Click Submit Changes.

   The indexing process. 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.

Copyright © 2002, Macromedia Inc. All rights reserved.

Comments