doc/homework/xml.html - view

File: [LON-CAPA] / doc / homework / xml.html
Revision 1.5: download - view: text, annotated - select for diffs
Thu Jun 6 07:14:18 2002 UTC (21 years, 11 months ago) by albertel
Branches: MAIN
CVS tags: version_0_5_1, version_0_5, version_0_4, stable_2002_july, STABLE, HEAD

-updated global lists, and the helper function lists

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: </ul> 86: 87: 88: In common usage, $Apache::lonxml::prevent_entity_encode, 89: $Apache::lonxml::evaluate, 90: $Apache::lonxml::metamode, 91: $Apache::lonxml::import, should never be set to a value 92: directly, but rather incremented when you want the effect on, 93: and decremented when you want the effect off. 94: 95: 96: <h3>Notable Perl subroutines</h3> 97: 98: If not specified these functions are in Apache::lonxml 99: 100: <ul> 101: <li> 102: xmlparse - see the XMLPARSE figure - also not callable 103: from inside a tag, if one needs to restart parsing, either 104: create add a new LCParser to the parser stack parser using the 105: newparser function, or call inner_xmlparser, see the xmlparse 106: function in scripttag.pm 107: </li> 108: <li> 109: recurse - acts just like xmlparse, except it 110: doesn't do the style definition check it always calls 111: callsub 112: </li> 113: <li> 114: callsub - callsub looks if a perl subroutine is defined 115: for the current tag and calls. Otherwise it just returns the 116: tag as it was read in. It also will throw on a default editing 117: interface unless the tag has a defined subroutine that either 118: returns something or requests that call sub not add the 119: editing interface. 120: </li> 121: <li> 122: afterburn - called on the output of xmlparse, it can 123: add highlights, anchors, and links to regular expersion 124: matches to the output. 125: </li> 126: <li> 127: register_insert - builds the 128: %Apache::lonxml::insertlist structure of what tags can have 129: what other tags inside. 130: </li> 131: <li> 132: whichuser - returns a list of $symb, $courseid, 133: $domain, $name that is correct for calls to lonnet functions 134: for this setup. Uses form.grade_ parameters, if the user is 135: allowed to mgr in the course 136: </li> 137: <li> 138: setup_globals - initializes all lonxml globals when 139: xmlparse is called. If you intend to create a new target you 140: will likely need to tweak how the globals are setup upon start 141: up. 142: </li> 143: <li> 144: init_safespace - creates Holes to external functions, 145: creates some global variables, and set the permitted operators 146: of the global Safespace intepreter. 147: </li> 148: </ul> 149: <h3>Functions Tag Handlers can use</h3> 150: 151: If not specified these functions are in Apache::lonxml 152: 153: <ul> 154: <li> 155: debug - a function to call to printout debugging 156: messages. Will only print when Apache::lonxml::debug is set to 157: 1 158: </li> 159: <li> 160: warning - a function to use for warning messages. The message 161: will appear at the top of a resource when it is viewed in 162: construction space only. 163: </li> 164: <li> 165: error - a function to use for error messages. The 166: message will appear at the top of a resource when it is viewed 167: in construction space, and will message the resource author 168: and course instructor, while informing the student that an 169: error has occured otherwise. 170: </li> 171: <li> 172: get_all_text - 2 args, tag to look for (need to use 173: /tag to look for an end tag) and a HTML::TokeParser reference, 174: it will repedelyt get text from the TokeParser until the 175: requested tag is found. It will return all of the document it 176: pulled form the TokeParser. (See 177: Apache::scripttag::start_script for an example of usage.) 178: </li> 179: <li> 180: get_param - 4 arguments, first is a scaler sting of 181: the argument needed, second is a reference to the parser 182: arguments stack, third is a reference to the Safe space, and 183: fourth is an optional "context" value. This subroutine allows 184: a tag to get a tag argument, after being interpolated inside 185: the Safe space. This should be used if the tag might use a 186: safe space variable reference for the tag argument. (See 187: Apache::scripttag::start_script for an example.) 188: 189: This version only handles scalar variables. 190: </li> 191: <li> 192: get_param_var - 4 arguments, first is a scaler sting of 193: the argument needed, second is a reference to the parser 194: arguments stack, third is a reference to the Safe space, and 195: fourth is an optional "context" value. This subroutine allows 196: a tag to get a tag argument, after being interpolated inside 197: the Safe space. This should be used if the tag might use a 198: safe space variable reference for the tag argument. (See 199: Apache::scripttag::start_script for an example.) 200: 201: This version can handle list or hash variables properly. 202: </li> 203: <li> 204: description - 1 argument, the token object. This will 205: return the textual decription of the current tag from the 206: insertlist.tab file. 207: </li> 208: <li> 209: whichuser - 0 arguments. This will take a look at the 210: current environment setting and return the current $symb, 211: $courseid, $udom, $uname. You should always use this function 212: if you want to determine who the current user is. (Since a 213: instructor might be trying to view a students version of a 214: resource.) 215: </li> 216: <li> 217: inner_xmlparse - 6 arguments, the target, an array 218: pointer to the current stack of tags, and array pointer to the 219: current stack of tag arguments, an array pointer to the 220: current stack of LCParser's, a pointer to the current Safe 221: space, a pointer to the hash of current style definitions 222: </li> 223: <li> 224: newparser - 3 args, first is a reference to the parser 225: stack, second should be a reference to a string scaler 226: containg the text the newparser should run over, third should 227: be a scaler of the directory path the file the parser is 228: parsing was in. (See Apache::scripttag::start_import for an 229: example.) 230: </li> 231: <li> 232: register - should be called in a file's BEGIN block. 2 233: arguments, a scaler string, and a list of strings. This allows 234: a file to register what tags it handles, and what the 235: namespace of those tags are. Example: 236: <pre> 237: sub BEGIN { 238: &Apache::lonxml::register('Apache::scripttag',('script','display')); 239: } 240: </pre> 241: Would tell xmlparse that in Apache::scripttag it can find 242: handlers for <script> and <display>, if one 243: regsiters a tag that was already registered the previous one 244: is remembered and will be restored on a deregister. 245: </li> 246: <li> 247: deregister - used to remove a previously registered tag 248: implementation. It will restore the previous registration if 249: there was one. 250: </li> 251: <li> 252: startredirection - used when a tag wants to save a 253: portion of the document for its end tag to use, but wants the 254: intervening document to be normally processed. (See 255: Apache::scripttag::start_window for an example.) 256: </li> 257: <li> 258: endredirection - used to stop preventing xmlparse from 259: hiding output. The return value is everthing that xmlparse has 260: processed since the corresponding startredirection. (See 261: Apache::scripttag::end_window for an example.) 262: </li> 263: <li> 264: Apache::run::evaluate - 3 args, first a string, second 265: a reference to the Safe space, 3 a string to be evaluated 266: before the first arg. This subroutine will do variable 267: interpolation and simple function interpolations on the first 268: argument. (See Apache::lonxml::inner_xmlparse for an example.) 269: </li> 270: <li> 271: Apache::run::run - 2 args, first a string, second a 272: reference to the Safe space. This handles passing the passed 273: string into the Safe space for evaluation and then returns the 274: result. (See Apache::scripttag::start_script for an example.) 275: </li> 276: </ul> 277: 278: <h2>Style Files</h2> 279: <h3>Style File specific tags</h3> 280: <ul> 281: <li> 282: <definetag> - 2 arguments, name name of 283: new tag being defined, if proceeded with a / defining an end 284: tag, required; parms parameters of the new tag, the 285: value of these parameters can be accesed by $parametername. 286: </li> 287: <li> 288: <render> - define what the new tag does for a non meta target 289: </li> 290: <li> 291: <meta> - define what the new tag does for a meta target 292: </li> 293: <li> 294: <tex> / <web> / <latexsource> - 295: define what a new tag does for a specific no meta target, all 296: data inside a <render> is render to all targets except 297: when surrounded by a specific target tags. 298: </li> 299: </ul> 300: <hr> 301: <address><a href="mailto:albertel@marvin.lite.msu.edu">Guy Albertelli</a></address> 302:  303:  304: Last modified: Thu Jun 6 01:16:44 EDT 2002 305:  306: </body> 307: </html>