doc/homework/xml.html - view

File: [LON-CAPA] / doc / homework / xml.html
Revision 1.3: download - view: text, annotated - select for diffs
Fri May 3 18:34:20 2002 UTC (22 years ago) by albertel
Branches: MAIN
CVS tags: HEAD

- updated some documenations, and added some documentation of the form parameters used by the homework engine

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