File:  [LON-CAPA] / doc / homework / xml.html
Revision 1.1: download - view: text, annotated - select for diffs
Mon May 21 03:35:46 2001 UTC (22 years, 10 months ago) by albertel
Branches: MAIN
CVS tags: HEAD
- added documentation

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>XML / Style Files</title>
  </head>

  <body>
    <h1>XML / Style Files</h1>

    <h2>XML Files</h2>
    <p>
      All HTML / XML files are run through the lonxml handler before
      being served to a user. This allows us to rewrite many portion
      of a document and to support serverside tags. There are 2 ways
      to add new tags to the xml parsing engine, either through
      LON-CAPA style files or by writing Perl tag handlers for the
      desired tags.
    </p>
    
    <h3>Global Variables</h3>
    <ul>
      <li>
	<i>Apache::lonxml::debug</i> -
      </li>
      <li>
	<i>Apache::lonxml::pwd</i> -
      </li>
      <li>
	<i>Apache::lonxml::outputstack</i> -
      </li>
      <li>
	<i>Apache::lonxml::redirection</i> -
      </li>
      <li>
	<i>Apache::lonxml::import</i> -
      </li>
      <li>
	<i>Apache::lonxml::extlinks</i> -
      </li>
      <li>
	<i>Apache::lonxml::metamode</i> -
      </li>
      <li>
	<i>Apache::lonxml::evaluate</i> -
      </li>
      <li>
	<i>Apache::lonxml::insertlist</i> -
      </li>
      <li>
	<i>Apache::lonxml::namespace</i> -
      </li>
      <li>
	<i>Apache::lonxml::</i> -
      </li>
    </ul>
	
    <h3>Notable Perl subroutines</h3>
    <p>
      If not specified these functions are in Apache::lonxml
    </p>
    <ul>
      <li>
	<i>xmlparse</i> - see the XMLPARSE figure
      </li>
      <li>
	<i>recurse</i> - acts just like <i>xmlparse</i>, except it
	doesn't do the style definition check it always calls
	<i>callsub</i>
      </li>
      <li>
	<i>callsub</i> - callsub looks if a perl subroutine is defined
	for the current tag and calls. Otherwise it just returns the
	tag as it was read in. It also will throw on a default editing
	interface unless the tag has a defined subroutine that either
	returns something or requests that call sub not add the
	editing interface.
      </li>
      <li>
	<i>afterburn</i> - called on the output of xmlparse, it can
	add highlights, anchors, and links to regular expersion
	matches to the output.
      </li>
      <li>
	<i>register_insert</i> - builds the
	%Apache::lonxml::insertlist structure of what tags can have
	what other tags inside.
      </li>
    </ul>
    <h3>Functions Tag Handlers can use</h3>
    <p>
      If not specified these functions are in Apache::lonxml
    </p>
    <ul>
      <li>
	<i>debug</i> - a function to call to printout debugging
	messages. Will only print when Apache::lonxml::debug is set to
	1
      </li>
      <li>
	<i>warning</i> - a function to use for warning messages. The message
	will appear at the top of a resource when it is viewed in
	construction space only.
      </li>
      <li>
	<i>error</i> - a function to use for error messages. The
	message will appear at the top of a resource when it is viewed
	in construction space, and will message the resource author
	and course instructor, while informing the student that an
	error has occured otherwise.
      </li>
      <li>
	<i>get_all_text</i> - 2 args, tag to look for (need to use
	/tag to look for an end tag) and a HTML::TokeParser reference,
	it will repedelyt get text from the TokeParser until the
	requested tag is found. It will return all of the document it
	pulled form the TokeParser. (See
	Apache::scripttag::start_script for an example of usage.)
      </li>
      <li>
	<i>get_param</i> - 4 arguments, firsth is a scaler sting of
	the argument needed, second is a reference to the parser
	arguments stack, third is a reference to the Safe space, and
	fourth is an optional "context" value. This subroutine allows
	a tag to get a tag argument, after being interpolated inside
	the Safe space. This should be used if the tag might use a
	safe space variable reference for the tag argument. (See
	Apaceh::scripttag::start_script for an example.)
      </li>
      <li>
	<i>newparser</i> - 3 args, first is a reference to the parser
	stack, second should be a reference to a string scaler
	containg the text the newparser should run over, third should
	be a scaler of the directory path the file the parser is
	parsing was in. (See Apache::scripttag::start_import for an
	example.)
      </li>
      <li>
	<i>register</i> - should be called in a file's BEGIN block. 2
	arguments, a scaler string, and a list of strings. This allows
	a file to register what tags it handles, and what the
	namespace of those tags are. Example:
<pre>
sub BEGIN {
  &Apache::lonxml::register('Apache::scripttag',('script','display'));
}
</pre>
	Would tell xmlparse that in Apache::scripttag it can find
	handlers for &lt;script&gt; and &lt;display&gt;
      </li>
      <li>
	<i>startredirection</i> - used when a tag wants to save a
	portion of the document for its end tag to use, but wants the
	intervening document to be normally processed. (See
	Apache::scripttag::start_window for an example.)
      </li>
      <li>
	<i>endredirection</i> - used to stop preventing xmlparse from
	hiding output. The return value is everthing that xmlparse has
	processed since the corresponding startredirection. (See
	Apache::scripttag::end_window for an example.)
      </li>
      <li>
	<i>Apache::run::evaluate</i> - 3 args, first a string, second
	a reference to the Safe space, 3 a string to be evaluated
	before the first arg. This subroutine will do variable
	interpolation and simple function interpolations on the first
	argument. (See Apache::lonxml::xmlparse for an example.)
      </li>
      <li>
	<i>Apache::run::run</i> - 2 args, first a string, second a
	reference to the Safe space. This handles passing the passed
	string into the Safe space for evaluation and then returns the
	result. (See Apache::scripttag::start_script for an example.)
      </li>
    </ul>

    <h2>Style Files</h2>
    <h3>Style File specific tags</h3>
    <ul>
      <li>
	<b>&lt;definetag&gt;</b> - 
      </li>
      <li>
	<b>&lt;render&gt;</b> - 
      </li>
      <li>
	<b>&lt;meta&gt;</b> - 
      </li>
      <li>
	<b>&lt;tex&gt; / &lt;web&gt; / &lt;latexsource&gt;</b> - 
      </li>
    </ul>

    <hr>
    <address><a href="mailto:albertel@marvin.lite.msu.edu">Guy Albertelli</a></address>
<!-- Created: Sun May 20 15:47:08 EDT 2001 -->
<!-- hhmts start -->
Last modified: Sun May 20 23:34:57 EDT 2001
<!-- hhmts end -->
  </body>
</html>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>