doc/homework/xml.html - view

File: [LON-CAPA] / doc / homework / xml.html
Revision 1.4: download - view: text, annotated - select for diffs
Thu May 23 21:17:19 2002 UTC (21 years, 10 months ago) by albertel
Branches: MAIN
CVS tags: HEAD

- added new global 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> 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. <h3>Global Variables</h3> <ul> <li> $Apache::lonxml::debug - debugging control </li> <li> @Apache::lonxml::pwd - path to the directory containing the file currently being processed </li> <li> @Apache::lonxml::outputstack $Apache::lonxml::redirection - 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> $Apache::lonxml::import - controls whether the <import> tag actually does anything </li> <li> @Apache::lonxml::extlinks - a list of URLs that the user is allowed to look at because of the current resource (images, and links) </li> <li> #Apache::lonxml::metamode - some output is turned off, the meta target wants a specific subset, use <output> to guarentee that the catianed data will be in the parsing output </li> <li> #Apache::lonxml::evaluate - controls whether run::evaluate actually derefences variable references </li> <li> %Apache::lonxml::insertlist - data structure for edit mode, determines what tags can go into what other tags </li> <li> @Apache::lonxml::namespace - stores the list of tag namespaces used in the insertlist.tab file that are currently active, used only in edit mode. </li> <li> $Apache::lonxml::registered - set to 1 once the remote has been updated to know what resource we are looking at. </li> <li> $Apache::lonxml::request - current Apache request object, or undef </li> </ul> <h3>Notable Perl subroutines</h3> If not specified these functions are in Apache::lonxml <ul> <li> xmlparse - see the XMLPARSE figure </li> <li> recurse - acts just like xmlparse, except it doesn't do the style definition check it always calls callsub </li> <li> callsub - 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> afterburn - called on the output of xmlparse, it can add highlights, anchors, and links to regular expersion matches to the output. </li> <li> register_insert - builds the %Apache::lonxml::insertlist structure of what tags can have what other tags inside. </li> <li> whichuser - 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> </ul> <h3>Functions Tag Handlers can use</h3> If not specified these functions are in Apache::lonxml <ul> <li> debug - a function to call to printout debugging messages. Will only print when Apache::lonxml::debug is set to 1 </li> <li> warning - 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> error - 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> get_all_text - 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> get_param - 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> newparser - 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> register - 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 <script> and <display> </li> <li> startredirection - 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> endredirection - 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> Apache::run::evaluate - 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> Apache::run::run - 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> <definetag> - 2 arguments, name name of new tag being defined, if proceeded with a / defining an end tag, required; parms parameters of the new tag, the value of these parameters can be accesed by $parametername. </li> <li> <render> - define what the new tag does for a non meta target </li> <li> <meta> - define what the new tag does for a meta target </li> <li> <tex> / <web> / <latexsource> - define what a new tag does for a specific no meta target, all data inside a <render> 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>   Last modified: Thu May 23 17:19:29 EDT 2002  </body> </html>