File:  [LON-CAPA] / doc / homework / xml.html
Revision 1.7: download - view: text, annotated - select for diffs
Mon Oct 21 20:31:06 2002 UTC (21 years, 5 months ago) by albertel
Branches: MAIN
CVS tags: version_2_9_X, version_2_9_99_0, version_2_9_1, version_2_9_0, version_2_8_X, version_2_8_99_1, version_2_8_99_0, version_2_8_2, version_2_8_1, version_2_8_0, version_2_7_X, version_2_7_99_1, version_2_7_99_0, version_2_7_1, version_2_7_0, version_2_6_X, version_2_6_99_1, version_2_6_99_0, version_2_6_3, version_2_6_2, version_2_6_1, version_2_6_0, version_2_5_X, version_2_5_99_1, version_2_5_99_0, version_2_5_2, version_2_5_1, version_2_5_0, version_2_4_X, version_2_4_99_0, version_2_4_2, version_2_4_1, version_2_4_0, version_2_3_X, version_2_3_99_0, version_2_3_2, version_2_3_1, version_2_3_0, version_2_2_X, version_2_2_99_1, version_2_2_99_0, version_2_2_2, version_2_2_1, version_2_2_0, version_2_1_X, version_2_1_99_3, version_2_1_99_2, version_2_1_99_1, version_2_1_99_0, version_2_1_3, version_2_1_2, version_2_1_1, version_2_1_0, version_2_12_X, version_2_11_X, version_2_11_4_uiuc, version_2_11_4_msu, version_2_11_4, version_2_11_3_uiuc, version_2_11_3_msu, version_2_11_3, version_2_11_2_uiuc, version_2_11_2_msu, version_2_11_2_educog, version_2_11_2, version_2_11_1, version_2_11_0_RC3, version_2_11_0_RC2, version_2_11_0_RC1, version_2_11_0, version_2_10_X, version_2_10_1, version_2_10_0_RC2, version_2_10_0_RC1, version_2_10_0, version_2_0_X, version_2_0_99_1, version_2_0_2, version_2_0_1, version_2_0_0, version_1_99_3, version_1_99_2, version_1_99_1_tmcc, version_1_99_1, version_1_99_0_tmcc, version_1_99_0, version_1_3_X, version_1_3_3, version_1_3_2, version_1_3_1, version_1_3_0, version_1_2_X, version_1_2_99_1, version_1_2_99_0, version_1_2_1, version_1_2_0, version_1_1_X, version_1_1_99_5, version_1_1_99_4, version_1_1_99_3, version_1_1_99_2, version_1_1_99_1, version_1_1_99_0, version_1_1_3, version_1_1_2, version_1_1_1, version_1_1_0, version_1_0_99_3, version_1_0_99_2, version_1_0_99_1, version_1_0_99, version_1_0_3, version_1_0_2, version_1_0_1, version_1_0_0, version_0_99_5, version_0_99_4, version_0_99_3, version_0_99_2, version_0_99_1, version_0_99_0, version_0_6_2, version_0_6, loncapaMITrelate_1, language_hyphenation_merge, language_hyphenation, conference_2003, bz6209-base, bz6209, HEAD, GCI_3, GCI_2, GCI_1, BZ4492-merge, BZ4492-feature_horizontal_radioresponse, BZ4492-feature_Support_horizontal_radioresponse, BZ4492-Support_horizontal_radioresponse
- default_homework is now lazy loaded by the <script> tag
- fixes BUG#842 (can't use <script> in .html)

