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, 11 months ago) by albertel
Branches: MAIN
CVS tags: HEAD

- added new global documentation

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: <li> 66: $Apache::lonxml::request - current Apache request 67: object, or undef 68: </li> 69: </ul> 70: 71: <h3>Notable Perl subroutines</h3> 72: 73: If not specified these functions are in Apache::lonxml 74: 75: <ul> 76: <li> 77: xmlparse - see the XMLPARSE figure 78: </li> 79: <li> 80: recurse - acts just like xmlparse, except it 81: doesn't do the style definition check it always calls 82: callsub 83: </li> 84: <li> 85: callsub - 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: afterburn - 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: register_insert - builds the 99: %Apache::lonxml::insertlist structure of what tags can have 100: what other tags inside. 101: </li> 102: <li> 103: whichuser - 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> 108: </ul> 109: <h3>Functions Tag Handlers can use</h3> 110: 111: If not specified these functions are in Apache::lonxml 112: 113: <ul> 114: <li> 115: debug - 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: warning - 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: error - 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: get_all_text - 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: get_param - 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: newparser - 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: register - 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 <script> and <display> 169: </li> 170: <li> 171: startredirection - 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: endredirection - 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: Apache::run::evaluate - 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: Apache::run::run - 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> 201: <definetag> - 2 arguments, name name of 202: new tag being defined, if proceeded with a / defining an end 203: tag, required; parms parameters of the new tag, the 204: value of these parameters can be accesed by $parametername. 205: </li> 206: <li> 207: <render> - define what the new tag does for a non meta target 208: </li> 209: <li> 210: <meta> - define what the new tag does for a meta target 211: </li> 212: <li> 213: <tex> / <web> / <latexsource> - 214: define what a new tag does for a specific no meta target, all 215: data inside a <render> is render to all targets except 216: when surrounded by a specific target tags. 217: </li> 218: </ul> 219: <hr> 220: <address><a href="mailto:albertel@marvin.lite.msu.edu">Guy Albertelli</a></address> 221:  222:  223: Last modified: Thu May 23 17:19:29 EDT 2002 224:  225: </body> 226: </html>