doc/homework/xml.html - view

File: [LON-CAPA] / doc / homework / xml.html
Revision 1.2: download - view: text, annotated - select for diffs
Mon May 21 15:24:47 2001 UTC (22 years, 11 months ago) by albertel
Branches: MAIN
CVS tags: stable_2002_spring, stable_2002_april, stable_2001_fall, HEAD

- new files
- deleted extra diamond

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