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

[lira]

lira		Wed Aug 14 03:30:51 2013 EDT

  Added files:                 
    /loncom/html/adm/help/tex	Authoring_Library_Scripts.tex 
  Log:
  initial commit
  
  

Index: loncom/html/adm/help/tex/Authoring_Library_Scripts.tex
+++ loncom/html/adm/help/tex/Authoring_Library_Scripts.tex
\label{Authoring_Library_Scripts}

A LON-CAPA .library file can contain just a script block, or just
response items, or both.  A LON-CAPA problem can import as many published library 
files as desired. A .library file always starts with a $<$library$>$ tag, and 
always ends with a $<$/library$>$ tag.\index{library}

\null
\noindent \textbf{Storing entire scripts}

Entire scripts can be stored in a library file. The entire script can then be imported
into a problem file. \index{library}\index{random\_permutation}

\null
\noindent Library file:
\begin{verbatim}
<library>
<script type="loncapa/perl">
@alpha=('A','B','C','D',);
$seed=&random(1,1000000,1);
@alpha=&random_permutation($seed, at alpha); #scramble order
$letter = $alpha[0]; #select first element
</script>
</library>
\end{verbatim}

\noindent Problem file:
\begin{verbatim}
<problem>
<import id="15">randomletter.library</import>
<startouttext />The random letter is $letter.<endouttext />
<!-- other problem tags could go here -->
</problem>
\end{verbatim}

\null
\noindent \textbf{Storing a portion of a script}

A portion of a script, such as a large data array can be stored in a library file.

\null 
\noindent Library file:
\begin{verbatim}
<library>
<script type="loncapa/perl">
@alpha=('A','B','C','D',);
$seed=&random(1,1000000,1);
@alpha=&random_permutation($seed, at alpha); #scramble order
</script>
</library>
\end{verbatim}

\noindent Problem file: (note the $<$script$>$ tag is repeated and other
script calculations can be done using variables from the library file.)
\begin{verbatim}
<problem>
<import id="15">randomletter.library</import>
<script type="loncapa/perl">
$letter = $alpha[0];
</script>
<startouttext />The random letter is $letter.<endouttext />
<!-- other problem tags could go here. -->
</problem>
\end{verbatim}

\null
\noindent \textbf{Storing a subroutine}

Another use of a .library file is to define a subroutine which you plan
to call in a number of instances, e.g., (see notes below about browsing libraries
in the repository to see the contents of this subroutine)

\begin{verbatim}
/res/msu/raeburn/cleaneq.library
\end{verbatim}

Here is some example XML problem code
which makes a call to the \&cleaneq() routine defined in the library file, passing
some arguments: \$eq,'x','y','z' in the call to the routine.

\begin{verbatim}
<problem>
<import id="15">/res/msu/raeburn/cleaneq.library</import>

<script type="loncapa/perl">
$eq = "1x + 0y +-7z --3";
$eq2 = &cleaneq($eq,'x','y','z');</script>
<startouttext />Here is an example equation:<br />
Without cleaneq: $eq<br />
With cleaneq: $eq2<endouttext />
</problem>
\end{verbatim}

\null
\noindent \textbf{Assigning random problems using libraries}
Libraries can be used to store alternative parts of problems which are
selected with the $<$randomlist$>$ tag.\index{randomlist}\index{randomizing parts}
The .library file
hold the all content that would normally appear inside the $<$part$>$ tag.
\begin{verbatim}
<part id="11">
<randomlist show="1">
<import id="12">sample1.library< /import>
<import id="13">sample2.library< /import>
<import id="14">sample3.library< /import>
< /randomlist>
< /part>
<part id="15">
<randomlist show="1">
<import id="16">sample4.library< /import>
<import id="17">sample5.library< /import>
<import id="18">sample6.library< /import>
< /randomlist>
< /part>
\end{verbatim}

Note: when using $<$randomlist$>$, always put the randomlist tag \textit{inside}
the $<$part$>$ tag. If multiple $<$part$>$ tags are inside a $<$randomlist$>$, then
the grading and course management will be more difficult.

\null 
\noindent \textbf{Viewing the text contents of a library script block}

If you click on a .library file when browsing the shared content
repository, and the .library file contains just a script block, then
nothing will be displayed in the pop-up window.

The code is viewable if the author has enabled access to the source
XML when publishing a .library item that is pure script block.  If that
is done, then when a user checks the ``Source Available'' checkbox when
browsing the shared content pool, a link will be displayed for items
with available source code. Clicking the ``Source Code'' link for
any such items will open a pop-up which displays the content of the library
file. It is good practice to enable access to the source code when publishing any 
library that will be shared. Otherwise, users cannot see it.

\null
\noindent \textbf{Viewing variables from a library script during testing}

When viewing a problem in the problem testing mode of Authoring Space, 
you will see a separate
Script Vars link at the bottom of the testing area for each script block 
(either a block included directly
within the file, or a block included within a library file imported into
a problem). By clicking the respective link, you can view variable values from
the respective script.\index{script variables, viewing}

\null
\noindent \textbf{Accessing submissions from a problem part loaded from a library}

When *response items (e.g., *response is a wildcard such as optionresponce, 
stringresponse, numericalresponse, etc.)\index{*response} are defined in a
library file, this results in an extra id item in the identifier
required in \&EXT() \index{\&EXT}functions, e.g., if a problem contains two parts with
ids of a and b respectively, and the *reponse items have ids of 11 and
12 respectively, and the id of the $<$import$>$ for the .library is 15, the
most recent submissions could be retrieved with the following \&EXT() calls.\index{\&EXT}

\&EXT('user.resource.resource.a.15\_11.submission');

\&EXT('user.resource.resource.b.15\_12.submission');