doc/homework/xml.html - view

File: [LON-CAPA] / doc / homework / xml.html
Revision 1.1: download - view: text, annotated - select for diffs
Mon May 21 03:35:46 2001 UTC (22 years, 11 months ago) by albertel
Branches: MAIN
CVS tags: HEAD

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