NAME

Apache::loncommon - pile of common routines


SYNOPSIS

Referenced by other mod_perl Apache modules.

Invocation: &Apache::loncommon::SUBROUTINENAME(ARGUMENTS);


INTRODUCTION

Common collection of used subroutines. This collection helps remove redundancy from other modules and increase efficiency of memory usage.

Current things done:

 Makes a table out of the previous homework attempts
 Inputs result_from_symbread, user, domain, course_id
 Reads in non-network-related .tab files

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

General Subroutines

Global Variables
%Keywords
A hash used by &keyword to determine if a word is considered a keyword.

$thesaurus_db_file
Scalar containing the full path to the thesaurus database.

BEGIN()
Initialize values from language.tab, copyright.tab, filetypes.tab, thesaurus.tab, and filecategories.tab.

browser_and_searcher_javascript
Returns scalar containing javascript to open a browser window or a searcher window. Also creates
openbrowser(formname,elementname,only,omit) [javascript]
inputs: formname, elementname, only, omit

formname and elementname indicate the name of the html form and name of the element that the results of the browsing selection are to be placed in.

Specifying 'only' will restrict the browser to displaying only files with the given extension. Can be a comma seperated list.

Specifying 'omit' will restrict the browser to NOT displaying files with the given extension. Can be a comma seperated list.

opensearcher(formname, elementname) [javascript]
Inputs: formname, elementname

formname and elementname specify the name of the html form and the name of the element the selection from the search results will be placed in.

linked_select_forms(...)
linked_select_forms returns a string containing a <script></script> block and html for two <select> menus. The select menus will be linked in that changing the value of the first menu will result in new values being placed in the second menu. The values in the select menu will appear in alphabetical order.

linked_select_forms takes the following ordered inputs:

$formname, the name of the <form> tag
$middletext, the text which appears between the <select> tags
$firstdefault, the default value for the first menu
$firstselectname, the name of the first <select> tag
$secondselectname, the name of the second <select> tag
$hashref, a reference to a hash containing the data for the menus.

Below is an example of such a hash. Only the 'text', 'default', and 'select2' keys must appear as stated. keys(%menu) are the possible values for the first select menu. The text that coincides with the first menu value is given in $menu{$choice1}->{'text'}. The values and text for the second menu are given in the hash pointed to by $menu{$choice1}->{'select2'}.

my %menu = ( A1 => { text =>``Choice A1'' , default => ``B3'', select2 => { B1 => ``Choice B1'', B2 => ``Choice B2'', B3 => ``Choice B3'', B4 => ``Choice B4'' } }, A2 => { text =>``Choice A2'' , default => ``C2'', select2 => { C1 => ``Choice C1'', C2 => ``Choice C2'', C3 => ``Choice C3'' } }, A3 => { text =>``Choice A3'' , default => ``D6'', select2 => { D1 => ``Choice D1'', D2 => ``Choice D2'', D3 => ``Choice D3'', D4 => ``Choice D4'', D5 => ``Choice D5'', D6 => ``Choice D6'', D7 => ``Choice D7'' } } );

help_open_topic($topic, $text, $stayOnPage, $width, $height)
Returns a string corresponding to an HTML link to the given help $topic, where $topic corresponds to the name of a .tex file in /home/httpd/html/adm/help/tex, with underscores replaced by spaces.

$text will optionally be linked to the same topic, allowing you to link text in addition to the graphic. If you do not want to link text, but wish to specify one of the later parameters, pass an empty string.

$stayOnPage is a value that will be interpreted as a boolean. If true, the link will not open a new window. If false, the link will open a new window using Javascript. (Default is false.)

$width and $height are optional numerical parameters that will override the width and height of the popped up window, which may be useful for certain help topics with big pictures included.

csv_translate($text)
Translate $text to allow it to be output as a 'comma seperated values' format.

get_domains()
Returns an array containing each of the domains listed in the hosts.tab file.

select_form($defdom,$name,%hash)
Returns a string containing a <select name='$name' size='1'> form to allow a user to select options from a hash option_name => displayed text. See lonrights.pm for an example invocation and use.

select_dom_form($defdom,$name,$includeempty)
Returns a string containing a <select name='$name' size='1'> form to allow a user to select the domain to preform an operation in. See loncreateuser.pm for an example invocation and use.

If the $includeempty flag is set, it also includes an empty choice (``no domain selected'');

get_library_servers($domain)
Returns a hash which contains keys like '103l3' and values like 'kirk.lite.msu.edu'. All of the keys will be for machines in the given $domain.

home_server_option_list($domain)
returns a string which contains an <option> list to be used in a <select> form input. See loncreateuser.pm for an example.

&decode_user_agent()
Inputs: $r

Outputs:

$httpbrowser
$clientbrowser
$clientversion
$clientmathml
$clientunicode
$clientos
authform_xxxxxx
The authform_xxxxxx subroutines provide javascript and html forms which handle some of the conveniences required for authentication forms. This is not an optimal method, but it works.

See loncreateuser.pm for invocation and use examples.

authform_header
authform_authorwarning
authform_nochange
authform_kerberos
authform_internal
authform_filesystem
get_auth_defaults
get_auth_defaults($target_domain) returns the default authentication type and an associated argument (initial password or a kerberos domain). These values are stored in lonTabs/domain.tab