<!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> - debugging control
      </li>
      <li>
	<i>@Apache::lonxml::pwd</i> - path to the directory containing
	the file currently being processed
      </li>
      <li>
	<i>@Apache::lonxml::outputstack</i> <br />
	<i>$Apache::lonxml::redirection</i> - these two are used for
	capturing a subset of the output for later processing, don't
	touch them directly use &startredirection and &endredirection
      </li>
      <li>
	<i>$Apache::lonxml::import</i> - controls whether the
	&lt;import&gt; tag actually does anything
      </li>
      <li>
	<i>@Apache::lonxml::extlinks</i> - a list of URLs that the
	user is allowed to look at because of the current resource
	(images, and links)
      </li>
      <li>
	<i>$Apache::lonxml::metamode</i> - some output is turned off,
	the meta target wants a specific subset, use &lt;output&gt; to
	guarentee that the catianed data will be in the parsing output
      </li>
      <li>
	<i>$Apache::lonxml::evaluate</i> - controls whether
	run::evaluate actually derefences variable references
      </li>
      <li>
	<i>%Apache::lonxml::insertlist</i> - data structure for edit
	mode, determines what tags can go into what other tags
      </li>
      <li>
	<i>@Apache::lonxml::namespace</i> - stores the list of tag
	namespaces used in the insertlist.tab file that are currently
	active, used only in edit mode.
      </li>
      <li>
	<i>$Apache::lonxml::registered</i> - set to 1 once the remote
	has been updated to know what resource we are looking at.
      </li>
      <li>
	<i>$Apache::lonxml::request</i> - current Apache request
	object, or undef
      </li>
      <li>
	<i>$Apache::lonxml::curdepth</i> - current depth of the
	overall parse depth. Will be a string like: 2_3_1 (first tag
	in the third second level tag in the second toplevel tag). It
	gets set by callsub, and can be used in Perl tag
	implementations. It relies upon the internal globals:
	<i>@Apache::lonxml::depthcounter</i>,
	<i>$Apache::lonxml::depth</i>,
	<i>$Apache::lonxml::olddepth</i>
      </li>
      <li>
	<i>$Apache::lonxml::prevent_entity_encode</i> - By default the
	xmlparser will try to rencode any 8-bit characters into HTML
	Entity Codes, If this is set to a true value it will be
	prevented.
      </li>
      <li>
	<i>$Apache::lonxml::errorcount</i> - keeps count of the number
	of errors generated in a parse
      </li>
      <li>
	<i>$Apache::lonxml::warningcount</i> - keeps count of the
	number of errors generated in a parse
      </li>
      <li>
	<i>$Apache::lonxml::counter</i> <br />
	<i>$Apache::lonxml::counter_changed</i> - a counter used to
	keep track of the number of questions asked, used currently to
	track bubble numbers, Initialized off of $ENV{'form.counter'},
	and writes this value to the environment if counter_changed is
	true, should use the &increment_counter() function to
	increment this value.
      </li>
      <li>
	<i>$Apache::lonxml::default_homework_loaded</i> - a boolean on
	wherethe the default_homework.lcpm file has been loaded into
	the Safe Space, the function
	&Apache::lonxml::default_homework_load()
      </li>
    </ul>

    <p>
      In common usage, <i>$Apache::lonxml::prevent_entity_encode</i>,
      <i>$Apache::lonxml::evaluate</i>,
      <i>$Apache::lonxml::metamode</i>,
      <i>$Apache::lonxml::import</i>, should never be set to a value
      directly, but rather incremented when you want the effect on,
      and decremented when you want the effect off.
    </p>
    
    <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 - also not callable
	from inside a tag, if one needs to restart parsing, either
	create add a new LCParser to the parser stack parser using the
	newparser function, or call inner_xmlparser, see the xmlparse
	function in scripttag.pm
      </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>
      <li>
	<i>whichuser</i> - returns a list of $symb, $courseid,
	$domain, $name that is correct for calls to lonnet functions
	for this setup. Uses form.grade_ parameters, if the user is
	allowed to mgr in the course
      </li>
      <li>
	<i>setup_globals</i> - initializes all lonxml globals when
	xmlparse is called. If you intend to create a new target you
	will likely need to tweak how the globals are setup upon start
	up.
      </li>
      <li>
	<i>init_safespace</i> - creates Holes to external functions,
	creates some global variables, and set the permitted operators
	of the global Safespace intepreter.
      </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, first 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
	Apache::scripttag::start_script for an example.)
	
	This version only handles scalar variables.
      </li>
      <li>
	<i>get_param_var</i> - 4 arguments, first 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
	Apache::scripttag::start_script for an example.)
	
	This version can handle list or hash variables properly.
      </li>
      <li>
	<i>description</i> - 1 argument, the token object. This will
	return the textual decription of the current tag from the
	insertlist.tab file.
      </li>
      <li>
	<i>whichuser</i> - 0 arguments. This will take a look at the
	current environment setting and return the current $symb,
	$courseid, $udom, $uname. You should always use this function
	if you want to determine who the current user is. (Since a
	instructor might be trying to view a students version of a
	resource.)
      </li>
      <li>
	<i>inner_xmlparse</i> - 6 arguments, the target, an array
	pointer to the current stack of tags, and array pointer to the
	current stack of tag arguments, an array pointer to the
	current stack of LCParser's, a pointer to the current Safe
	space, a pointer to the hash of current style definitions
      </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;, if one
	regsiters a tag that was already registered the previous one
	is remembered and will be restored on a deregister.
      </li>
      <li>
	<i>deregister</i> - used to remove a previously registered tag
	implementation. It will restore the previous registration if
	there was one.
      </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::inner_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> - 2 arguments, <i>name</i> name of
	new tag being defined, if proceeded with a / defining an end
	tag, required; <i>parms</i> parameters of the new tag, the
	value of these parameters can be accesed by $parametername.
      </li>
      <li>
	<b>&lt;render&gt;</b> - define what the new tag does for a non meta target
      </li>
      <li>
	<b>&lt;meta&gt;</b> - define what the new tag does for a meta target
      </li>
      <li>
	<b>&lt;tex&gt; / &lt;web&gt; / &lt;latexsource&gt;</b> -
	define what a new tag does for a specific no meta target, all
	data inside a &lt;render&gt; is render to all targets except
	when surrounded by a specific target tags.
      </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: Mon Oct 21 16:41:56 EDT 2002
<!-- hhmts end -->
  </body>
</html>

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