Annotation of doc/homework/xml.html, revision 1.4

1.1       albertel    1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
                      2: <html>
                      3:   <head>
                      4:     <title>XML / Style Files</title>
                      5:   </head>
                      6: 
                      7:   <body>
                      8:     <h1>XML / Style Files</h1>
                      9: 
                     10:     <h2>XML Files</h2>
                     11:     <p>
                     12:       All HTML / XML files are run through the lonxml handler before
                     13:       being served to a user. This allows us to rewrite many portion
                     14:       of a document and to support serverside tags. There are 2 ways
                     15:       to add new tags to the xml parsing engine, either through
                     16:       LON-CAPA style files or by writing Perl tag handlers for the
                     17:       desired tags.
                     18:     </p>
                     19:     
                     20:     <h3>Global Variables</h3>
                     21:     <ul>
                     22:       <li>
1.2       albertel   23: 	<i>$Apache::lonxml::debug</i> - debugging control
1.1       albertel   24:       </li>
                     25:       <li>
1.2       albertel   26: 	<i>@Apache::lonxml::pwd</i> - path to the directory containing the file currently being processed 
1.1       albertel   27:       </li>
                     28:       <li>
1.2       albertel   29: 	<i>@Apache::lonxml::outputstack</i> <br />
                     30: 	<i>$Apache::lonxml::redirection</i> - these two are used for
                     31: 	capturing a subset of the output for later processing, don't
                     32: 	touch them directly use &startredirection and &endredirection
1.1       albertel   33:       </li>
                     34:       <li>
1.2       albertel   35: 	<i>$Apache::lonxml::import</i> - controls whether the
                     36: 	&lt;import&gt; tag actually does anything
1.1       albertel   37:       </li>
                     38:       <li>
1.3       albertel   39: 	<i>@Apache::lonxml::extlinks</i> - a list of URLs that the
                     40: 	user is allowed to look at because of the current resource
                     41: 	(images, and links)
1.1       albertel   42:       </li>
                     43:       <li>
1.2       albertel   44: 	<i>#Apache::lonxml::metamode</i> - some output is turned off,
                     45: 	the meta target wants a specific subset, use &lt;output&gt; to
                     46: 	guarentee that the catianed data will be in the parsing output
1.1       albertel   47:       </li>
                     48:       <li>
1.2       albertel   49: 	<i>#Apache::lonxml::evaluate</i> - controls whether
                     50: 	run::evaluate actually derefences variable references
1.1       albertel   51:       </li>
                     52:       <li>
1.2       albertel   53: 	<i>%Apache::lonxml::insertlist</i> - data structure for edit
                     54: 	mode, determines what tags can go into what other tags
1.1       albertel   55:       </li>
                     56:       <li>
1.2       albertel   57: 	<i>@Apache::lonxml::namespace</i> - stores the list of tag
                     58: 	namespaces used in the insertlist.tab file that are currently
                     59: 	active, used only in edit mode.
1.1       albertel   60:       </li>
1.3       albertel   61:       <li>
                     62: 	<i>$Apache::lonxml::registered</i> - set to 1 once the remote
                     63: 	has been updated to know what resource we are looking at.
                     64:       </li>
1.4     ! albertel   65:       <li>
        !            66: 	<i>$Apache::lonxml::request</i> - current Apache request
        !            67: 	object, or undef
        !            68:       </li>
1.1       albertel   69:     </ul>
                     70: 	
                     71:     <h3>Notable Perl subroutines</h3>
                     72:     <p>
                     73:       If not specified these functions are in Apache::lonxml
                     74:     </p>
                     75:     <ul>
                     76:       <li>
                     77: 	<i>xmlparse</i> - see the XMLPARSE figure
                     78:       </li>
                     79:       <li>
                     80: 	<i>recurse</i> - acts just like <i>xmlparse</i>, except it
                     81: 	doesn't do the style definition check it always calls
                     82: 	<i>callsub</i>
                     83:       </li>
                     84:       <li>
                     85: 	<i>callsub</i> - callsub looks if a perl subroutine is defined
                     86: 	for the current tag and calls. Otherwise it just returns the
                     87: 	tag as it was read in. It also will throw on a default editing
                     88: 	interface unless the tag has a defined subroutine that either
                     89: 	returns something or requests that call sub not add the
                     90: 	editing interface.
                     91:       </li>
                     92:       <li>
                     93: 	<i>afterburn</i> - called on the output of xmlparse, it can
                     94: 	add highlights, anchors, and links to regular expersion
                     95: 	matches to the output.
                     96:       </li>
                     97:       <li>
                     98: 	<i>register_insert</i> - builds the
                     99: 	%Apache::lonxml::insertlist structure of what tags can have
                    100: 	what other tags inside.
                    101:       </li>
1.3       albertel  102:       <li>
                    103: 	<i>whichuser</i> - returns a list of $symb, $courseid,
                    104: 	$domain, $name that is correct for calls to lonnet functions
                    105: 	for this setup. Uses form.grade_ parameters, if the user is
                    106: 	allowed to mgr in the course
                    107:       </li>
