NAME

lonsearchcat - LONCAPA Search Interface


SYNOPSIS

Search interface to LON-CAPAs digital library


DESCRIPTION

This module enables searching for a distributed browseable catalog.

This is part of the LearningOnline Network with CAPA project described at http://www.lon-capa.org.

lonsearchcat presents the user with an interface to search the LON-CAPA digital library. lonsearchcat also initiates the execution of a search by sending the search parameters to LON-CAPA servers. The progress of search (on a server basis) is displayed to the user in a seperate window.


Internals

Global variables
$importbutton
button to take the select results and go to group sorting

%groupsearch_db
Database hash used to save values for the groupsearch RAT interface.

$diropendb
The full path to the (temporary) search database file. This is set and used in &handler() and is also used in &output_results().

%Views
Hash which associates an output view description with the function that produces it. Adding a new view type should be as easy as adding a line to the definition of this hash and making sure the function takes the proper parameters.

$bodytag
LON-CAPA standard body tag, gotten from &Apache::lonnet::bodytag. No title, no table, just a <body> tag.

&handler() - main handler invoked by httpd child
Variables
$hidden
holds 'hidden' html forms

$scrout
string that holds portions of the screen output

&print_basic_search_form()
Returns a scalar which holds html for the basic search form.

&advanced_search_form()
Returns a scalar which holds html for the advanced search form.

&get_persistent_form_data
Inputs: filename of database

Outputs: returns undef on database errors.

This function is the reverse of &make_persistent() for form data. Retrieve persistent data from %persistent_db. Retrieved items will have their values unescaped. If a form value already exists in $ENV, it will not be overwritten. Form values that are array references may have values appended to them.

&get_persistent_data
Inputs: filename of database, ref to array of values to recover.

Outputs: array of values. Returns undef on error.

This function is the reverse of &make_persistent(); Retrieve persistent data from %persistent_db. Retrieved items will have their values unescaped. If the item contains commas (before unescaping), the returned value will be an array pointer.

&make_persistent()
Inputs: Hash of values to save, filename of persistent database.

Store variables away to the %persistent_db. Values will be escaped. Values that are array pointers will have their elements escaped and concatenated in a comma seperated string.

&make_form_data_persistent()
Inputs: filename of persistent database.

Store most form variables away to the %persistent_db. Values will be escaped. Values that are array pointers will have their elements escaped and concatenated in a comma seperated string.

HTML form building functions
&simpletextfield()
Inputs: $name,$value,$size

Returns a text input field with the given name, value, and size. If size is not specified, a value of 20 is used.

&simplecheckbox()
Inputs: $name,$value

Returns a simple check box with the given $name. If $value eq 'on' the box is checked.

&fieldtitle()
Input: $title

Returns a scalar with html which will display $title as a search field heading.

&searchphrasefield()
Inputs: $title,$name,$value

Returns html for a title line and an input field for entering search terms. The entry field (which is where the $name and $value are used) is a 50 column simpletextfield. The html returned is for a row in a three column table.

&searchphrasefield_with_related()
Inputs: $title,$name,$value

Returns html for a title line and an input field for entering search terms and a check box for 'related words'. The entry field (which is where the $name and $value are used) is a 50 column simpletextfield. The name of the related words checkbox is ``$name_related''.

&dateboxes()
Returns html selection form elements for the specification of the day, month, and year.

&selectbox()
Returns a scalar containing an html <select> form.

Inputs:

$title
Printed above the select box, in uppercase. If undefined, only a select box will be returned, with no additional html.

$name
The name element of the <select> tag.

$default
The default value of the form. Can be $anyvalue, or in @idlist.

$anyvalue
The <option value=``...''> used to indicate a default of none of the values. Can be undef.

$anytag
The text associate with $anyvalue above.

$functionref
Each element in @idlist will be passed as a parameter to the function referenced here. The return value of the function should be a scalar description of the items. If this value is undefined the description of each item in @idlist will be the item name.

@idlist
The items to be selected from. One of these or $anyvalue will be the value returned by the form element, $ENV{form.$name}.

