doc/homework/xml.html - view

File: [LON-CAPA] / doc / homework / xml.html
Revision 1.6: download - view: text, annotated - select for diffs
Mon Oct 21 17:10:35 2002 UTC (21 years, 6 months ago) by albertel
Branches: MAIN
CVS tags: HEAD

- documenting the increase in lonxml's globals

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 27: the file currently being processed 28: </li> 29: <li> 30: @Apache::lonxml::outputstack 31: $Apache::lonxml::redirection - these two are used for 32: capturing a subset of the output for later processing, don't 33: touch them directly use &startredirection and &endredirection 34: </li> 35: <li> 36: $Apache::lonxml::import - controls whether the 37: <import> tag actually does anything 38: </li> 39: <li> 40: @Apache::lonxml::extlinks - a list of URLs that the 41: user is allowed to look at because of the current resource 42: (images, and links) 43: </li> 44: <li> 45: $Apache::lonxml::metamode - some output is turned off, 46: the meta target wants a specific subset, use <output> to 47: guarentee that the catianed data will be in the parsing output 48: </li> 49: <li> 50: $Apache::lonxml::evaluate - controls whether 51: run::evaluate actually derefences variable references 52: </li> 53: <li> 54: %Apache::lonxml::insertlist - data structure for edit 55: mode, determines what tags can go into what other tags 56: </li> 57: <li> 58: @Apache::lonxml::namespace - stores the list of tag 59: namespaces used in the insertlist.tab file that are currently 60: active, used only in edit mode. 61: </li> 62: <li> 63: $Apache::lonxml::registered - set to 1 once the remote 64: has been updated to know what resource we are looking at. 65: </li> 66: <li> 67: $Apache::lonxml::request - current Apache request 68: object, or undef 69: </li> 70: <li> 71: $Apache::lonxml::curdepth - current depth of the 72: overall parse depth. Will be a string like: 2_3_1 (first tag 73: in the third second level tag in the second toplevel tag). It 74: gets set by callsub, and can be used in Perl tag 75: implementations. It relies upon the internal globals: 76: @Apache::lonxml::depthcounter, 77: $Apache::lonxml::depth, 78: $Apache::lonxml::olddepth 79: </li> 80: <li> 81: $Apache::lonxml::prevent_entity_encode - By default the 82: xmlparser will try to rencode any 8-bit characters into HTML 83: Entity Codes, If this is set to a true value it will be 84: prevented. 85: </li> 86: <li> 87: $Apache::lonxml::errorcount - keeps count of the number 88: of errors generated in a parse 89: </li> 90: <li> 91: $Apache::lonxml::warningcount - keeps count of the 92: number of errors generated in a parse 93: </li> 94: <li> 95: $Apache::lonxml::counter 96: $Apache::lonxml::counter_changed - a counter used to 97: keep track of the number of questions asked, used currently to 98: track bubble numbers, Initialized off of $ENV{'form.counter'}, 99: and writes this value to the environment if counter_changed is 100: true, should use the &increment_counter() function to 101: increment this value. 102: </li> 103: </ul> 104: 105: 106: In common usage, $Apache::lonxml::prevent_entity_encode, 107: $Apache::lonxml::evaluate, 108: $Apache::lonxml::metamode, 109: $Apache::lonxml::import, should never be set to a value 110: directly, but rather incremented when you want the effect on, 111: and decremented when you want the effect off. 112: 113: 114: <h3>Notable Perl subroutines</h3> 115: 116: If not specified these functions are in Apache::lonxml 117: 118: <ul> 119: <li> 120: xmlparse - see the XMLPARSE figure - also not callable 121: from inside a tag, if one needs to restart parsing, either 122: create add a new LCParser to the parser stack parser using the 123: newparser function, or call inner_xmlparser, see the xmlparse 124: function in scripttag.pm 125: </li> 126: <li> 127: recurse - acts just like xmlparse, except it 128: doesn't do the style definition check it always calls 129: callsub 130: </li> 131: <li> 132: callsub - callsub looks if a perl subroutine is defined 133: for the current tag and calls. Otherwise it just returns the 134: tag as it was read in. It also will throw on a default editing 135: interface unless the tag has a defined subroutine that either 136: returns something or requests that call sub not add the 137: editing interface. 138: </li> 139: <li> 140: afterburn - called on the output of xmlparse, it can 141: add highlights, anchors, and links to regular expersion 142: matches to the output. 143: </li> 144: <li> 145: register_insert - builds the 146: %Apache::lonxml::insertlist structure of what tags can have 147: what other tags inside. 148: </li> 149: <li> 150: whichuser - returns a list of $symb, $courseid, 151: $domain, $name that is correct for calls to lonnet functions 152: for this setup. Uses form.grade_ parameters, if the user is 153: allowed to mgr in the course 154: </li> 155: <li> 156: setup_globals - initializes all lonxml globals when 157: xmlparse is called. If you intend to create a new target you 158: will likely need to tweak how the globals are setup upon start 159: up. 160: </li> 161: <li> 162: init_safespace - creates Holes to external functions, 163: creates some global variables, and set the permitted operators 164: of the global Safespace intepreter. 165: </li> 166: </ul> 167: <h3>Functions Tag Handlers can use</h3> 168: 169: If not specified these functions are in Apache::lonxml 170: 171: <ul> 172: <li> 173: debug - a function to call to printout debugging 174: messages. Will only print when Apache::lonxml::debug is set to 175: 1 176: </li> 177: <li> 178: warning - a function to use for warning messages. The message 179: will appear at the top of a resource when it is viewed in 180: construction space only. 181: </li> 182: <li> 183: error - a function to use for error messages. The 184: message will appear at the top of a resource when it is viewed 185: in construction space, and will message the resource author 186: and course instructor, while informing the student that an 187: error has occured otherwise. 188: </li> 189: <li> 190: get_all_text - 2 args, tag to look for (need to use 191: /tag to look for an end tag) and a HTML::TokeParser reference, 192: it will repedelyt get text from the TokeParser until the 193: requested tag is found. It will return all of the document it 194: pulled form the TokeParser. (See 195: Apache::scripttag::start_script for an example of usage.) 196: </li> 197: <li> 198: get_param - 4 arguments, first is a scaler sting of 199: the argument needed, second is a reference to the parser 200: arguments stack, third is a reference to the Safe space, and 201: fourth is an optional "context" value. This subroutine allows 202: a tag to get a tag argument, after being interpolated inside 203: the Safe space. This should be used if the tag might use a 204: safe space variable reference for the tag argument. (See 205: Apache::scripttag::start_script for an example.) 206: 207: This version only handles scalar variables. 208: </li> 209: <li> 210: get_param_var - 4 arguments, first is a scaler sting of 211: the argument needed, second is a reference to the parser 212: arguments stack, third is a reference to the Safe space, and 213: fourth is an optional "context" value. This subroutine allows 214: a tag to get a tag argument, after being interpolated inside 215: the Safe space. This should be used if the tag might use a 216: safe space variable reference for the tag argument. (See 217: Apache::scripttag::start_script for an example.) 218: 219: This version can handle list or hash variables properly. 220: </li> 221: <li> 222: description - 1 argument, the token object. This will 223: return the textual decription of the current tag from the 224: insertlist.tab file. 225: </li> 226: <li> 227: whichuser - 0 arguments. This will take a look at the 228: current environment setting and return the current $symb, 229: $courseid, $udom, $uname. You should always use this function 230: if you want to determine who the current user is. (Since a 231: instructor might be trying to view a students version of a 232: resource.) 233: </li> 234: <li> 235: inner_xmlparse - 6 arguments, the target, an array 236: pointer to the current stack of tags, and array pointer to the 237: current stack of tag arguments, an array pointer to the 238: current stack of LCParser's, a pointer to the current Safe 239: space, a pointer to the hash of current style definitions 240: </li> 241: <li> 242: newparser - 3 args, first is a reference to the parser 243: stack, second should be a reference to a string scaler 244: containg the text the newparser should run over, third should 245: be a scaler of the directory path the file the parser is 246: parsing was in. (See Apache::scripttag::start_import for an 247: example.) 248: </li> 249: <li> 250: register - should be called in a file's BEGIN block. 2 251: arguments, a scaler string, and a list of strings. This allows 252: a file to register what tags it handles, and what the 253: namespace of those tags are. Example: 254: <pre> 255: sub BEGIN { 256: &Apache::lonxml::register('Apache::scripttag',('script','display')); 257: } 258: </pre> 259: Would tell xmlparse that in Apache::scripttag it can find 260: handlers for <script> and <display>, if one 261: regsiters a tag that was already registered the previous one 262: is remembered and will be restored on a deregister. 263: </li> 264: <li> 265: deregister - used to remove a previously registered tag 266: implementation. It will restore the previous registration if 267: there was one. 268: </li> 269: <li> 270: startredirection - used when a tag wants to save a 271: portion of the document for its end tag to use, but wants the 272: intervening document to be normally processed. (See 273: Apache::scripttag::start_window for an example.) 274: </li> 275: <li> 276: endredirection - used to stop preventing xmlparse from 277: hiding output. The return value is everthing that xmlparse has 278: processed since the corresponding startredirection. (See 279: Apache::scripttag::end_window for an example.) 280: </li> 281: <li> 282: Apache::run::evaluate - 3 args, first a string, second 283: a reference to the Safe space, 3 a string to be evaluated 284: before the first arg. This subroutine will do variable 285: interpolation and simple function interpolations on the first 286: argument. (See Apache::lonxml::inner_xmlparse for an example.) 287: </li> 288: <li> 289: Apache::run::run - 2 args, first a string, second a 290: reference to the Safe space. This handles passing the passed 291: string into the Safe space for evaluation and then returns the 292: result. (See Apache::scripttag::start_script for an example.) 293: </li> 294: </ul> 295: 296: <h2>Style Files</h2> 297: <h3>Style File specific tags</h3> 298: <ul> 299: <li> 300: <definetag> - 2 arguments, name name of 301: new tag being defined, if proceeded with a / defining an end 302: tag, required; parms parameters of the new tag, the 303: value of these parameters can be accesed by $parametername. 304: </li> 305: <li> 306: <render> - define what the new tag does for a non meta target 307: </li> 308: <li> 309: <meta> - define what the new tag does for a meta target 310: </li> 311: <li> 312: <tex> / <web> / <latexsource> - 313: define what a new tag does for a specific no meta target, all 314: data inside a <render> is render to all targets except 315: when surrounded by a specific target tags. 316: </li> 317: </ul> 318: <hr> 319: <address><a href="mailto:albertel@marvin.lite.msu.edu">Guy Albertelli</a></address> 320:  321:  322: Last modified: Mon Oct 21 13:23:28 EDT 2002 323:  324: </body> 325: </html>