1.1       albertel  108:     </ul>
                    109:     <h3>Functions Tag Handlers can use</h3>
                    110:     <p>
                    111:       If not specified these functions are in Apache::lonxml
                    112:     </p>
                    113:     <ul>
                    114:       <li>
                    115: 	<i>debug</i> - a function to call to printout debugging
                    116: 	messages. Will only print when Apache::lonxml::debug is set to
                    117: 	1
                    118:       </li>
                    119:       <li>
                    120: 	<i>warning</i> - a function to use for warning messages. The message
                    121: 	will appear at the top of a resource when it is viewed in
                    122: 	construction space only.
                    123:       </li>
                    124:       <li>
                    125: 	<i>error</i> - a function to use for error messages. The
                    126: 	message will appear at the top of a resource when it is viewed
                    127: 	in construction space, and will message the resource author
                    128: 	and course instructor, while informing the student that an
                    129: 	error has occured otherwise.
                    130:       </li>
                    131:       <li>
                    132: 	<i>get_all_text</i> - 2 args, tag to look for (need to use
                    133: 	/tag to look for an end tag) and a HTML::TokeParser reference,
                    134: 	it will repedelyt get text from the TokeParser until the
                    135: 	requested tag is found. It will return all of the document it
                    136: 	pulled form the TokeParser. (See
                    137: 	Apache::scripttag::start_script for an example of usage.)
                    138:       </li>
                    139:       <li>
                    140: 	<i>get_param</i> - 4 arguments, firsth is a scaler sting of
                    141: 	the argument needed, second is a reference to the parser
                    142: 	arguments stack, third is a reference to the Safe space, and
                    143: 	fourth is an optional "context" value. This subroutine allows
                    144: 	a tag to get a tag argument, after being interpolated inside
                    145: 	the Safe space. This should be used if the tag might use a
                    146: 	safe space variable reference for the tag argument. (See
                    147: 	Apaceh::scripttag::start_script for an example.)
                    148:       </li>
                    149:       <li>
                    150: 	<i>newparser</i> - 3 args, first is a reference to the parser
                    151: 	stack, second should be a reference to a string scaler
                    152: 	containg the text the newparser should run over, third should
                    153: 	be a scaler of the directory path the file the parser is
                    154: 	parsing was in. (See Apache::scripttag::start_import for an
                    155: 	example.)
                    156:       </li>
                    157:       <li>
                    158: 	<i>register</i> - should be called in a file's BEGIN block. 2
                    159: 	arguments, a scaler string, and a list of strings. This allows
                    160: 	a file to register what tags it handles, and what the
                    161: 	namespace of those tags are. Example:
                    162: <pre>
                    163: sub BEGIN {
                    164:   &Apache::lonxml::register('Apache::scripttag',('script','display'));
                    165: }
                    166: </pre>
                    167: 	Would tell xmlparse that in Apache::scripttag it can find
                    168: 	handlers for &lt;script&gt; and &lt;display&gt;
                    169:       </li>
                    170:       <li>
                    171: 	<i>startredirection</i> - used when a tag wants to save a
                    172: 	portion of the document for its end tag to use, but wants the
                    173: 	intervening document to be normally processed. (See
                    174: 	Apache::scripttag::start_window for an example.)
                    175:       </li>
                    176:       <li>
                    177: 	<i>endredirection</i> - used to stop preventing xmlparse from
                    178: 	hiding output. The return value is everthing that xmlparse has
                    179: 	processed since the corresponding startredirection. (See
                    180: 	Apache::scripttag::end_window for an example.)
                    181:       </li>
                    182:       <li>
                    183: 	<i>Apache::run::evaluate</i> - 3 args, first a string, second
                    184: 	a reference to the Safe space, 3 a string to be evaluated
                    185: 	before the first arg. This subroutine will do variable
                    186: 	interpolation and simple function interpolations on the first
                    187: 	argument. (See Apache::lonxml::xmlparse for an example.)
                    188:       </li>
                    189:       <li>
                    190: 	<i>Apache::run::run</i> - 2 args, first a string, second a
                    191: 	reference to the Safe space. This handles passing the passed
                    192: 	string into the Safe space for evaluation and then returns the
                    193: 	result. (See Apache::scripttag::start_script for an example.)
                    194:       </li>
                    195:     </ul>
                    196: 
                    197:     <h2>Style Files</h2>
                    198:     <h3>Style File specific tags</h3>
                    199:     <ul>
                    200:       <li>
1.2       albertel  201: 	<b>&lt;definetag&gt;</b> - 2 arguments, <i>name</i> name of
                    202: 	new tag being defined, if proceeded with a / defining an end
                    203: 	tag, required; <i>parms</i> parameters of the new tag, the
                    204: 	value of these parameters can be accesed by $parametername.
1.1       albertel  205:       </li>
                    206:       <li>
1.2       albertel  207: 	<b>&lt;render&gt;</b> - define what the new tag does for a non meta target
1.1       albertel  208:       </li>
                    209:       <li>
1.2       albertel  210: 	<b>&lt;meta&gt;</b> - define what the new tag does for a meta target
1.1       albertel  211:       </li>
                    212:       <li>
1.2       albertel  213: 	<b>&lt;tex&gt; / &lt;web&gt; / &lt;latexsource&gt;</b> -
                    214: 	define what a new tag does for a specific no meta target, all
                    215: 	data inside a &lt;render&gt; is render to all targets except
                    216: 	when surrounded by a specific target tags.
1.1       albertel  217:       </li>
                    218:     </ul>
                    219:     <hr>
                    220:     <address><a href="mailto:albertel@marvin.lite.msu.edu">Guy Albertelli</a></address>
                    221: <!-- Created: Sun May 20 15:47:08 EDT 2001 -->
                    222: <!-- hhmts start -->
1.4     ! albertel  223: Last modified: Thu May 23 17:19:29 EDT 2002
1.1       albertel  224: <!-- hhmts end -->
                    225:   </body>
                    226: </html>

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