&parse_advanced_search()
Parse advanced search form and return the following:
$query Scalar containing an SQL query.
$customquery Scalar containing a custom query.
$customshow Scalar containing commands to show custom metadata.
$libraries_to_query Reference to array of domains to search.
&parse_basic_search()
Parse the basic search form and return a scalar containing an sql query.

&related_version
Modifies an input string to include related words. Words in the string are replaced with parenthesized lists of 'OR'd words. For example ``torque'' is replaced with ``(torque OR word1 OR word2 OR ...)''.

Note: Using this twice on a string is probably silly.

&build_SQL_query()
Builds a SQL query string from a logical expression with AND/OR keywords using Text::Query and &recursive_SQL_query_builder()

&build_custommetadata_query()
Constructs a custom metadata query using a rather heinous regular expression.

&recursive_SQL_query_build()
Recursively constructs an SQL query. Takes as input $dkey and $pattern.

&build_date_queries()
Builds a SQL logic query to check time/date entries. Also reports errors (check for /^Incorrect/).

&copyright_check()
&ensure_db_and_table
Ensure we can get lonmysql to connect to the database and the table we need exists.

Inputs: $r, table id

Returns: undef on error, 1 if the table exists.

&print_sort_form
MySQL Table Description
MySQL table creation requires a precise description of the data to be stored. The use of the correct types to hold data is vital to efficient storage and quick retrieval of records. The columns must be described in the following format:

&create_results_table()
Creates the table of search results by calling lonmysql. Stores the table id in $ENV{'form.table'}

Inputs: none.

Returns: the identifier of the table on success, undef on error.

Search Status update functions
Each of the following functions changes the values of one of the input fields used to display the search status to the user. The names should be explanatory.

Inputs: Apache request handler ($r), text to display.

Returns: Nothing.

&update_count_status()
&update_status()
&update_seconds()
&revise_button
Inputs: None

Returns: html string for a 'revise search' button.

&run_search
&prev_next_buttons
&display_results
&catalogmode_output($title,$url,$fnum,$checkbox_num)
Returns html needed for the various catalog modes. Gets inputs from $ENV{'form.catalogmode'}. Stores data in %groupsearch_db.

&parse_row
Parse a row returned from the database.

&parse_raw_result()
Takes a line from the file of results and parse it. Returns a hash with keys for the following fields: 'title', 'author', 'subject', 'url', 'keywords', 'version', 'notes', 'abstract', 'mime', 'lang', 'owner', 'copyright', 'creationdate', 'lastrevisiondate'.

In addition, the following tags are set by calling the appropriate lonnet function: 'language', 'cprtag', 'mimetag'.

The 'title' field is set to ``Untitled'' if the title field is blank.

'abstract' and 'keywords' are truncated to 200 characters.

&handle_custom_fields()
&search_results_header
Output the proper html headers and javascript code to deal with different calling modes.

Takes most inputs directly from %ENV, except $mode.

$mode is either (at this writing) 'Basic' or 'Advanced'

The following environment variables are checked:

'form.catalogmode'
Checked for 'interactive' and 'groupsearch'.

'form.mode'
Checked for existance & 'edit' mode.

'form.form'
'form.element'
Metadata Viewing Functions
Output is a HTML-ified string. Input arguments are title, author, subject, url, keywords, version, notes, short abstract, mime, language, creation date, last revision date, owner, copyright, hostname, and extra custom metadata to show.
&detailed_citation_view()
&summary_view()
&compact_view()
&fielded_format_view()
&xml_sgml_view()
&filled() see if field is filled.
&output_blank_field_error()
Output a complete page that indicates the user has not filled in enough information to do a search.

Inputs: $r (Apache request handle), $closebutton, $parms.

Returns: nothing

$parms is extra information to include in the 'Revise search request' link.

&output_date_error()
Output a full html page with an error message.

Inputs:

    $r, the request pointer.
    $message, the error message for the user.
    $closebutton, the specialized close button needed for groupsearch.

&start_fresh_session()
Cleans the global %groupsearch_db by removing all fields which begin with 'pre_' or 'store'.