[BACK]Return to xml.html CVS log [TXT] [DIR] Up to [LON-CAPA] / doc / homework
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, 6 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)

    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>
   23: 	<i>$Apache::lonxml::debug</i> - debugging control
   24:       </li>
   25:       <li>
   26: 	<i>@Apache::lonxml::pwd</i> - path to the directory containing
   27: 	the file currently being processed
   28:       </li>
   29:       <li>
   30: 	<i>@Apache::lonxml::outputstack</i> <br />
   31: 	<i>$Apache::lonxml::redirection</i> - these two are used for
   32: 	capturing a subset of the output for later processing, don't
   33: 	touch them directly use &startredirection and &endredirection
   34:       </li>
   35:       <li>
   36: 	<i>$Apache::lonxml::import</i> - controls whether the
   37: 	&lt;import&gt; tag actually does anything
   38:       </li>
   39:       <li>
   40: 	<i>@Apache::lonxml::extlinks</i> - a list of URLs that the
   41: 	user is allowed to look at because of the current resource
   42: 	(images, and links)
   43:       </li>
   44:       <li>
   45: 	<i>$Apache::lonxml::metamode</i> - some output is turned off,
   46: 	the meta target wants a specific subset, use &lt;output&gt; to
   47: 	guarentee that the catianed data will be in the parsing output
   48:       </li>
   49:       <li>
   50: 	<i>$Apache::lonxml::evaluate</i> - controls whether
   51: 	run::evaluate actually derefences variable references
   52:       </li>
   53:       <li>
   54: 	<i>%Apache::lonxml::insertlist</i> - data structure for edit
   55: 	mode, determines what tags can go into what other tags
   56:       </li>
   57:       <li>
   58: 	<i>@Apache::lonxml::namespace</i> - stores the list of tag
   59: 	namespaces used in the insertlist.tab file that are currently
   60: 	active, used only in edit mode.
   61:       </li>
   62:       <li>
   63: 	<i>$Apache::lonxml::registered</i> - set to 1 once the remote
   64: 	has been updated to know what resource we are looking at.
   65:       </li>
   66:       <li>
   67: 	<i>$Apache::lonxml::request</i> - current Apache request
   68: 	object, or undef
   69:       </li>
   70:       <li>
   71: 	<i>$Apache::lonxml::curdepth</i> - current depth of the
   72: 	overall parse depth. Will be a string like: 2_3_1 (first tag
   73: 	in the third second level tag in the second toplevel tag). It
   74: 	gets set by callsub, and can be used in Perl tag
   75: 	implementations. It relies upon the internal globals:
   76: 	<i>@Apache::lonxml::depthcounter</i>,
   77: 	<i>$Apache::lonxml::depth</i>,
   78: 	<i>$Apache::lonxml::olddepth</i>
   79:       </li>
   80:       <li>
   81: 	<i>$Apache::lonxml::prevent_entity_encode</i> - By default the
   82: 	xmlparser will try to rencode any 8-bit characters into HTML
   83: 	Entity Codes, If this is set to a true value it will be
   84: 	prevented.
   85:       </li>
   86:       <li>
   87: 	<i>$Apache::lonxml::errorcount</i> - keeps count of the number
   88: 	of errors generated in a parse
   89:       </li>
   90:       <li>
   91: 	<i>$Apache::lonxml::warningcount</i> - keeps count of the
   92: 	number of errors generated in a parse
   93:       </li>
   94:       <li>
   95: 	<i>$Apache::lonxml::counter</i> <br />
   96: 	<i>$Apache::lonxml::counter_changed</i> - a counter used to
   97: 	keep track of the number of questions asked, used currently to
   98: 	track bubble numbers, Initialized off of $ENV{'form.counter'},
   99: 	and writes this value to the environment if counter_changed is
  100: 	true, should use the &increment_counter() function to
  101: 	increment this value.
  102:       </li>
  103:       <li>
  104: 	<i>$Apache::lonxml::default_homework_loaded</i> - a boolean on
  105: 	wherethe the default_homework.lcpm file has been loaded into
  106: 	the Safe Space, the function
  107: 	&Apache::lonxml::default_homework_load()
  108:       </li>
  109:     </ul>
  110: 
  111:     <p>
  112:       In common usage, <i>$Apache::lonxml::prevent_entity_encode</i>,
  113:       <i>$Apache::lonxml::evaluate</i>,
  114:       <i>$Apache::lonxml::metamode</i>,
  115:       <i>$Apache::lonxml::import</i>, should never be set to a value
  116:       directly, but rather incremented when you want the effect on,
  117:       and decremented when you want the effect off.
  118:     </p>
  119:     
  120:     <h3>Notable Perl subroutines</h3>
  121:     <p>
  122:       If not specified these functions are in Apache::lonxml
  123:     </p>
  124:     <ul>
  125:       <li>
  126: 	<i>xmlparse</i> - see the XMLPARSE figure - also not callable
  127: 	from inside a tag, if one needs to restart parsing, either
  128: 	create add a new LCParser to the parser stack parser using the
  129: 	newparser function, or call inner_xmlparser, see the xmlparse
  130: 	function in scripttag.pm
  131:       </li>
  132:       <li>
  133: 	<i>recurse</i> - acts just like <i>xmlparse</i>, except it
  134: 	doesn't do the style definition check it always calls
  135: 	<i>callsub</i>
  136:       </li>
  137:       <li>
  138: 	<i>callsub</i> - callsub looks if a perl subroutine is defined
  139: 	for the current tag and calls. Otherwise it just returns the
  140: 	tag as it was read in. It also will throw on a default editing
  141: 	interface unless the tag has a defined subroutine that either
  142: 	returns something or requests that call sub not add the
  143: 	editing interface.
  144:       </li>
  145:       <li>
  146: 	<i>afterburn</i> - called on the output of xmlparse, it can
  147: 	add highlights, anchors, and links to regular expersion
  148: 	matches to the output.
  149:       </li>
  150:       <li>
  151: 	<i>register_insert</i> - builds the
  152: 	%Apache::lonxml::insertlist structure of what tags can have
  153: 	what other tags inside.
  154:       </li>
  155:       <li>
  156: 	<i>whichuser</i> - returns a list of $symb, $courseid,
  157: 	$domain, $name that is correct for calls to lonnet functions
  158: 	for this setup. Uses form.grade_ parameters, if the user is
  159: 	allowed to mgr in the course
  160:       </li>
  161:       <li>
  162: 	<i>setup_globals</i> - initializes all lonxml globals when
  163: 	xmlparse is called. If you intend to create a new target you
  164: 	will likely need to tweak how the globals are setup upon start
  165: 	up.
  166:       </li>
  167:       <li>
  168: 	<i>init_safespace</i> - creates Holes to external functions,
  169: 	creates some global variables, and set the permitted operators
  170: 	of the global Safespace intepreter.
  171:       </li>
  172:     </ul>
  173:     <h3>Functions Tag Handlers can use</h3>
  174:     <p>
  175:       If not specified these functions are in Apache::lonxml
  176:     </p>
  177:     <ul>
  178:       <li>
  179: 	<i>debug</i> - a function to call to printout debugging
  180: 	messages. Will only print when Apache::lonxml::debug is set to
  181: 	1
  182:       </li>
  183:       <li>
  184: 	<i>warning</i> - a function to use for warning messages. The message
  185: 	will appear at the top of a resource when it is viewed in
  186: 	construction space only.
  187:       </li>
  188:       <li>
  189: 	<i>error</i> - a function to use for error messages. The
  190: 	message will appear at the top of a resource when it is viewed
  191: 	in construction space, and will message the resource author
  192: 	and course instructor, while informing the student that an
  193: 	error has occured otherwise.
  194:       </li>
  195:       <li>
  196: 	<i>get_all_text</i> - 2 args, tag to look for (need to use
  197: 	/tag to look for an end tag) and a HTML::TokeParser reference,
  198: 	it will repedelyt get text from the TokeParser until the
  199: 	requested tag is found. It will return all of the document it
  200: 	pulled form the TokeParser. (See
  201: 	Apache::scripttag::start_script for an example of usage.)
  202:       </li>
  203:       <li>
  204: 	<i>get_param</i> - 4 arguments, first is a scaler sting of
  205: 	the argument needed, second is a reference to the parser
  206: 	arguments stack, third is a reference to the Safe space, and
  207: 	fourth is an optional "context" value. This subroutine allows
  208: 	a tag to get a tag argument, after being interpolated inside
  209: 	the Safe space. This should be used if the tag might use a
  210: 	safe space variable reference for the tag argument. (See
  211: 	Apache::scripttag::start_script for an example.)
  212: 	
  213: 	This version only handles scalar variables.
  214:       </li>
  215:       <li>
  216: 	<i>get_param_var</i> - 4 arguments, first is a scaler sting of
  217: 	the argument needed, second is a reference to the parser
  218: 	arguments stack, third is a reference to the Safe space, and
  219: 	fourth is an optional "context" value. This subroutine allows
  220: 	a tag to get a tag argument, after being interpolated inside
  221: 	the Safe space. This should be used if the tag might use a
  222: 	safe space variable reference for the tag argument. (See
  223: 	Apache::scripttag::start_script for an example.)
  224: 	
  225: 	This version can handle list or hash variables properly.
  226:       </li>
  227:       <li>
  228: 	<i>description</i> - 1 argument, the token object. This will
  229: 	return the textual decription of the current tag from the
  230: 	insertlist.tab file.
  231:       </li>
  232:       <li>
  233: 	<i>whichuser</i> - 0 arguments. This will take a look at the
  234: 	current environment setting and return the current $symb,
  235: 	$courseid, $udom, $uname. You should always use this function
  236: 	if you want to determine who the current user is. (Since a
  237: 	instructor might be trying to view a students version of a
  238: 	resource.)
  239:       </li>
  240:       <li>
  241: 	<i>inner_xmlparse</i> - 6 arguments, the target, an array
  242: 	pointer to the current stack of tags, and array pointer to the
  243: 	current stack of tag arguments, an array pointer to the
  244: 	current stack of LCParser's, a pointer to the current Safe
  245: 	space, a pointer to the hash of current style definitions
  246:       </li>
  247:       <li>
  248: 	<i>newparser</i> - 3 args, first is a reference to the parser
  249: 	stack, second should be a reference to a string scaler
  250: 	containg the text the newparser should run over, third should
  251: 	be a scaler of the directory path the file the parser is
  252: 	parsing was in. (See Apache::scripttag::start_import for an
  253: 	example.)
  254:       </li>
  255:       <li>
  256: 	<i>register</i> - should be called in a file's BEGIN block. 2
  257: 	arguments, a scaler string, and a list of strings. This allows
  258: 	a file to register what tags it handles, and what the
  259: 	namespace of those tags are. Example:
  260: <pre>
  261: sub BEGIN {
  262:   &Apache::lonxml::register('Apache::scripttag',('script','display'));
  263: }
  264: </pre>
  265: 	Would tell xmlparse that in Apache::scripttag it can find
  266: 	handlers for &lt;script&gt; and &lt;display&gt;, if one
  267: 	regsiters a tag that was already registered the previous one
  268: 	is remembered and will be restored on a deregister.
  269:       </li>
  270:       <li>
  271: 	<i>deregister</i> - used to remove a previously registered tag
  272: 	implementation. It will restore the previous registration if
  273: 	there was one.
  274:       </li>
  275:       <li>
  276: 	<i>startredirection</i> - used when a tag wants to save a
  277: 	portion of the document for its end tag to use, but wants the
  278: 	intervening document to be normally processed. (See
  279: 	Apache::scripttag::start_window for an example.)
  280:       </li>
  281:       <li>
  282: 	<i>endredirection</i> - used to stop preventing xmlparse from
  283: 	hiding output. The return value is everthing that xmlparse has
  284: 	processed since the corresponding startredirection. (See
  285: 	Apache::scripttag::end_window for an example.)
  286:       </li>
  287:       <li>
  288: 	<i>Apache::run::evaluate</i> - 3 args, first a string, second
  289: 	a reference to the Safe space, 3 a string to be evaluated
  290: 	before the first arg. This subroutine will do variable
  291: 	interpolation and simple function interpolations on the first
  292: 	argument. (See Apache::lonxml::inner_xmlparse for an example.)
  293:       </li>
  294:       <li>
  295: 	<i>Apache::run::run</i> - 2 args, first a string, second a
  296: 	reference to the Safe space. This handles passing the passed
  297: 	string into the Safe space for evaluation and then returns the
  298: 	result. (See Apache::scripttag::start_script for an example.)
  299:       </li>
  300:     </ul>
  301: 
  302:     <h2>Style Files</h2>
  303:     <h3>Style File specific tags</h3>
  304:     <ul>
  305:       <li>
  306: 	<b>&lt;definetag&gt;</b> - 2 arguments, <i>name</i> name of
  307: 	new tag being defined, if proceeded with a / defining an end
  308: 	tag, required; <i>parms</i> parameters of the new tag, the
  309: 	value of these parameters can be accesed by $parametername.
  310:       </li>
  311:       <li>
  312: 	<b>&lt;render&gt;</b> - define what the new tag does for a non meta target
  313:       </li>
  314:       <li>
  315: 	<b>&lt;meta&gt;</b> - define what the new tag does for a meta target
  316:       </li>
  317:       <li>
  318: 	<b>&lt;tex&gt; / &lt;web&gt; / &lt;latexsource&gt;</b> -
  319: 	define what a new tag does for a specific no meta target, all
  320: 	data inside a &lt;render&gt; is render to all targets except
  321: 	when surrounded by a specific target tags.
  322:       </li>
  323:     </ul>
  324:     <hr>
  325:     <address><a href="mailto:albertel@marvin.lite.msu.edu">Guy Albertelli</a></address>
  326: <!-- Created: Sun May 20 15:47:08 EDT 2001 -->
  327: <!-- hhmts start -->
  328: Last modified: Mon Oct 21 16:41:56 EDT 2002
  329: <!-- hhmts end -->
  330:   </body>
  331: </html>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>