[LON-CAPA-cvs] cvs: doc /homework newtag.html
albertel
lon-capa-cvs@mail.lon-capa.org
Thu, 06 Jun 2002 08:43:24 -0000
albertel Thu Jun 6 04:43:24 2002 EDT
Added files:
/doc/homework newtag.html
Log:
- most of a document outlining what needs to be done to add a basic tag
-still missing
- useful helper function descriptions
- edit mode
- insertlist.tab
- analyze mode
Index: doc/homework/newtag.html
+++ doc/homework/newtag.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Making a New Tag Handler</title>
</head>
<body>
<h1>Making a New Tag Handler</h1>
<h2>Required Actions</h2>
<ul>
<li>
you will need to call <i>&Apache::lonxml::register()</i>
to register the tag name and the namespace it is in, most of
the time this is in the BEGIN block of the handler
</li>
<li>
you will need to create both <i>&start_newtag()</i> and
<i>&end_newtag()</i> functions.
</li>
<li>
these function will need to do one of:
<ol>
<li>
return a non-null string
</li>
<li>
return a null string (and expect that for some targets a
default output may be generated for it)
</li>
<li>
return a list containing a null string for the first
element and the string 'no' for the second element., this
will make sure that the result is a null string and any
default action normally taken will be skipped
</li>
</ol>
<li>
These functions will have six arguments passed to them
<ol>
<li>
<i>$target</i> a scalar cotaing the string of the target
that is being parsed for. The current possibilities
include web, tex, grade, answer, modified, edit, meta,
analyze. Although more may be added in the future, you
must guarentee that you return a blank string for any
target you don't specifically handle.
</li>
<li>
<i>$token</i> a HTML::LCParser token object,You probably
want to avoid using the parameter information inside of
this, you most likely want to use <i>$paramstack</i> and
<i>&Apache::lonxml::get_param()</i>
</li>
<li>
<i>$tagstack</i> a stack pointer of the names of the tags
that are currently open, don't modify
</li>
<li>
<i>$paramstack</i> a stack pointer of the parameters
passed to the currently open tags, don't modify, and you
probably should use this only as a parameter to
<i>&Apache::lonxml::get_param</i>
</li>
<li>
<i>$parser</i> a stack pointer of the current stack of
HTML::LCParser objects. You probably only want to use the
top one. Also your functions may manipulate this object
and grab more tokens from it but be carefule about
unbalancing it, also avoid calling the ->get_text()
routine unless you really not what you are doing
(<i>&Apache::lonxml::get_all_text()</i> is probably
what you want to use.
</li>
<li>
<i>$safeeval</i> a pointer to the safe space interpreter,
You probably don't what to do anything with this directly,
<i>&Apache::run::run</i> and other functions need this
argument and will use it correctly.
</li>
<li>
<i>$style</i> a Hash reference, it contains mappings
between tags and style file definitions. Few functions
will need to use this.
</li>
</ol>
</li>
<li>
if it is a new response tag it needs to
<ul>
<li>
call <i>&Apache::response::start_response()</i> in the
start_newtag function and
<i>&Apache::response::end_response()</i> at the end of
the end_newtag function
</li>
<li>
set the required data for a responseid from the
datastorage document
</li>
<li>
use the functions
<i>&Apache::response::check_for_previous()</i> and
<i>&Apache::response::handle_previous()</i> to check
if a student's reponse has been submitted before.
</li>
<li>
call <i>&Apache::response::setup_params()</i> if it is
expecting external parameters to be set for it.
</li>
</ul>
</li>
</ul>
<h2>Things to not do</h2>
<ul>
<li>
there is no direct access to the Apache Request object. It is
<b>very</b> unlikely that you need it, any data you want is
either in %ENV, a global variable listed below or in the xml
documentation, or should be gotten through an Apache::lonnet
function
</li>
<li>
print, either return it in the result, or use the
debug/warning/error facility of Apache::lonxml
</li>
<li>
use the <i>get_text()</i> procedure of the $parser
HTML::LCParser object
</li>
<li>
access the paramater attributes of the $token HTML::LCParser
object
</li>
</ul>
<h2>Interesting Globals</h2>
<ul>
<li> lonhomework globals
<ul>
<li>
<i>%Apache::lonhomework::history</i> the data from a restore
call for the current symb
</li>
<li>
<i>%Apache::lonhomework::results</i> the hash that will be
cstored at the end of the current execution
</li>
<li>
<i>$Apache::lonhomework::browse</i> the result of an allowed
request for the bre priviledge on the current file
</li>
<li>
<i>$Apache::lonhomework::viewgrades</i> the result of an
allowed request on the vgr priviledge for the current course
</li>
<li>
<i>$Apache::lonhomework::type</i> the current type of the
resource, either '', exam, homework, quiz, form, or survey
</li>
<li>
<i>%Apache::lonhomework::analyze</i> in analyze mode all data
to be returned is sotred in here.
</li>
</ul>
</li>
<li>
inputtag globals
<ul>
<li>
<i>@Apache::inputtags::input</i> list of current input ids
</li>
<li>
<i>@Apache::inputtags::inputlist</i> list of all input ids
seen in this problem
</li>
<li>
<i>@Apache::inputtags::response</i> list of all current
response ids
</li>
<li>
<i>@Apache::inputtags::responselist</i> list of all
response ids seen in this problem
</li>
<li>
<i>@Apache::inputtags::previous</i> list of whether or not
a specific response was previously used
</li>
<li>
<i>$Apache::inputtags::part</i> id of current part, 0
means that no part is current (inside <problem>
only)
</li>
<li>
<i>@Apache::inputtags::status</i> list of problem date
statuses, the first element is for <problem> if
there is a second element it is for the current
<part> possible values are CLOSED, CAN_ANSWER,
SHOW_ANSWER, UNCHECKEDOUT
</li>
<li>
<i>%Apache::inputtags::params</i> hash of defined params
for the current response
</li>
<li>
<i>@Apache::inputtags::import</i> list of all ids, from
<import>s, these get join()ed and prepended to the
ids in the @Apache::inputtags::response and
@Apache::inputtags::responselist variables
</li>
</ul>
</li>
</ul>
<h2>Interesting Function</h2>
<hr>
<address><a href="mailto:albertel@msu.edu"></a></address>
<!-- Created: Thu Jun 6 03:47:04 EDT 2002 -->
<!-- hhmts start -->
Last modified: Thu Jun 6 04:46:00 EDT 2002
<!-- hhmts end -->
</body>
</html>