[LON-CAPA-cvs] cvs: loncom /html/adm/help/tex About_Communication.tex About_Developers_Manual.tex Authentication.tex Cascading_Parameters.tex Chatting.tex Developer_Manual_Title_Page.tex Developer_Tutorial.tex Finding_Resources.tex Guts_Apache.tex Guts_Apache_Env.tex Guts_Apache_Modules.tex Guts_Authentication.tex Guts_Authoring.tex Guts_Coding_Guidelines.tex Guts_Course_Dir.tex Guts_User_Dir.tex Resource_Discussion.tex Roles_About.tex What_Is_LON-CAPA.tex Why_LON-CAPA.tex
bowersj2
lon-capa-cvs@mail.lon-capa.org
Wed, 20 Aug 2003 16:17:40 -0000
This is a MIME encoded message
--bowersj21061396260
Content-Type: text/plain
bowersj2 Wed Aug 20 12:17:40 2003 EDT
Added files:
/loncom/html/adm/help/tex About_Communication.tex
About_Developers_Manual.tex
Authentication.tex
Cascading_Parameters.tex Chatting.tex
Developer_Manual_Title_Page.tex
Developer_Tutorial.tex
Finding_Resources.tex Guts_Apache.tex
Guts_Apache_Env.tex
Guts_Apache_Modules.tex
Guts_Authentication.tex
Guts_Coding_Guidelines.tex
Guts_Course_Dir.tex Guts_User_Dir.tex
Resource_Discussion.tex Roles_About.tex
What_Is_LON-CAPA.tex Why_LON-CAPA.tex
Modified files:
/loncom/html/adm/help/tex Guts_Authoring.tex
Log:
Adding some .tex files in. (LPML addition later; still some to go.)
--bowersj21061396260
Content-Type: text/plain
Content-Disposition: attachment; filename="bowersj2-20030820121740.txt"
Index: loncom/html/adm/help/tex/Guts_Authoring.tex
diff -u loncom/html/adm/help/tex/Guts_Authoring.tex:1.1 loncom/html/adm/help/tex/Guts_Authoring.tex:1.2
--- loncom/html/adm/help/tex/Guts_Authoring.tex:1.1 Thu Jul 24 22:16:12 2003
+++ loncom/html/adm/help/tex/Guts_Authoring.tex Wed Aug 20 12:17:40 2003
@@ -1,32 +1,39 @@
\label{Guts_Authoring}
\subsection{Content Re-usage and Granularity}
-Any faculty participating in the Network can publish their own learning
-resources into the common pool. To that end, the Network provides
-a {}``construction space''\index{construction space} which is only
-accessible to the author, and a publication process, which transfers
-the material to the shared pool. During the publication process, metadata
-about the resource is gathered, and system-wide update notification
-and versioning mechanisms are triggered.
-
-Learning resources could be simple paragraphs of text, movies, applets,
-individualizing homework problems, etc. In addition to providing a
-distributed digital library with mechanisms to store and catalog these
-resources, the Network enables faculty to combine and sequence these
-resources at several levels: An instructor from Community College
-\textbf{A} could combine a text paragraph from University \textbf{B}
-with a movie from College \textbf{C} and an online homework problem
-from Publisher \textbf{D}, to form one page. Another instructor from
-High School \textbf{E} can take that page from Community College \textbf{A}
-and combine it with other pages into a module, unit or chapter. Those
-in turn can be combined into whole coursepacks. Faculty can design
-their own curricula from existing and newly created resources instead
-of having to buy into a complete off-the-shelf product.
+% Replace this with stuff from LyX
+
+{}``Resources''\index{resources} are the atomic unit of content in
+LON-CAPA. Learning resources could be simple paragraphs of text,
+movies, applets, individualizing homework problems, etc. Any faculty
+member can use their {}``construction space''\index{construction
+space} to create or upload their resources, either into the common
+pool or with highly selective access controls.
+
+LON-CAPA was designed from the beginning to support collaboration and
+using resources that may be distributed all across the planet. For
+each resource in the LON-CAPA network, LON-CAPA track metadata about
+that resource, provides versioning of the resource, and provides
+automatic subscription and change notification mechanisms. Thus, you
+can freely use resources from other institutions, and you can either
+tell LON-CAPA to always give you a given version of a resource if
+you're happy with it, or allow the system to automatically propagate
+changes to you.
+
+For example, an instructor from Community College \textbf{A} could
+combine a text paragraph from University \textbf{B} with a movie from
+College \textbf{C} and an online homework problem from Publisher
+\textbf{D}, to form one page. Another instructor from High School
+\textbf{E} can take that page from Community College \textbf{A} and
+combine it with other pages into a module, unit or chapter. Those in
+turn can be combined into whole course packs. Faculty can design their
+own curricula from existing and newly created resources instead of
+having to buy into a complete off-the-shelf product.
%
\begin{figure}
\begin{center}\includegraphics[%
- width=0.55\paperwidth,bb = 0 0 200 100, draft, type=eps]{Resource_Assembly}\end{center}
+ width=0.55\paperwidth]{Resource_Assembly}\end{center}
\caption{Resource Assembly}
@@ -44,13 +51,13 @@
or collection of resources that would be seen as one web page, or
printed as one unit.
-Using the same tool, fragments (which would then be rendered as standalone
+Using the same tool, fragments (which would then be rendered as stand alone
pages), pages and other sequences can be assembled into sequences.
Sequences are resources which are rendered a sequence of pages, not
necessarily linear. Examples are one lesson, one chapter, or one learning
cycle.
-On the third granularity level, fragments (rendered as standalone
+On the third granularity level, fragments (rendered as stand alone
pages), pages, and sequences can be assembled into courses. Courses
are a sequence which represents the entirety of the resources belonging
to a learning unit into which learners can be enrolled. Examples are
@@ -71,7 +78,7 @@
on those resources.
-\subsection{Cirriculum Adaptivity}
+\subsection{Curriculum Adaptivity}
Maps allow for conditional choices and branching points. The actual
path through and presentation of the learning resources is determined
Index: loncom/html/adm/help/tex/About_Communication.tex
+++ loncom/html/adm/help/tex/About_Communication.tex
\label{About_Communication}
Each of these communication techniques, except internal email, can
be prevented by the instructors, by setting parameters in the course
environment screen. Each of these communication techniques allows
the inclusion of \LaTeX{}, for math support, if desired.
As a practical matter, the Resource Discussion and Internal Email
tend to constitute the bulk of the communication instructors and students
do.
Index: loncom/html/adm/help/tex/About_Developers_Manual.tex
+++ loncom/html/adm/help/tex/About_Developers_Manual.tex
\label{About_Developers_Manual.tex}
The purpose of this document is to introduce developers people to
LON-CAPA, and enable them to start doing real work with the system
as quickly as possible. This should prove useful both to people who
already intend to develop with LON-CAPA, and to technical people who
are evaluating LON-CAPA to see if it suits their needs.
The most daunting task facing new developers is understanding how
the whole system fits together; individual pieces are usually sensible
but like any large program it is difficult to understand the forest
by looking at just the trees. Therefore, this document will start
out with the highest-level overview of the system, which can be safely
skipped if you already know what LON-CAPA is.
Next, we'll look at the major subsystems of LON-CAPA and how they
fit together at a high level, with enough detail to understand the
context a given piece of the system functions in. Appropriate pointers
will be given to the detailed documentation on the various subsystems,
so this section can be used as an expanded {}``Table of Contents''.
Then a brief tutorial in adding a {}``handler'' to LON-CAPA will
be given, enabling you both to understand how to add brand-new functionality
to LON-CAPA, and better understand the majority of the code in the
system which is in the form of handlers.
Finally, the last and largest portion of this document will be extremely
detailed examinations of the subsystems from a technical point of
view, including API descriptions suitable for use in programming.
Obviously you will not need to read this over entirely, unless you
really want to know what the system can do.
Index: loncom/html/adm/help/tex/Authentication.tex
+++ loncom/html/adm/help/tex/Authentication.tex
\label{Authentication}
People are authenticated with a standard username and password scheme.
LON-CAPA ships with support for LON-CAPA specific passwords, authentication
using the UNIX authentication scheme on the server (assuming that
user has a user account on that system), and Kerberous 4 and 5. It
is easy to add other external authentication types to integrate with
whatever your campus may use, and there are institutions doing this.
Index: loncom/html/adm/help/tex/Cascading_Parameters.tex
+++ loncom/html/adm/help/tex/Cascading_Parameters.tex
\label{Cascading_Parameters}
LON-CAPA uses a powerful and flexible {}``cascading parameter''
system. A {}``parameter'' is anything that can be set for a problem
in a course, such as a due date. LON-CAPA parameters can be set for
the {}``entire course'', for {}``all problems in a particular sequence'',
or for an {}``individual problem''. Fully independently of that,
they can be set for {}``everyone in a course'', for {}``everyone
in a section'', or for {}``a single person''. More specific parameter
settings override more general ones.
Some of the more common parameters include {}``open date'' (when
a problem becomes visible for the student to complete), {}``due date''
(the time the student must have the problem done by), {}``answer
date'' (an optional date where the solution to the problem becomes
visible if they did not complete it earlier), and {}``weight'' (the
point value of the problem). Different problem types can also take
different parameters; for instance, the instructor can override the
{}``tolerance'' for a numerical problem (how close the student must
come for a numerical problem to be considered correct), or control
the style of the problem (for instance, the system has an {}``exam''
mode where it will give the student multiple choices for a numerical
problem, which is useful for printed exams). Problems can also export
arbitrary other parameters, which may give instructors the ability
to control the difficulty level or select a specific varient of the
problem, depending on how the problem was authored.
This parameter system makes most common manipulations of these parameters
very easy. If a specific section missed a lab because of a fire drill,
that section can have its due date extended for the week without affecting
any other section with a single operation. A single student can have
their problems opened earlier if they're going to be gone for some
excused reason. An entire self-paced learning course can have a global
due-date set at the beginning of the course.
On a technical level, the parameter setting is handled by \texttt{lonparmset}.
\texttt{lonnavmaps} provides an easy-to-use interface to most of the
common parameters while doing much of the bookkeeping for you. See
documentation for those things in the appropriate section below. A
function called {}``\texttt{parmval}'' in \texttt{Apache::lonnavmaps::navmap}
and \texttt{Apache::assesscalc} handle the computation of which parameter
is in effect and can be consulted for precise details on the cascading.
Index: loncom/html/adm/help/tex/Chatting.tex
+++ loncom/html/adm/help/tex/Chatting.tex
\label{Chatting}
Course members can participate in a live chatting environment for
their course.
Index: loncom/html/adm/help/tex/Developer_Manual_Title_Page.tex
+++ loncom/html/adm/help/tex/Developer_Manual_Title_Page.tex
\label{Developer_Manual_Title_Page}
\title{Learning \emph{Online} Network with CAPA\\
\emph{~}\\
\emph{\Large Developer's Tutorials And Manual}}
\maketitle
\vfill{}
\begin{center}~\end{center}
\begin{center}LON-CAPA Code Contributors\end{center}
~
\begin{center}Laboratory for Instructional Technology in Education\\
and the\\
Office of Medical Education Research and Development\\
Michigan State University\\
\end{center}
\newpage
\tableofcontents{}
\newpage
Index: loncom/html/adm/help/tex/Developer_Tutorial.tex
+++ loncom/html/adm/help/tex/Developer_Tutorial.tex
\section{Adding a Handler to LON-CAPA}
In this section, we will add a brand new {}``handler'' to LON-CAPA.
A \textbf{handler\index{handler}} is code that gets loaded by the
Apache web server that tells the web server how to handle a certain
kind of request. For a complete discussion of this process, you will
need to read the Apache documentation; we especially recommend the
O'Reilly book {}``Writing Apache Modules with Perl and C''. In this
chapter we will add a {}``Response'' handler; this is the most important
handler in the system because it is directly responsible for what
the user sees on the screen when they end up using the handler.
As a side-effect of installing a new handler from scratch, we will
also show how to modify the files LON-CAPA uses and run LON-CAPA with
the modified files.
After completing this tutorial you should be able to more easily understand
the structure of the vast majority of LON-CAPA code.
If you are brave and are not using Red Hat to run LON-CAPA, the \texttt{/etc/httpd}
and \texttt{/var/log/httpd} directories may not exist, as your distribution
may prefer to refer to them as \texttt{/etc/apache} and \texttt{/etc/log/apache},
such as Gentoo does. In that case, I recommend symlinking \texttt{/etc/httpd}
to \texttt{/etc/apache} (LON-CAPA depends on \texttt{/etc/httpd} existing),
and either make the appropriate substitutions in the following directions
for the log files, or make a symlink there, too. (\texttt{ln -s /etc/apache
/etc/httpd})
\subsection{Pre-requisites}
\begin{itemize}
\item LON-CAPA must be installed and running.
\item \textbf{Perl}: You're going to need to know some or you will not understand
the code. You don't need to be intimately familiar with the many hundreds
of libraries Perl has, though, which is much harder then learning
the language.
\item Knowledge of the Apache server is not required for this tutorial,
but {}``real work'' may require more information then is given here.
\end{itemize}
\subsection{Adding a New Handler}
You need to create a \emph{new Perl module} to serve as the handler.
A {}``Perl module''\index{Perl module} is a file that has a name
ending in {}``.pm''. For the sake of concreteness, I will refer
to this file as \texttt{lontutorial.pm}%
\footnote{Currently, almost all LON-CAPA Perl modules are prefixed with {}``lon''.
This is a weak convention used inconsistently, and theoretically it
will be dropped from the project someday. %
}.
Create this new file where ever you'd like for now.
\subsubsection{Apache Handler Shell}
Put the following code into your Perl module:
\begin{lyxcode}
package~Apache::lontutorial;
~
use~strict;
use~Apache::Constants~qw(:common);
use~Apache::loncommon;
~
=pod
~
=head1~NAME
~
lontutorial~-~tutorial~code
~
=head1~SYNOPSIS
~
lontutorial~contains~the~code~from~the~tutorial,~and
does~tutorial~stuff.
~
=cut
~
sub~handler~\{
~~~~my~\$r~=~shift;
~
~~~~\$r->print('Hello~world!');
~~~~return~OK;
\}
~
1;
\end{lyxcode}
A line-by-line breakdown:
\begin{itemize}
\item \texttt{\textbf{package Apache::lontutorial;}}: This puts everything
in the file in the \texttt{Apache::lontutorial} namespace. Note that
the \texttt{lontutorial} part should match your filename before the
\texttt{.pm}. (The file may contain other packages; see \texttt{lonnavmaps.pm}
or \texttt{lonhelper.pm} for an example. But this package should show
up in the file or Apache may have trouble finding your file.)
\item \texttt{\textbf{use strict;}}: Turns on strict variable checking,
which is a Very Good Idea. If you intend to submit the code back to
the main LON-CAPA project, please make sure to use this.
\item \texttt{\textbf{use Apache::Constants qw(:common);}}: This loads certain
constants used to communicate with Apache into the current namespace.
\item \texttt{\textbf{use Apache::loncommon;}}: This loads some commonly-used
functions we will use later. See \texttt{man Apache::loncommon} for
more information.
\item \texttt{\textbf{=pod}} through \texttt{\textbf{=cut}}: This contains
inline documentation in the POD format. Please see \texttt{man perlpod}
for more information. I encourage you to document your code. Note
many current LON-CAPA modules do not contain good examples. Please
consult \texttt{perldoc lonhelp.pm} in the \texttt{loncom/interface}
directory of the CVS repository, or see the \texttt{lonhelp.pm} information
later in the developer manual, for style considerations. The documentation
so produced can be easily added to this Developer's Manual if it would
be useful to others, so you're accomplishing the dual purpose of documenting
in the file and the manual at the same time.
\item \texttt{\textbf{sub handler \{}}: Apache will call the \texttt{handler}
function in the namespace it is given for the handler in the \texttt{loncapa\_apache.conf}
file; see below. Thus, we need to supply it, or Apache will fail and
complain about a missing subroutine.
\item \texttt{\textbf{my \$r = shift;}}: The first and only parameter to
the handler function is the Apache Response object. We will partially
cover this object in this tutorial, for more information consult outside
documentation.
\item \texttt{\textbf{\$r->print('Hello world!');}}: \texttt{\$r->print}
is how we sent text to the user. This is the \emph{only} method to
send text to the user's web browser, and in the end, all output ends
up going through this function.
\item \texttt{\textbf{return OK;}}: {}``OK'' is a constant we imported
in our namespace in the use \texttt{Apache::Constants} line. It tells
the server the page was successfully displayed, as opposed to a 404
or other error.
\item \texttt{\textbf{1;}}: This tells Perl the module was successfully
parsed, and is a required part of Perl modules.
\end{itemize}
\subsubsection{Telling Apache About Your Handler}
In order for Apache to use your file, you need to tell Apache where
to find it, and what URL(s) to use for it. Add the following to your
\texttt{/etc/httpd/conf/loncapa\_apache.conf}, after the \texttt{PerlTransHandler}
declaration:
\begin{lyxcode}
<Location~/adm/tutorial>
PerlAccessHandler~~~~~~~Apache::lonacc
SetHandler~~~~~~~~~~~~~~perl-script
PerlHandler~~~~~~~~~~~~~Apache::lontutorial
ErrorDocument~~~~~~500~~/adm/errorhandler
</Location>
\end{lyxcode}
This will tell Apache to call Apache::lontutorial::handler when someone
goes to /adm/tutorial to see what to do.
Note: The \texttt{Apache::} is not technically necessary in mod\_perl,
it's just that LON-CAPA uses it. We may remove it from the system
someday. In the meantime, it would be consistent with the rest of
the system to continue use it. (If you don't understand what this
is saying, don't worry about it.)
\subsubsection{Putting The File Where Apache Can Find It}
Now you need to put that file where Apache can find it.
Apache will look for it in \texttt{/home/httpd/lib/perl/Apache}/,
so copy it there.
\begin{lyxcode}
cp~lontutorial~/home/httpd/lib/perl/Apache/
\end{lyxcode}
\subsubsection{Running Apache}
You can now (re-)start the Apache server.
\begin{lyxcode}
/etc/init.d/httpd~restart
\end{lyxcode}
Also, if you are logged into LON-CAPA, log out (exit) before continuing.
(Note re-starting the server does \emph{not} automatically log you
out, which is really helpful while debugging so you don't have to
continuously log back in.)
If everything went well, you can now go to your server and go to \texttt{http://your.server/adm/tutorial},
with \texttt{your.server} replaced by the domain name of your LON-CAPA
server, of course. (I will use {}``your.server'' that way for the
rest of this tutorial.)
And you should see\ldots{} {}``Bad Request''? What happened?
You don't know it yet, but we're making a handler for functionality
that will require the user to be logged in for it to work, because
it is going to depend on information about the user. Right now, nobody
is logged in. The \texttt{PerlAccessHandler\index{PerlAccessHandler}}
line in what we put in \texttt{loncapa\_apache.conf} tells Apache
to use {}``Apache::lonacc::handler'' as an \textbf{access handler}\index{access handler}.
An \textbf{access handler} determines whether the user has permission
to perform the current action. lonacc is a handler written for LON-CAPA
that among other things, ensures the user is logged in. This handler
told Apache that this is a {}``Bad Request'', which is why you got
the {}``Bad Request'' screen. Your handler code was actually \textbf{never
even executed}; Apache aborted the request before getting to your
code.
Log into LON-CAPA, and choose a role with a course. (You may need
to create a course; please see the Course Management manual for more
information.) Any role with a course, Student, Instructor, Course
Coordinator or otherwise is fine. We won't be making any changes to
the course data so it doesn't matter if it's a {}``real'' course.
Once you've gotten to the first page of the course (normal entry),
change your URL to read \texttt{http://your.server/adm/tutorial}.
You should now see {}``Hello world!'' on the screen.
\paragraph{Apache can't find \texttt{/adm/tutorial}:}
If Apache is claiming it can't find the file named {}``/adm/tutorial'',
something is wrong with your \texttt{loncapa\_apache.conf} file. Please
double check the entry to make sure it is in the right place, that
it is typed correctly, and that all the lines are present. If it is
still incorrect, please ask for help on the \texttt{lon-capa-dev@mail.msu.edu}
list, including a copy of your \texttt{loncapa\_apache.conf} file
in the email; either something is wrong that is beyond the scope of
this document(other system configuration issues) or you really can't
find the error.
\paragraph{{}``Something went wrong, please help us find out what''}
If you get an icon of the LON-CAPA logo with a cracked screen and
the preceding message, something is wrong with your Perl code. This
is the standard screen that asks the user to send us more information
about what happened, so we can try to diagnose the problem. Since
you're a developer, you can ignore that screen and actually collect
the information and act on it directly.
The Perl error landed in \texttt{/var/log/httpd/error\_log}, in the
last few lines. Take a look at what was in there, and try to fix it.
\begin{lyxcode}
tail~/var/log/httpd/error\_log
\end{lyxcode}
Since I can't guess what error you encountered, I'm afraid I can't
help you out here. But I do know the code I wrote above worked, so
as a last resort try to figure out what is different. If you are absolutely
stumped, please ask for help on the \texttt{lon-capa-dev@mail.msu.edu}
list, including a copy of your \texttt{lontutorial.pm} file in the
email; either something is wrong that is beyond the scope of this
document (other system configuration issues) or you really can't find
the error.
Actually, if you have the time, I recommend adding a syntax error
to your \texttt{lontutorial.pm}, even if it worked the first time,
so you can see what happens. This will not be the last time there's
an error in your code\ldots{}
\subsubsection{Modifying The Module}
When Apache is started, it reads all the Perl modules in LON-CAPA
into memory, and after that, does not use the \texttt{.pm} files in
\texttt{/home/httpd/lib/perl/Apache}%
\footnote{Slight exaggeration here: Actually it only loads the ones mentioned
in startup.pl, and since your module isn't in that file, it won't
be loaded at startup. But this really doesn't matter much.%
}. To get Apache to use your newly-edited files, you need to copy them
to \texttt{/home/httpd/lib/perl/Apache} and restart the Apache server.
It is generally not a good idea to directly modify the files in \texttt{/home/httpd/lib/perl/Apache}
while developing, because of the difficulty you will have later propagating
changes made there back to more useful places, such as in the LON-CAPA
CVS repository. To alleviate the annoyance of constantly copying the
file to that directory and restarting the server, compose a single
command line that does all of it at once. I often use something like
the following:
\begin{lyxcode}
pushd~.;~cd~YOUR\_DIRECTORY;~cp~lontutorial.pm
~/home/httpd/lib/perl/Apache;~/etc/init.d/httpd~restart;
~popd
\end{lyxcode}
where YOUR\_DIRECTORY is replaced by the directory containing the
\texttt{lontutorial.pm} file, and that is all one line.
The {}``pushd'' and {}``popd'' commands are built-in to the Bash
shell; other shells may or may not contain such commands.
Once you've created this command line, you can just use the Up arrow
in your shell to get it back. You can add whatever you want to it
as needed; that's why I wrap it in the {}``pushd'' and {}``popd''
commands, so you can {}``cd'' without affecting your current directory.
If you had a syntax error in your Perl module, fix it now. If you
didn't, I'd recommend make a small change to the printed string or
something and making sure you have figured out how to change the code
in the Apache server correctly before continuing.
Once again, notice that even after re-starting the server, you are
still logged in with the same settings you were using before the server
re-start.
\subsection{Making The Handler Do Something}
\subsubsection{A Bit More Boilerplate}
At this point, your handler isn't doing much. If you look carefully,
you'll notice that the {}``Hello World'' on the screen is in a mono-spaced
font, not the proportional font used by default in HTML. That's because
\emph{all} you sent was {}``Hello World!''; the browser looks at
the header of the HTTP response to see what kind of response it is
getting back, but you didn't even \emph{send} a header. Technically,
that's not a legal HTTP response, but the browser was accommodating
and displayed what you got back anyhow as text. (Consult documentation
on the HTTP protocol for more information about this; generally you
will not need to worry about this in LON-CAPA beyond the boilerplate
presented here.)
To send back a proper HTTP response, add this code after the \texttt{my
\$r = shift;}:
\begin{lyxcode}
~~~~\#~Handle~header-only~request
~~~~if~(\$r->header\_only)~\{
~~~~~~~~if~(\$ENV\{'browser.mathml'\})~\{
~~~~~~~~~~~~\$r->content\_type('text/xml');
~~~~~~~~\}~else~\{
~~~~~~~~~~~~\$r->content\_type('text/html');
~~~~~~~~\}
~~~~~~~~\$r->send\_http\_header;
~~~~~~~~return~OK;
~~~~\}
~~~~\#~Send~header,~don't~cache~this~page
~~~~if~(\$ENV\{'browser.mathml'\})~\{
~~~~~~~~\$r->content\_type('text/xml');
~~~~\}~else~\{
~~~~~~~~\$r->content\_type('text/html');
~~~~\}
~~~~\&Apache::loncommon::no\_cache(\$r);
~~~~\$r->send\_http\_header;
\end{lyxcode}
This is boilerplate that appears at the top of many LON-CAPA handlers.
It handles the case where the user is requesting that only headers
be sent; unusual, but worth handling. It sets the content type appropriately,
and tells the client not to cache this page, which is appropriate
since it will be dynamic.
For efficiency, when you use \texttt{\$r->print()} to send something
to the user, Apache assumes you know what you are doing and will immediately%
\footnote{Actually, if you send a lot of little things, Apache is smart enough
to bundle them together into one big network packet for efficiency.
If you absolutely want Apache to send everything it has to the user
\emph{right now}, use \texttt{\$r->rflush()}\ldots{} but sparingly,
as repeated use can cause a \emph{huge} slowdown.%
} send what you printed across the network. Since the HTTP header is
supposed to precede all content, it is important that you send the
header before you send any other content across the network, so we
ask the Apache server to go ahead and send the header with \texttt{\$r->send\_http\_header()}.
Since the \texttt{Apache::loncommon::no\_cache()} call affects the
header, it must be called before we send it out, because once the
header is sent there's no getting it back.
All code that follows this code will send the output to the user directly.
Finally, let's add two more lines to make it fit into the system better.
Wrap the following three lines around the {}``Hello World'' line,
as shown:
\begin{lyxcode}
\$r->print('<html><head><title>Tutorial~Page</title></head>');
\$r->print(\&Apache::loncommon::bodytag('Tutorial~Handler','',''));
\$r->print('Hello~world!');
\$r->print('</body></html>');
\end{lyxcode}
Now use your command line to copy \texttt{lontutorial.pm} and restart
the server. Go to \texttt{/adm/tutorial}, and you'll see a nice looking
page saying {}``Hello world!''.
Congratulations, you now have a handler ready to do some real work
with!
\subsubsection{Rending Navmaps}
To start with, let's go ahead and display the navmap for the current
course.
Under \texttt{use strict;}, add this line:
\begin{lyxcode}
use~Apache::lonnavmaps;
\end{lyxcode}
Remove the {}``Hello world!'' line and replace it with this:
\begin{lyxcode}
\$ENV\{'form.condition'\}~=~1;
my~\$renderArgs~=~\{~'cols'~=>~{[}Apache::lonnavmaps::resource{]},
~~~~~~~~~~~~~~~~~~~'showParts'~=>~0,
~~~~~~~~~~~~~~~~~~~'r'~=>~\$r~\};
Apache::lonnavmaps::render(\$renderArgs);
\end{lyxcode}
Line by line:
\begin{itemize}
\item \texttt{\textbf{use Apache::lonnavmaps;}}: \texttt{Apache::lonnavmaps}
contains routines that help render navmaps. For more information,
see later in this manual or type \texttt{man Apache::lonnavmaps}.
This ensures these routines are loaded into memory.
\item \texttt{\textbf{\$ENV\{'form.condition'\} = 1;}}: This is an an argument
being passed to the Apache::lonnavmaps::render routine in a rather
unorthodox way. This will cause the navmap to render all of the resources,
by default, except for what we explicitly exclude. Since we're not
going to exclude anything (which we would do with \texttt{\$ENV\{'form.filter'\}}),
all resources will be shown.
\item \texttt{\textbf{my \$renderArgs\ldots{}\$r\};}}: Since the \texttt{render}
routine takes a \emph{lot} of arguments, the \texttt{render} routine
takes in a hash reference instead of a traditional list of arguments.
For full information about what that function takes, consult the documentation.
\texttt{'cols'} will tell the render function what to render in the
navmap; {}``0'' is the standard listing of the resource with a link
to the resource. \texttt{'showParts' => 0} tells the render function
not to show individual parts, which will not be useful to us. \texttt{'r'
=> \$r} passes the Apache response object to the \texttt{render} function,
which it uses to provide periodic output to the user by using the
\texttt{rflush} method on the object.
\item \texttt{\textbf{Apache::lonnavmaps::render(\$renderArgs);}}: Performs
the actual rendering of the navmaps. Since we passed it \texttt{\$r},
it will take care of displaying the navmaps for us. If we didn't pass
it \texttt{\$r}, it would return a string containing the rendered
HTML, which we would be responsible for \texttt{\$r->print}ing.
\end{itemize}
Save this and use your command line to re-load the server. Make sure
you've selected a specific course role before trying to visit \texttt{/adm/tutorial}.
You may need to create a course with a few resources in it first,
depending on your setup.
\subsubsection{Goal}
In order to exercise storing data on the LON-CAPA network, we're going
to do something a little silly, but pedagogically useful. Let's add
two columns to the navmap, one which will provide a checkbox which
we can click, and another which will show how many times we've selected
that particular resource and submitted a form. While this is somewhat
silly, the general principle of doing something for some selection
of resources is a fairly common operation in LON-CAPA, as is storing
or loading data from the network.
In doing this, we'll learn:
\begin{itemize}
\item How to store data on the LON-CAPA network correctly.
\item How to process incoming form input in LON-CAPA.
\item How to work with and identify resources in LON-CAPA.
\end{itemize}
\subsection{Adding A Form For Input}
The first thing we need to do to accomplish this is to add an HTML
form to the screen so we have something to submit. Just above the
\texttt{\$ENV\{'form.condition'\}} line, add the following:
\begin{lyxcode}
\$r->print(\char`\"{}<form~method='post'><input~type='hidden'~name='submission'~value='1'~/>\char`\"{});
\end{lyxcode}
This will print out a form element, and a hidden form element named
{}``submission'' with a value of {}``1''. Strictly speaking, this
is not necessary, but this serves as a {}``sentinel'', which makes
it easy to check later whether or not we need to process input with
a single \texttt{if} statement.
Just before \texttt{\$r->print({}``</body></html>'');}, add this:
\begin{lyxcode}
\$r->print('<input~type=\char`\"{}submit\char`\"{}~value=\char`\"{}Increment\char`\"{}~/></form>');
\end{lyxcode}
If you now use your command line to re-load the server, and you examine
the source code of the page on /adm/tutorial, you should now see a
form, with a hidden value and a submit button, though pressing the
submit button won't do much.
\subsubsection{Seeing The Incoming Data}
LON-CAPA automatically processing incoming POST data and exposes it
to you in the \texttt{\%ENV} hash. The data will appear in \texttt{\$ENV\{'form.\$varname'\}},
where \texttt{\$varname} is the variable name of the HTML form element.
In this case, since we have an element named {}``submission'', a
{}``1'' will appear in \texttt{\$ENV\{'form.submission'\}} when
we hit the {}``Increment'' button. To see this, add the following
after the \texttt{bodytag} call:
\begin{lyxcode}
if~(\$ENV\{'form.submission'\})~\{
~~~~\$r->print('<p>Form~submitted.</p>');
\}~else~\{
~~~~\$r->print('<p>No~form~information~submitted.</p>');
\}
\end{lyxcode}
Reload the tutorial code into the server. Now, when you type in \texttt{/adm/tutorial},
{}``No form information submitted.'' will appear on the screen.
When you hit {}``Increment'', {}``Form submitted.'' will appear.
Note this only applies to POST'ed data. If you use GET, the data will
appear on the query string. For your code, this will show up in \texttt{\$ENV\{QUERY\_STRING\}}.
If you want to invoke LON-CAPA's processing on that string, so you
see the variables in \texttt{\%ENV}, use \texttt{Apache::loncommon::get\_unprocessed\_cgi(\$ENV\{QUERY\_STRING\});}.
\subsubsection{Adding Checkboxes for Input}
Now we want to add a checkbox column into the navmap rendering so
we have a place to input our selections. In order to do that, we need
to provide the rendering code with a subroutine that will take an
\texttt{Apache::lonnavmaps::resource} object and return the string
we want to print, including the <td> and </td> tags. (For more information,
consult the \texttt{Apache::lonnavmaps::render} documentation.) Add
the following after the second and last \texttt{send\_http\_header}
line:
\begin{lyxcode}
my~\$checkboxCode~=~sub~\{~my~\$resource~=~shift;
~~~~return~'<td~align=\char`\"{}center\char`\"{}><input~type=\char`\"{}checkbox\char`\"{}~'~.
~~~~'name=\char`\"{}symb.'~.
~~~~Apache::lonnet::escape(\$resource->symb())~.~
~~~~'\char`\"{}~/></td>';
\};
\end{lyxcode}
A \textbf{symb} is a string which uniquely identifies a resource within
a course, since the same resource can show up in multiple sequences,
or multiple times in the same sequence. Thus, that makes a good ID
for the checkboxes. Given an \texttt{Apache::lonnavmaps::resource}
object, the {}``symb'' method will return the symb. \texttt{Apache::lonnet::escape}
is a function that does URL-escaping on the resulting string, so it's
safe to pass into an HTML attribute. (XML-type escaping would work
too.)
Go ahead and load this into the server, so you can see the HTML output
by viewing the source.
\subsubsection{Getting The Checked Resources}
Let's make sure we can retrieve the checked resources before continuing.
Add the following code before the \texttt{\$r->print({}``<form}\ldots{}
code:
\begin{lyxcode}
foreach~(keys~\%ENV)~\{
~~~~if~(substr(\$\_,~0,~10)~eq~'form.symb.')~\{
~~~~~~~~my~\$symb~=~substr(\$\_,~10);
~~~~~~~~\$symb~=~Apache::lonnet::unescape(\$symb);
~~~~~~~~\$r->print(\char`\"{}\$symb<br~/>\char`\"{});
~~~~\}
\}
\end{lyxcode}
That will print each symb that we select the checkbox for on the screen.
You may remove this later if you find it unsightly.
Re-load the code into the server and make sure it's still working.
Try checking a few boxes and hitting {}``Increment'' to make sure
the symbs appear at the top of the screen.
\subsection{Storing Data on the LON-CAPA Network}
Let's suppose you want to record how often you submit a given checkbox.
You can't write to the current server's hard drive, because there's
no guarantee that next time you log on, that you'll get the same server.
(Of course, if you're on a single development system, you can know
that, but if you want your code to be generally useful for LON-CAPA,
you can't depend on being on the same system.)
Let's go ahead and retrieve the hash we're going to store. If it doesn't
already exist, it will end up getting created implicitly. Before the
\texttt{foreach (keys \%ENV)}, add
\begin{lyxcode}
my~\%countHash~=~Apache::lonnet::restore('tutorial');
my~\%newHash~=~();
\end{lyxcode}
\texttt{\%countHash} will contain what we've stored. \texttt{\%newHash}
will be used to store new data into the stored hash; please see the
documentation on lonnet to see why this is necessary.
\texttt{'tutorial'} identifies the hash we wish to store; if we make
a later \texttt{restore} call with that parameter we'll get this hash
back. Normally you'll want to choose the name of the hash more carefully,
for instance including the course ID into it, unless you really mean
to do something for all courses. For simplicity, we are leaving that
out.
Replace the \texttt{foreach} loop that is printing out the symbs with
this:
\begin{lyxcode}
foreach~(keys~\%ENV)~\{
~~~~if~(substr(\$\_,~0,~10)~eq~'form.symb.')~\{
~~~~~~~~my~\$symb~=~substr(\$\_,~10);
~~~~~~~~\$symb~=~Apache::lonnet::unescape(\$symb);
~~~~~~~~\$countHash\{\$symb\}++;
~~~~~~~~\$newHash\{\$symb\}~=~\$countHash\{\$symb\};
~~~~\}
\}
\end{lyxcode}
That will increment the count for each symb that we checked a box
for. We need to store the data the user changed, so just before \texttt{return
OK;}, add the following line of code:
\begin{lyxcode}
Apache::lonnet::store(\textbackslash{}\%newHash,~'tutorial');
\end{lyxcode}
\subsubsection{Displaying The Count}
Finally, we need a column that will display the count of times we've
checked the box. Right after the \texttt{foreach} loop we just modified,
add
\begin{lyxcode}
my~\$countCode~=~sub~\{~my~\$resource~=~shift;
~~return~'<td~align=\char`\"{}center\char`\"{}>'~.
~~~~\$countHash\{\$resource->symb()\}~.
~~~~\char`\"{}</td>\char`\"{};
~~\};
\end{lyxcode}
Add \texttt{\$countCode} to the 'cols' list in the \texttt{\$renderArgs}:
\begin{lyxcode}
my~\$renderArgs~=~\{~'cols'~=>~{[}Apache::lonnavmaps::resource,
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\$checkboxCode,~\$countCode{]},
~~~~~~~~~~~~~~~~~~~'showParts'~=>~0,
~~~~~~~~~~~~~~~~~~~'r'~=>~\$r~\};
\end{lyxcode}
Viola! That should do it.
\subsection{Complete Code Listing}
For your reference, I include the complete code listing for the tutorial
here:
\begin{lyxcode}
package~Apache::lontutorial;
~
use~strict;
use~Apache::lonnavmaps;
use~Apache::Constants~qw(:common);
~
=pod
~
=head1~NAME
~
lontutorial~-~tutorial~code
~
=head1~SYNOPSIS
~
lontutorial~contains~the~code~from~the~tutorial,~and
does~tutorial~stuff.
~
=cut
~
sub~handler~\{
~~~~my~\$r~=~shift;
~~~~\#~Handle~header-only~request
~~~~if~(\$r->header\_only)~\{
~~~~~~~~if~(\$ENV\{'browser.mathml'\})~\{
~~~~~~~~~~~~\$r->content\_type('text/xml');
~~~~~~~~\}~else~\{
~~~~~~~~~~~~\$r->content\_type('text/html');
~~~~~~~~\}
~~~~~~~~\$r->send\_http\_header;
~~~~~~~~return~OK;
~~~~\}
~~~~\#~Send~header,~don't~cache~this~page
~~~~if~(\$ENV\{'browser.mathml'\})~\{
~~~~~~~~\$r->content\_type('text/xml');
~~~~\}~else~\{
~~~~~~~~\$r->content\_type('text/html');
~~~~\}
~~~~\&Apache::loncommon::no\_cache(\$r);
~~~~\$r->send\_http\_header;
~~~~my~\$checkboxCode~=~sub~\{~my~\$resource~=~shift;~
~~~~~~return~'<td~align=\char`\"{}center\char`\"{}><input~type=\char`\"{}checkbox\char`\"{}~name=\char`\"{}symb.'~.
~~~~~~~~~~Apache::lonnet::escape(\$resource->symb())~.~'\char`\"{}~/></td>';
~~~~~~~~~~~~~~~~~~~~~~~~~\};
~~~~\$r->print('<html><head><title>Tutorial~Page</title></head>');
~~~~\$r->print(\&Apache::loncommon::bodytag('Tutorial~Handler','',''));
~~~~if~(\$ENV\{'form.submission'\})~\{
~~~~~~~~\$r->print('<p>Form~submitted.</p>');
~~~~\}~else~\{
~~~~~~~~\$r->print('<p>No~form~information~submitted.</p>');
~~~~\}
~~~~my~\%countHash~=~Apache::lonnet::restore('tutorial');
~~~~my~\%newHash~=~();
~~~~foreach~(keys~\%ENV)~\{
~~~~~~~~if~(substr(\$\_,~0,~10)~eq~'form.symb.')~\{
~~~~~~~~~~~~my~\$symb~=~substr(\$\_,~10);
~~~~~~~~~~~~\$symb~=~Apache::lonnet::unescape(\$symb);
~~~~~~~~~~~~\$countHash\{\$symb\}++;
~~~~~~~~~~~~\$newHash\{\$symb\}~=~\$countHash\{\$symb\};
~~~~~~~~\}
~~~~\}
~~~~my~\$countCode~=~sub~\{~my~\$resource~=~shift;
~~~~~~return~'<td~align=\char`\"{}center\char`\"{}>'~.
~~~~~~~~\$countHash\{\$resource->symb()\}~.
~~~~~~~~\char`\"{}</td>\char`\"{};
~~~~~~\};
~~~~\$r->print(\char`\"{}<form~method='post'><input~type='hidden'\char`\"{}~.
~~~~~~~~~~~~~~\char`\"{}name='submission'~value='1'~/>\char`\"{});
~~~~\$ENV\{'form.condition'\}~=~1;
~~~~my~\$renderArgs~=~\{~'cols'~=>~{[}Apache::lonnavmaps::resource,
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\$checkboxCode,~\$countCode{]},
~~~~~~~~~~~~~~~~~~~~~~~'showParts'~=>~0,
~~~~~~~~~~~~~~~~~~~~~~~'r'~=>~\$r~\};
~~~~Apache::lonnavmaps::render(\$renderArgs);
~~~~\$r->print('<input~type=\char`\"{}submit\char`\"{}~value=\char`\"{}Increment\char`\"{}~/></form>');
~~~~\$r->print('</body></html>');
~~~~Apache::lonnet::store(\textbackslash{}\%newHash,~'tutorial');
~~~~return~OK;
\}
1;
\end{lyxcode}
Index: loncom/html/adm/help/tex/Finding_Resources.tex
+++ loncom/html/adm/help/tex/Finding_Resources.tex
\label{Finding_Resources}
Finding resources in LON-CAPA's library is accomplished by both a
{}``browsing'' interface, which provides a Windows Explorer-like
interface to the network, \index{resources, browsing}and a {}``search''
\index{resources, searching}interface, which allows searching based on various useful criteria
like words that appear in the resource, resource type, who wrote it,
etc.
Index: loncom/html/adm/help/tex/Guts_Apache.tex
+++ loncom/html/adm/help/tex/Guts_Apache.tex
The standard mode in which the Apache web server is used is that a
URL corresponds to some static file on the file system, which then
more or less gets sent out as-is. Slight deviations from that simple
principle are however already the directory listing function, virtual
servers, and the cgi-bin directory. In the latter case, Apache executes
the file in a new process and provides both the input to the process
in the environment, and routes the output to the client. Other deviations
are the error messages.
In a more general view, URLs to Apache are URIs (Uniform Resource
Identifiers), which may are may not correspond to a physical file,
which in turn may or may not be sent out as-is.
As a request for a URI gets sent to the Apache server, it goes through
several phases. At each phase ({}``stage'') along the process, handler
modules can be defined to deal with the request. Details about these
phases are given in {}``Writing Apache Modules with Perl and C''
from O'Reilly (the {}``Eagle book'') in Chapter 3 (page 60).
These handler modules are not like cgi-scripts executed in a separate
process, but are dynamically linked into the Apache child processes
themselves - they run inside of Apache. The mod\_perl mechanism in
addition links the Perl interpreter into the Apache child process.
Modules are pre-interpreted ({}``compiled'') by the Perl interpreter
when they are first loaded, and the pre-interpreted code stays permanently
in the memory allocated to that Apache child process. The result is
a significant speed-up, and through the flexible mechanism of module
registration and different stages of the process, a high degree of
customizability.
LON-CAPA does \emph{not} use Apache::Registry, and so in addition
avoids the unnecessary overhead of emulating a cgi-environment within
the handlers. Instead, it makes direct use of the Apache Perl API
(Chapter 9, Eagle book).
If you intend to add new capabilities to LON-CAPA that require new
handlers, as opposed to tweaking current ones, we recommend buying
a copy of {}``Writing Apache Modules with Perl and C''; it is not
strictly necessary but it is the clearest description of what is going
on in the Apache server, and without it you will be challenged to
understand everything that is occurring in the server.
Index: loncom/html/adm/help/tex/Guts_Apache_Env.tex
+++ loncom/html/adm/help/tex/Guts_Apache_Env.tex
The environment is accessible through the global hash named \%ENV.
In addition to the standard variables placed in the environment by
the Apache server, LON-CAPA places a lot of information in the \%ENV.
You can see this information by going to \texttt{/adm/test}; the top
part of that screen will show your current \%ENV. (You may need to
modify \texttt{/home/httpd/lonTabs/htpasswd} before you can view that
handler and change the password for \texttt{lonadm}.)
Many of the environment variables are primarily useful to the authentication
and permission routines (such as \texttt{Apache::lonnet::allowed}),
and are very rarely directly manipulated.
Generally, the \%ENV is informally organized into {}``namespaces'',
such as {}``browser'' (containing browser information), {}``course''
(containing course-specific information), etc. For the following table,
the full name of the variable is the name shown on the left, prepended
by the section it is in. For instance, the first \%ENV member shown
below is \$ENV\{'browser.mathml'\}. Only generally useful portions
of the \%ENV are covered here.
\begin{longtable}{|c|c|}
\hline
\textbf{\%ENV name}&
\textbf{Description}\tabularnewline
\hline
\endfirsthead
\textbf{browser:}&
\tabularnewline
\hline
.mathml&
if true, browser support MathML\tabularnewline
\hline
.os&
indicates OS of browser\tabularnewline
\hline
.type&
indicates type of browser ({}``ie'', {}``mozilla'', etc)\tabularnewline
\hline
.version&
version of the browser\tabularnewline
\hline
\textbf{environment:}&
\tabularnewline
\hline
.firstname&
user's firstname\tabularnewline
\hline
.generation&
user's generation ({}``1st'', {}``jr.'', etc)\tabularnewline
\hline
.id&
institution-specific ID number\tabularnewline
\hline
.lastname&
user's lastname\tabularnewline
\hline
.middlename&
user's middle name\tabularnewline
\hline
.remote&
'on' if the user has the remote open\tabularnewline
\hline
\textbf{request:}&
\tabularnewline
\hline
.course.fn&
{}``full name'' of the course directory\tabularnewline
\hline
.course.id&
ID of the course currently logged into\tabularnewline
\hline
.course.sec&
current section of the course the user is in\tabularnewline
\hline
.course.uri&
URI of the top-level map\tabularnewline
\hline
.filename&
requested filename for current request\tabularnewline
\hline
.host&
originating IP of request\tabularnewline
\hline
.role&
full role designation for the course\tabularnewline
\hline
.role.adv&
whether the user is {}``advanced''; generally don't use\tabularnewline
\hline
.role.domain&
domain of the current course\tabularnewline
\hline
\textbf{user:}&
\tabularnewline
\hline
.adv&
whether the user is {}``advanced''; generally don't use\tabularnewline
\hline
.author&
whether the user is an author\tabularnewline
\hline
.domain&
domain the user is from\tabularnewline
\hline
.home&
user's home server\tabularnewline
\hline
.name&
user's login name\tabularnewline
\hline
\end{longtable}
Other variables are frequently available, and you can add new ones
easily; see \texttt{Apache::lonnet::appenv()} and friends.
Index: loncom/html/adm/help/tex/Guts_Apache_Modules.tex
+++ loncom/html/adm/help/tex/Guts_Apache_Modules.tex
\begin{figure}
\begin{lyxcode}
<LocationMatch~\char`\"{}\textasciicircum{}/res.{*}\char`\"{}>
PerlAccessHandler~~~~~~~Apache::lonacc
PerlHeaderParserHandler~Apache::lonrep
ErrorDocument~~~~~403~/adm/login
ErrorDocument~~~~~404~/adm/notfound.html
ErrorDocument~~~~~406~/adm/roles
ErrorDocument~~~~~500~/adm/errorhandler
</LocationMatch>
<LocationMatch~\char`\"{}\textasciicircum{}/priv.{*}\char`\"{}>
PerlAccessHandler~Apache::loncacc
SetHandler~~~~~~~~perl-script
PerlHandler~~~~~~~Apache::lonconstruct
ErrorDocument~~~~~403~/adm/login
ErrorDocument~~~~~404~/adm/notfound.html
ErrorDocument~~~~~406~/adm/unauthorized.html
ErrorDocument~~~~~500~/adm/errorhandler
</LocationMatch>
\end{lyxcode}
\caption{\label{loncapa_apache.conf example}\texttt{loncapa\_apache.conf}
example snippet}
\end{figure}
Which chain of handler deals with which kind of resource is defined
in \texttt{/etc/httdp/conf/loncapa\_apache.conf}. LON-CAPA only defines
handlers at the header-parser, access control, and response phase
(figure 3-3 Eagle book). In the header-parser phase, the replication
handler is run, and in the access-control phase, the various access-handlers.
Future handlers will mostly be implemented in the response phase.
Fig. \ref{loncapa_apache.conf example} shows excerpts of the configuration
script \texttt{/etc/httpd/loncapa\_apache.conf} for these modules.
Index: loncom/html/adm/help/tex/Guts_Authentication.tex
+++ loncom/html/adm/help/tex/Guts_Authentication.tex
On the library servers, it is a routine in \texttt{lond} that does
the authentication. It checks if this is the user's homeserver, checks
the password, and answers with {}``unknown\_user'', {}``authorized''
or {}``non\_authorized''.
Determination if this is the user's homeserver is done by the presence
of his or her password file in
\texttt{/home/httpd/lonUsers/domain/1.char/2.char/3.char/username/passwd}
for example
\texttt{/home/httpd/lonUsers/msu/s/m/i/smith/passwd}
The password is stored in the format \texttt{mechanism:info}, where
mechanism can currently be unix, krb4 or internal. For krb4, the info
is the Kerberos domain, for internal it is the crypt password itself.
unix simply authenticates against /etc/passwd.
Index: loncom/html/adm/help/tex/Guts_Coding_Guidelines.tex
+++ loncom/html/adm/help/tex/Guts_Coding_Guidelines.tex
Things to keep in mind while coding handlers for LON-CAPA:
\begin{enumerate}
\item \textbf{DON'T} write to Access machine disks with permanent data.
Use \texttt{Apache::lonnet::store/restore}.
\item \textbf{DO} \texttt{use strict;}
\item \textbf{DON'T} use \texttt{print()}. Use \texttt{\$request->print()}.
(Unfortunately, \texttt{print} sometimes seems to work while writing
the handler, but will it will fail unpredictably in real usage.)
\item \textbf{DON'T} launch children.
\item \textbf{DO} \texttt{use strict;}
\item \textbf{DO} use \texttt{\$Apache::lonnet::perlvar\{'lonDaemons'\}/tmp}
for temporary data.
\item \textbf{DO} query the return value of every file operation.
\item \textbf{DO} familiarize your self with the functions in lonnet.pm
and use them to communicate with other servers and when your handler
needs to ask questions.
\item \textbf{DON'T} use \texttt{\&Apache::lonnet::reply()}; use the proper
wrapper functions.
\item \textbf{DO} \texttt{use strict;}\end{enumerate}
Index: loncom/html/adm/help/tex/Guts_Course_Dir.tex
+++ loncom/html/adm/help/tex/Guts_Course_Dir.tex
\label{Guts_Course_Dir}
Courses are assigned to users, not vice versa. Internally, courses
are handled like users without login privileges. The username is a
unique ID, for example \texttt{msu\_12679c3ed543a25msul1}. Every course
in every semester has a unique ID; there is no {}``semester transition'',
course expire and other courses take their place. The userdata of
the course includes the full name of the course, a pointer to its
top-level resource map ({}``course map''), and any associated deadlines,
spreadsheets, etc., as well as a course enrollment list. The latter
is somewhat redundant, since in principle, this list could be produced
by going through the roles of all users, and looking for the valid
role of being student in that course, but for performance reasons
this is cached.
%
\begin{figure}
\begin{lyxcode}
\#>~ls~-alF~/home/httpd/lonUsers/msu/1/2/6/12679c3ed543a25msul1/
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~~17155~Apr~25~16:20~classlist.db
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~60912~Apr~25~16:20~classlist.hist
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~~12354~Jan~~4~16:40~environment.db
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~~~~82~Jan~~4~16:40~environment.hist
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~103030~May~15~14:47~nohist\_calculatedsheets.db
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~~13050~May~~9~21:04~nohist\_expirationdates.db
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~~~~~6~Jan~~4~16:40~passwd
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~~17457~May~~9~21:04~resourcedata.db
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~~8888~May~~9~21:04~resourcedata.hist~
\end{lyxcode}
\caption{Sample course home directory listing}
\end{figure}
\texttt{classlist} is this list of students in the course, \texttt{environment}
includes the course's full name, etc, and \texttt{resourcedata} contains
deadlines, parameters for homework, etc.
Index: loncom/html/adm/help/tex/Guts_User_Dir.tex
+++ loncom/html/adm/help/tex/Guts_User_Dir.tex
\label{Guts_User_Dir}
Every user in the system has one library server, which is their home
server. It stores the authoritative copy of all of their records.
Internally, this data is stored in a directory
\texttt{/home/httpd/lonUsers/}\texttt{\emph{domain}}\texttt{/}\texttt{\emph{firstChar}}\texttt{/}\texttt{\emph{secondChar}}\texttt{/}\texttt{\emph{thirdChar}}\texttt{/}\texttt{\emph{login}}
for example, for {}``smith'' at {}``msu'':
\texttt{/home/httpd/lonUsers/msu/s/m/i/smith/}
%
\begin{figure}
\begin{lyxcode}
\#>~ls~-alF~/home/httpd/lonUsers/msu/k/o/r/kortemey
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~13006~May~15~12:21~activity.log
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~~12413~Oct~26~~2000~coursedescriptions.db
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~11361~Oct~26~~2000~coursedescriptions.hist
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~~13576~Apr~19~17:45~critical.db
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~~1302~Apr~19~17:45~critical.hist
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~~13512~Apr~19~17:45~email\_status.db
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~~1496~Apr~19~17:45~email\_status.hist
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~12373~Apr~19~17:45~environment.db
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~~~169~Apr~19~17:45~environment.hist
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~~12315~Oct~25~~2000~junk.db
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~~1590~Nov~~4~~1999~junk.hist
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~~23626~Apr~19~17:45~msu\_12679c3ed543a25msul1.db
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~~3363~Apr~19~17:45~msu\_12679c3ed543a25msul1.hist
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~~17242~Nov~13~~2000~msu\_1827338c7d339a3msul1.db
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~~1986~Nov~13~~2000~msu\_1827338c7d339a3msul1.hist
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~~18497~Dec~21~11:25~msu\_1827338c7d339b4msul1.db
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~~3801~Dec~21~11:25~msu\_1827338c7d339b4msul1.hist
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~~12470~Apr~19~17:45~nohist\_annotations.db
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~~13395~Nov~15~~2000~nohist\_bookmarks.db
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~104264~Apr~19~17:45
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~nohist\_calculatedsheets\_msu\_12679c3ed543a25msul1.db
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~~13248~Apr~~5~17:18
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~nohist\_calculatedsheets\_msu\_1827338c7d339b4msul1.db
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~~12568~Oct~28~~2000~nohist\_coursedescriptions.db
-rw-r-{}-{}-{}-{}-~~~1~www~~~~~~users~~~~~~765954~Apr~19~17:45~nohist\_email.db
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~710631~Apr~19~17:45~nohist\_email.hist
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~~~~13~Apr~19~17:45~passwd
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~12802~May~~3~13:08~roles.db
-rw-r-{}-r-{}-~~~1~www~~~~~~users~~~~~~~~1316~Apr~12~16:05~roles.hist
\end{lyxcode}
\caption{Sample user directory listing}
\end{figure}
Files ending in \texttt{.db} are GDBM files, files ending in \texttt{.hist}
are logs of entries to these files. Filenames starting with \texttt{nohist}
do not keep history files. \texttt{passwd} stores the login mechanism
and password (if applicable).
\texttt{environment} stores name-value pairs that are automatically
added to the session environment at login time, for example the full
name, etc.
\texttt{roles} stores the user's roles.
\texttt{critical}, \texttt{nohist\_email}, and \texttt{email\_status}
are used by the messaging mechanisms
Files with a course-ID as name, for example \texttt{msu\_12679c3ed543a25msul1.db},
store performance data for that student in the course, as stored by
\texttt{store} and \texttt{restore} in \texttt{lonnet}.
Other files are caches, for example for previously calculated spreadsheets,
etc.
Index: loncom/html/adm/help/tex/Resource_Discussion.tex
+++ loncom/html/adm/help/tex/Resource_Discussion.tex
\label{Resource_Discussion}
Unless banned by an instructor, all resources in the course can host
discussion, which means students may post comments that will appear
for all viewers on the resource. Course members will see new discussion
on their Navigation screens. Instructors may allow course members
to post anonymously or not, and course personnel can see who posted
the anonymous messages. Anonymous only prevents students from seeing
the poster. (Sometime instructors or TAs post anonymously to discreetly
help the students.) Course personnel may hide or delete inappropriate
messages.
Users use the same mechanisms to post to resources and to send internal
email to resource authors or course administrators, and the user can
do more then one of these things at the same time with a message simply
by clicking multiple checkboxes.
Index: loncom/html/adm/help/tex/Roles_About.tex
+++ loncom/html/adm/help/tex/Roles_About.tex
\label{Roles_About}
LON-CAPA has two basic types of Roles, {}``domain'' and {}``course''
roles.
While LON-CAPA is a role based system, a {}``role'' is really a
collection of {}``permissions'', such as {}``permission to post''
or {}``permission to change student grades''. For a complete list
of currently existing permissions, please consult \texttt{/home/httpd/lonTabs/rolesplain.tab}
in a LON-CAPA install. For a complete definition of the various roles
described below, consult the \texttt{/home/httpd/lonTabs/roles.tab},
in conjunction with the \texttt{rolesplain.tab} file.
Domain Administrators and Course Coordinators can create custom roles,
so the following only discusses the roles that LON-CAPA ships with,
and is not necessarily an exhaustive list, just the common ones. As
a developer, it is generally better to look at the \emph{permissions}
a user has when determining whether they can perform an action, rather
then their specific role.
{}``Domain'' roles are roles that apply to the domain in general.
The standard domain roles are:
\begin{itemize}
\item \textbf{Domain adminstrator}\index{Domain Adminstrator}: The domain
adminstrator is the {}``superuser'' of that domain. The administrator
can create new users or modify existing users, create new courses,
and assign any role to users for domain or course roles in that domain.
They do not actually have direct control over courses being run in
that domain, but they can freely assign themselves {}``Course Coordinator''
roles for any course in the domain, so they do theoretically have
access to all information in their domain.
\item \textbf{Librarian}\index{Librarian}: The librarian has access to
all the resources in the domain. As the name implies this is generally
for cataloging purposes.
\item \textbf{Domain Guest}\index{Domain Guest}: A Domain Guest has the
priviledges to log on to a domain and view public resources, but does
not belong to any course or have any other priviledges.
\item \textbf{Author}\index{Author}: An author has an authoring space and
the privilidge to create new resources. Please see the Author's Manual
for more information about what an Author can do (http://msu.loncapa.org/adm/help/author.manual.pdf).
\end{itemize}
{}``Course'' roles apply to specific courses. The standard roles
are:
\begin{itemize}
\item \textbf{Course Coordinator}\index{Course Coordinator}: The Course
Coordinator has full control over the course, including assigning
roles in the course and such. Typically the person {}``most responsible''
for the course will be given this role, which if there is only one
instructor will be that instructor.
\item \textbf{Instructor}\index{Instructor}: Has power over the students
in the course, but can not assign roles or do other {}``admin''
type things. This role can also be attached to a specific section.
\item \textbf{Student}\index{Student}: Has permission to view the course,
do the homework, use the communication mechanisms unless specifically
banned by the instructors, and little else.
\item \textbf{Teaching Assistant}\index{Teaching Assistant}: Can view and
modify grades of other students, and delete messages from the course
discussion. Can be limited to sections.
\item \textbf{Exam Proctor}\index{Exam Proctor}: Can set grades for students.
Very limited.
\end{itemize}
For an exhaustive list and description of the roles LON-CAPA ships
with, see \texttt{www.loncapa.org/roles.html}.
Index: loncom/html/adm/help/tex/What_Is_LON-CAPA.tex
+++ loncom/html/adm/help/tex/What_Is_LON-CAPA.tex
\label{What_Is_LON-CAPA.tex}
The \textbf{L}earning\textbf{O}nline \textbf{N}etwork with a \textbf{C}omputer
\textbf{A}ssisted \textbf{P}ersonalized \textbf{A}pproach (LON-CAPA)
is an integrated system for online learning and assessment. It consists
of a learning content authoring and management system allowing new
and existing content to be used flexibly, a course management system,
an individualized homework and automatic grading system, data collection
and data mining system, and a content delivery system that will provide
gateways to and from NSF's National STEM Digital Library.
In particular:
\begin{itemize}
\item The LON-CAPA software provides instructors with a common, scalable
platform to assist in all aspects of teaching a course, from lecture
preparation to administration of homework assignments and exams. It
allows instructors to create educational materials and to share such
learning resources with colleagues across institutions in a simple
and efficient manner.
\item It provides an extremely sophisticated assignment engine that can
create unique homework assignments and examinations for each student
in a class. Its formative and summative assessment tools grade a broad
variety of objective problems and assist in evaluation of essays.
\item It provides prompt feedback for students and instructors, as well
as statistical information on performance and on effectiveness of
materials. Discussion pages attached to every homework assignment
encourage communication among students and faculty.
\end{itemize}
The LON-CAPA software is freely available and free (GNU General Public
License), and may be modified and adapted.
LON-CAPA is being developed and implemented by an enthusiastic group
of faculty and professionals who recognize that Information Technology
can play an important role in improving students' learning and understanding.
Current members of the project include faculty from universities,
colleges, and K-12 schools in the US, Canada, Asia, Africa, and Europe.
The core development group is located at Michigan State University.
Index: loncom/html/adm/help/tex/Why_LON-CAPA.tex
+++ loncom/html/adm/help/tex/Why_LON-CAPA.tex
\label{Why_LON-CAPA}
There are tens of learning management systems to choose from. Why
should you choose LON-CAPA over the competition?
\begin{itemize}
\item \textbf{Unparalleled assessment engine}: The assessment engine in
LON-CAPA is the beneficiary of over a decade of development and refinement.
Few projects are even in the same league of the LON-CAPA project in
experience with sophisticated homework problems. Sophisticated randomization
features go well beyond merely randomizing the order of multiple choice
problems; everything can be randomized, from the exact parameters
in a given numerical problem to \emph{which} parameters are missing
for a given student. See our Author's Manual for an idea of how powerful
the assessment engine is (http://msu.loncapa.org/adm/help/author.manual.pdf),
or try our Demo Course (http://demo.lon-capa.org/cgi-bin/signon.pl).
Along with powerful online assessment, the randomization can be taken
off-line as well. Customized exams can be printed for each student,
taking full advantage of the randomization. Most of the usual forms
of cheating on an exam are effectively impossible when each student
gets a different exam. LON-CAPA integrates directly with some forms
of scanning systems (and as long as you can get the input from the
system in some manner, LON-CAPA can integrate with it with a little
programmer support), and supports partial handgrading: An instructor
or a TA can examine a single essay problem on an otherwise multiple-choice
exam, and encode a score for the essay problem before sending the
answer form for grading.
\item mention development in an aggresive student cheating environment?
Should probably be attached to pedagogical advantages, along with
a mention of tens of thousands of students in the system.
\item \textbf{Full course support}: LON-CAPA is capable of running your
entire course from top to bottom. LON-CAPA can host all of the content
of the course, from syllabuses to actual course materials. It can
track your students grades, with as much power as you need. Want to
give students bonuses for getting a problem right on the first try?
Or insert external grades into the system from an external data source?
Powerful communication features enable discussion between the instructors
and students, or among the students themselves. From the initial course
creation to the final grades readout, LON-CAPA has all the power you
need to run courses.
\item \textbf{It's free}\index{free}: The thousands or millions you save
over expensive course management solutions can be better spent on
computers, or directly spent on your students. LON-CAPA can frequently
do more with less then some of the largest commercial competitors,
too.
\item \textbf{It's free}\index{free}: As in liberty. No need to buy an
extra-special license just to have the privilege of developing extensions
to the system. You have full access to the entire system. You aren't
restricted to carefully delimited parts of the system the vendor deems
{}``safe'' for you to access. You also have full access to all the
data on the system; LON-CAPA never locks up your data. There aren't
any hidden secrets in the system, either, when you're free to scrutinize
all of the source code. And it won't become closed later either, thanks
to the licensing.
\item \textbf{Large Digital Library}: LON-CAPA's digital library means you
have access to thousands of high-quality learning resources right
off the bat, without writing them yourself. Since one of LON-CAPA
driving motivations is resource sharing, you have full support for
it at any granularity, from simply using other's freely available
resource, to a multi-institution grant-funded large-scale collaboration
project, to simply re-using content used last year in the same course.
\item \textbf{Power for the Users}: LON-CAPA's grants a lot of power to
the instructors to control their course; the system imposes minimal
arbitrary restrictions on the instructors because the design is mature.
To get an idea of what the instructors can do, see our Course Management
Manual (http://msu.loncapa.org/adm/help/course.manual.pdf).
\item \textbf{Improve Student's Performance}: Several studies have repeatedly
shown that using LON-CAPA can significantly improve student performance.
One especially interesting result has been its ability to nearly eliminate
the gender gap in technical subjects such as physics, where men have
traditionally outperformed women.
\end{itemize}
--bowersj21061396260--