($def_auth, $def_arg) = &get_auth_defaults($target_domain);

If target_domain is not found in domain.tab, returns nothing ('').

get_auth_defaults
get_kerberos_defaults
get_kerberos_defaults($target_domain) returns the default kerberos version and domain. If not found in domain.tabs, it defaults to version 4 and the domain of the server.

($def_version, $def_krb_domain) = &get_kerberos_defaults($target_domain);

get_kerberos_defaults
initialize_keywords
Initializes the package variable %Keywords if it is empty. Uses the package variable $thesaurus_db_file.

keyword($word)
Returns true if $word is a keyword. A keyword is a word that appears more than the average number of times in the thesaurus database. Calls &initialize_keywords

get_related_words
Look up a word in the thesaurus. Takes a scalar arguement and returns an array of words. If the keyword is not in the thesaurus, an empty array will be returned. The order of the words returned is determined by the database which holds them.

Uses global $thesaurus_db_file.

plainname($uname,$udom)
Gets a users name and returns it as a string in ``first middle last generation'' form

nickname($uname,$udom)
Gets a users name and returns it as a string as

``&quot;nickname&quot;''

if the user has a nickname or

``first middle last generation''

if the user does not

screenname($uname,$udom)
Gets a users screenname and returns it as a string

&determinedomain()
Inputs: $domain (usually will be undef)

Returns: Determines which domain should be used for designs

&domainlogo()
Inputs: $domain (usually will be undef)

Returns: A link to a domain logo, if the domain logo exists. If the domain logo does not exist, a description of the domain.

&designparm()
Inputs: $which parameter; $domain (usually will be undef)

Returns: value of designparamter $which

&bodytag()
Returns a uniform header for LON-CAPA web pages.

Inputs:

 $title, A title to be displayed on the page.
 $function, the current role (can be undef).
 $addentries, extra parameters for the <body> tag.
 $bodyonly, if defined, only return the <body> tag.
 $domain, if defined, force a given domain.
 $forcereg, if page should register as content page (relevant for 
            text interface only)

Returns: A uniform header for LON-CAPA web pages. If $bodyonly is nonzero, a string containing a <body> tag will be returned. If $bodyonly is undef or zero, an html string containing a <body> tag and other decorations will be returned.

CSV Upload/Handling functions

upfile_store($r)
Store uploaded file, $r should be the HTTP Request object, needs $ENV{'form.upfile'} returns $datatoken to be put into hidden field

load_tmp_file($r)
Load uploaded file from tmp, $r should be the HTTP Request object, needs $ENV{'form.datatoken'}, sets $ENV{'form.upfile'} to the contents of the file

upfile_record_sep()
Separate uploaded file into records returns array of records, needs $ENV{'form.upfile'} and $ENV{'form.upfiletype'}

record_sep($record)
Separate a record into fields $record should be an item from the upfile_record_sep(), needs $ENV{'form.upfiletype'}

upfile_select_html()
return HTML code to select file and specify its type

csv_print_samples($r,$records)
Prints a table of sample values from each column uploaded $r is an Apache Request ref, $records is an arrayref from &Apache::loncommon::upfile_record_sep

csv_print_select_table($r,$records,$d)
Prints a table to create associations between values and table columns. $r is an Apache Request ref, $records is an arrayref from &Apache::loncommon::upfile_record_sep, $d is an array of 2 element arrays (internal name, displayed name)

csv_samples_select_table($r,$records,$d)
Prints a table of sample values from the upload and can make associate samples to internal names.

$r is an Apache Request ref, $records is an arrayref from &Apache::loncommon::upfile_record_sep, $d is an array of 2 element arrays (internal name, displayed name)

check_if_partid_hidden($id,$symb,$udom,$uname)
Returns either 1 or undef

1 if the part is to be hidden, undef if it is to be shown

Arguments are:

$id the id of the part to be checked $symb, optional the symb of the resource to check $udom, optional the domain of the user to check for $uname, optional the username of the user to check for

Access .tab File Data

languageids()
returns list of all language ids

languagedescription()
returns description of a specified language id

copyrightids()
returns list of all copyrights

copyrightdescription()
returns description of a specified copyright id

filecategories()
returns list of all file categories

filecategorytypes()
returns list of file types belonging to a given file category

fileembstyle()
returns embedding style for a specified file type

filedescription()
returns description for a specified file type

filedescriptionex()
returns description for a specified file type with extra formatting

Alternate Problem Views

get_previous_attempt()
return string with previous attempt on problem

get_student_view()
show a snapshot of what student was looking at

get_student_answers()
show a snapshot of how student was answering problem

HTTP Helper

get_unprocessed_cgi($query,$possible_names)
Modify the %ENV hash to contain unprocessed CGI form parameters held in $query. The parameters listed in $possible_names (an array reference), will be set in $ENV{'form.name'} if they do not already exist.

Typically called with $ENV{'QUERY_STRING'} as the first parameter. $possible_names is an ref to an array of form element names. As an example: get_unprocessed_cgi($ENV{'QUERY_STRING'},['uname','udom']); will result in $ENV{'form.uname'} and $ENV{'form.udom'} being set.

cacheheader()
returns cache-controlling header code

no_cache($r)
specifies header code to not have cache

add_to_env($name,$value)
adds $name to the %ENV hash with value $value, if $name already exists, the entry is converted to an array reference and $value is added to the array.