ColdFusion Developer’s Guide phần 5 pot

ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 465 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 a collection. Creating a collection with the ColdFusion Administrator Use the following procedure to quickly create a collection with the ColdFusion Administrator: 1 In the ColdFusion Administrator, select Data & Services > Verity Collections. 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:\CFusion\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” on page 463. 5 (Optional) Select Enable Category Support to create a Verity Parametric collection. For more information on using categories, see “Narrowing searches by using categories” on page 476. 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. 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 collec- tions 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 programmatically or by using the ColdFusion Admin- istrator. Use the following guidelines to determine which method to use: ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 466 You c a n us e 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. 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 devel- opment 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 Admin- istrator 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 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 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:\CFusion\verity\collections\"> 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 Attribute Description action (Optional) The action to perform on the collection (create, delete, or optimize). The default value for the action attribute is list. For more information, see cfcollection in 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 The language. categories (Optional) Specifies that cfcollection create a Verity Parametric Index (PI) for this collection. By default, the categories attribute is set to False. To create a collection that uses categories, specify Yes. ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 467 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. 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. 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:\CFusion\verity\collections\"> <p>The collection #Form.CollectionName# is created.</p> </cfcase> <cfcase value="Optimize"> <cfcollection action="Optimize" ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 468 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 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. Indexing a collection by using the cfindex tag You can index a collection in CFML by using the cfindex tag, which eliminates the need to use the ColdFusion Administrator. The cfindex tag populates the collection with metadata that is then used to retrieve search results. You c a n us e t h e 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 by using the ColdFusion Administrator, or the cfcollection tag. For more information, see “Creating a collection with the ColdFusion Administrator” on page 465, or “Creating a collection with the cfcollection tag” on page 466. When using the cfindex tag, the following attributes correspond to the values that you would enter by using the ColdFusion Administrator to index a collection: Attribute Description collection The name of the collection. action Specifies what the cfindex tag should do to the collection. The default action is to update the collection, which generates a new index. Other actions are to delete, purge, or refresh the collection. type Specifies the type of files or other data to which the cfindex tag applies the specified action. The value you assign to the type attribute determines the value to use with the key attribute (see the following list). When you enter a value for the type attribute, cfindex expects a corresponding value in the key attribute. For example, if you specify type=file, cfindex expects a directory path and filename for the key attribute. The type attribute has the following possible values: • file: Specifies a directory path and filename for the file that you are indexing. • path: Specifies a directory path that contains the files that you are indexing. • custom: Specifies custom data, such as a record set returned from a query. ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 469 You can use form and action pages similar to the following examples to select and index a collection. 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 you do when you index a collection. extensions (Optional) The delimited list of file extensions that ColdFusion uses to index files if type="path". key The value that you specify for the key attribute depends on the value set for the type attribute: • If type="file", the key is the directory path and filename for the file you are indexing. • If type="path", the key is the directory path that contains the files you are indexing. • If type="custom", the key is a unique identifier specifying the location of the documents you are indexing; for example, the URL of a specific web page or website whose contents you want to index. If you are indexing data returned by a query (from a database for example), the key is the name of the record set column that contains the primary key. URLpath (Optional) The URL path for files if type="file" and type="path". When the collection is searched with the cfsearch tag, ColdFusion works as follows: • type="file": The URLpath attribute contains the URL to the file. • type="path": The path name is automatically prefixed to filenames and returned as the URLpath attribute. recurse (Optional) Yes or No. If type = "path" , Yes specifies that directories below the path specified in the key attribute are included in the indexing operation. language (Optional) The language of the collection. The default language is English Basic. To learn more about support for languages, see “Specifying a language” on page 463. Attribute Description ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 470 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:\CFusion\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” on page 480. Indexing a collection with the ColdFusion Administrator As an alternative to programmatically indexing a collection, use the following procedure to index a collection with the ColdFusion Administrator. 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. ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 471 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” on page 463. 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. Creating a search page You use the cfsearch tag to search an indexed collection. Searching a Verity collection is similar to a standard ColdFusion query: both use a dedicated ColdFusion tag that requires a name attribute for their searches and both return a query object that contains rows matching the search criteria. The following table compares the two tags: Note: You receive an error if you attempt to search a collection that has not been indexed. The following are important attributes for the cfsearch tag: Each cfsearch returns variables that provide the following information about the search: cfquery cfsearch Searches a data source Searches a collection Requires a name attribute Requires a name attribute Uses SQL statements to specify search criteria Uses a criteria attribute to specify search criteria Returns variables keyed to database table field names Returns a unique set of variables Uses cfoutput to display query results Uses cfoutput to display search results Attribute Description name The name of the search query. collection The name of the collection(s) being searched. Separate multiple collections with a comma; for example, collection = "sprocket_docs,CodeColl". criteria The search target (can be dynamic). maxrows The maximum number of records returned by the search. Always specify this attribute to ensure optimal perfor- mance (start with 300 or less, if possible). Attribute Description RecordCount The total number of records returned by the search. CurrentRow The current row of the record set. RecordsSearched The total number of records in the index that were searched. If no records were returned in the search, this prop- erty returns a null value. ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 472 Additionally, if you specify the status attribute, the cfsearch tag returns the status structure, which contains the information in the following table: You can use search form and results pages similar to the following examples to search a collection. Create a search form 1 Create a ColdFusion page with the following content: <html> <head> <title>Searching a collection</title> </head> <body> <h2>Searching a collection</h2> <form method="post" action="collection_search_action.cfm"> <p>Enter search term(s) in the box below. You can use AND, OR, NOT, and parentheses. Surround an exact phrase with quotation marks.</p> <p><input type="text" name="criteria" size="50" maxLength="50"> </p> <input type="submit" value="Search"> </form> </body> </html> 2 Save the file as collection_search_form.cfm. Enter search target words in this form, which ColdFusion passes as the variable criteria to the action page, which displays the search results. Create the results page 1 Create a ColdFusion page with the following content: <html> <head> <title>Search Results</title> </head> <body> <cfsearch name = "codecoll_results" collection = "CodeColl" Summary Automatic summary saved by the cfindex tag. Context A context summary that contains the search terms, highlighted in bold (by default). This is enabled if you set the contextpassages attribute to a number greater than zero. Variable Description found The number of documents that contain the search criteria. searched The number of documents searched. Corresponds to the recordsSearched column in the search results. time The number of milliseconds the search took, as reported by the Verity K2 search service. suggestedQuery An alternative query, as suggested by Verity, that may produce better results. This often contains corrected spell- ings of search terms. Present only when the suggestions tag attribute criteria is met. Keywords A structure that contains each search term as a key to an array of up to five possible alternative terms in order of preference. Present only when the suggestions tag attribute criteria is met. Attribute Description ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 473 criteria = "#Form.criteria#" contextPassages = "1" contextBytes = "300" maxrows = "100"> <h2>Search Results</h2> <cfoutput> Your search returned #codecoll_results.RecordCount# file(s). </cfoutput> <cfoutput query="codecoll_results"> <p> File: <a href="#URL#">#Key#</a><br> Document Title (if any): #Title#<br> Score: #Score#<br> Summary: #Summary#<br> Highlighted Summary: #context#</p> </cfoutput> </body> </html> 2 Save the file as collection_search_action.cfm. 3 View collection_search_form.cfm in the web browser. 4 Enter a target word(s) and click Search. Note: As part of the indexing process, Verity automatically produces a summary of every document file or every query record set that gets indexed. The default summary result set column selects the best sentences, based on internal rules, up to a maximum of 500 characters. Every cfsearch operation returns summary information by default. For more information on this topic, see “Using Verity Search Expressions” on page 488. Alternatively, you can use the context result set column, which provides a context summary with highlighted search terms. Enhancing search results ColdFusion lets you enhance the results of searches by letting you incorporate search features that let users more easily find the information they need. Verity provides the following search enhancements: • Highlighting search terms • Providing alternative spelling suggestions • Narrowing searches using categories Highlighting search terms Term highlighting lets users quickly scan retrieved documents to determine whether they contain the desired infor- mation. This can be especially useful when searching lengthy documents, letting users quickly locate relevant infor- mation returned by the search. To implement term highlighting, use the following cfsearch attributes in the search results page: ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 474 The following example adds to the previous search results example by highlighting the returned search terms with bold type. Create a search results page that includes term highlighting 1 Create a ColdFusion page with the following content: <html> <head> <title>Search Results</title> </head> <body> <cfsearch name = "codecoll_results" collection = "CodeColl" criteria = "#Form.Criteria#"> ContextHighlightBegin="<b>" ContextHighlightEnd="</b>" ContextPassages="1" ContextBytes="500" maxrows = "100"> <h2>Search Results</h2> <cfoutput> Your search returned #codecoll_results.RecordCount# file(s). </cfoutput> <cfoutput query="codecoll_results"> <p> File: <a href="#URL#">#Key#</a><br> Document Title (if any): #Title#<br> Score: #Score#<br> Summary: #Summary#<br> Highlighted Summary: #context#</p> </cfoutput> </body> </html> 2 Save the file as collection_search_action.cfm. Note: This overwrites the previous ColdFusion example page. 3 View collection_search_form.cfm in the web browser: 4 Enter a target word(s) and click Search. Providing alternative spelling suggestions Many unsuccessful searches are the result of incorrectly spelled query terms. Verity can automatically suggest alter- native spellings for misspelled queries using a dictionary that is dynamically built from the search index. Attributes Description ContextHighlightBegin Specifies the HTML tag to prepend to the search term within the returned documents. This attribute must be used in conjunction with ContextHighlightEnd to highlight the resulting search terms. The default HTML tag is <b>, which highlights search terms using bold type. ContextHighlightEnd Specifies the HTML tag to append to the search term within the returned documents. ContextPassages The number of passages/sentences Verity returns in the context summary (the context column of the results). The default value is 0; this disables the context summary. ContextBytes The total number of bytes that Verity returns in the context summary. The default is 300 bytes. [...]... #Project_Docs# 2 Save the file as indexdir.cfm in the myapps directory The ColdFusion cfindex tag indexes the contents of the specified directory path Search and display the directory path 1 Create a ColdFusion page that contains the following content: ADOBE COLDFUSION 8 4 85 ColdFusion Developer’s Guide Your collection now includes the following items: #Emp_ID# #FirstName# #LastName# #Contract_File# Your search returned #getEmps.RecordCount# file(s)... name="collection" default="test-pi"> Collection Name: ADOBE COLDFUSION 8 478 ColdFusion Developer’s Guide Category: CategoryTree: Search: . ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 4 65 Creating a search tool for ColdFusion applications There are three main tasks in creating a search tool for your ColdFusion application: 1. programmatically or by using the ColdFusion Admin- istrator. Use the following guidelines to determine which method to use: ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 466 You c a n us e cfcollection. language” on page 463. Attribute Description ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 470 Use cfindex to index a collection 1 Create a ColdFusion page with the following content: <html> <head> <title>Creating