[LON-CAPA-cvs] cvs: loncom /html/adm/help/tex Institutional_Integration_Course_Codes.tex

[raeburn]

raeburn		Mon Jul 28 19:14:54 2008 EDT

  Added files:                 
    /loncom/html/adm/help/tex	
                             	Institutional_Integration_Course_Codes.tex 
  Log:
  - Documening localenroll::instcode_format() and localenroll::instcode_defaults().
  
  

Index: loncom/html/adm/help/tex/Institutional_Integration_Course_Codes.tex
+++ loncom/html/adm/help/tex/Institutional_Integration_Course_Codes.tex
\label{Institutional_Integration_Course_Codes}
Courses in a domain can be self-cataloging if assigned an institutional
code. For this to work, two routines need to be customized in localenroll.pm
- \emph{instcode\_format()} and \emph{instcode\_defaults()}. The first
of these is used to split institutional course codes into their constituent
parts, and to populate some perl data structures with these data.
LON-CAPA will use these perl structures to generate linked select boxes 
which can be used when searching the {}``official'' course catalog.
The second routine is used when constructing a regular expression for  
retrieval of courses based on search criteria specified by the user via the
linked select boxes. The search criteria are combined with defaults for any
components not explicitly selected (the defaults are fragments of a generic 
institutional code) to create the regular expression used in the course search.

\textbf{\large instcode\_format} 

Six arguments are required:

\begin{enumerate}
\item domain (\$dom)
\item reference to hash of institutional course IDs (\$instcodes)
\item reference to hash of codes (\$codes)
\item reference to array of titles (\$codetitles), e.g., @\{\$codetitles\}
= (\char`\"{}year\char`\"{},\char`\"{}semester\char`\"{},\char`\"{}department\char`\"{},\char`\"{}number\char`\"{})
\item reference to hash of abbreviations used in categories, (\$cat\_titles)
e.g., 

\begin{quote}
\%\{\$\$cat\_titles\{'Semester'\}\} = (
\begin{quote}
fs => 'Fall',

ss => 'Spring',

us => 'Summer');
\end{quote}
\end{quote}
\item reference to hash of arrays specifying sort order used in category
titles (\$cat\_order), e.g., @\{\$\$cat\_order\{'Semester'\}\} = ('ss','us','fs'); 
\end{enumerate}
The routine returns 'ok' if no errors occurred.

At MSU, {}``fs03nop590'' is an example of an institutional course
code; including the following entry in the instcodes hash passed in
by reference - \$\$instcodes\{'43551dedcd43febmsul1'\} = 'fs03nop590'
would cause the \$codes perl data structure to be populated.

fs03nop590 would be split as follows:

\$\$codes\{'year'\} = '2003'

\$\$codes\{'semester'\} = 'Fall'

\$\$codes\{'department'\} = 'nop'

\$\$codes\{'number'\} = '590'

The routine used at MSU is as follows:

\begin{quotation}
\texttt{sub instcode\_format \{}
\begin{quotation}
\texttt{my (\$dom,\$instcodes,\$codes,\$codetitles,\$cat\_titles,\$cat\_order)
= @\_;}

\texttt{@\{\$codetitles\} = (\char`\"{}Year\char`\"{},\char`\"{}Semester\char`\"{},\char`\"{}Department\char`\"{},\char`\"{}Number\char`\"{});}

\texttt{\%\{\$\$cat\_titles\{'Semester'\}\} = (}
\begin{quotation}
\texttt{fs => 'Fall',}

\texttt{ss => 'Spring',}

\texttt{us => 'Summer'}
\end{quotation}
\texttt{);}

\texttt{@\{\$\$cat\_order\{'Semester'\}\} = ('ss','us','fs');}

\texttt{foreach my \$cid (keys \%\{\$instcodes\}) \{}
\begin{quotation}
\texttt{if (\$\$instcodes\{\$cid\} =\~{} m/^({[}suf]s)(\textbackslash{}d\{2\})(\textbackslash{}w\{2,3\})(\textbackslash{}d\{3,4\}\textbackslash{}w?)\$/)
\{}
\begin{quotation}
\texttt{\$\$codes\{\$cid\}\{'Semester'\} = \$1;}

\texttt{\$\$codes\{\$cid\}\{'Department'\} = \$3;}

\texttt{\$\$codes\{\$cid\}\{'Number'\} = \$4;}

\texttt{my \$year = \$2;}

\texttt{my \$numyear = \$year;}

\texttt{\$numyear =\~{} s/^0//;}

\texttt{\$\$codes\{\$cid\}\{'Year'\} = \$year;}

\texttt{unless (defined(\$\$cat\_titles\{'Year'\}\{\$year\})) \{}
\begin{quotation}
\texttt{\$\$cat\_titles\{'Year'\}\{\$year\} = 2000 + \$numyear;}
\end{quotation}
\texttt{\}}
\end{quotation}
\texttt{\}}
\end{quotation}
\texttt{\}}

\texttt{my \$outcome = 'ok';}

\texttt{return \$outcome;}
\end{quotation}
\texttt{\}}
\end{quotation}
\textbf{\large instcode\_defaults}{\large \par}

Three arguments are required:

\begin{enumerate}
\item domain (\$dom)
\item reference to hash which will contain default regular expression matches
for different components of an institutional course code


(\$defaults)

\item reference to array which will contain order of component parts used
in institutional code. (\$code\_order)
\end{enumerate}
The routine returns 'ok' if no errors occurred.

At MSU , the regaular expression fragments used mirror those included
in the regular expression used in instcode\_format() to split an institutional
course code into its component parts.

\begin{quotation}
\texttt{sub instcode\_defaults \{}
\begin{quotation}
\texttt{my (\$dom,\$defaults,\$code\_order) = @\_;}

\texttt{\%\{\$defaults\} = (}
\begin{quotation}
\texttt{'Year' => '\textbackslash{}d\{2\}',}

\texttt{'Semester' => '^{[}sfu]s',}

\texttt{'Department' => '\textbackslash{}w\{2,3\}',}

\texttt{'Number' => '\textbackslash{}d\{3,4\}\textbackslash{}w?',}
\end{quotation}
\texttt{);}

\texttt{@\{\$code\_order\} = ('Semester','Year','Department','Number');}

\texttt{return 'ok';}
\end{quotation}
\texttt{\}}
\end{quotation}