Annotation of doc/homework/xml.html, revision 1.5
1.1 albertel 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>
1.2 albertel 23: <i>$Apache::lonxml::debug</i> - debugging control
1.1 albertel 24: </li>
25: <li>
1.5 ! albertel 26: <i>@Apache::lonxml::pwd</i> - path to the directory containing
! 27: the file currently being processed
1.1 albertel 28: </li>
29: <li>
1.2 albertel 30: <i>@Apache::lonxml::outputstack</i> <br />
31: <i>$Apache::lonxml::redirection</i> - 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
1.1 albertel 34: </li>
35: <li>
1.2 albertel 36: <i>$Apache::lonxml::import</i> - controls whether the
37: <import> tag actually does anything
1.1 albertel 38: </li>
39: <li>
1.3 albertel 40: <i>@Apache::lonxml::extlinks</i> - a list of URLs that the
41: user is allowed to look at because of the current resource
42: (images, and links)
1.1 albertel 43: </li>
44: <li>
1.5 ! albertel 45: <i>$Apache::lonxml::metamode</i> - some output is turned off,
1.2 albertel 46: the meta target wants a specific subset, use <output> to
47: guarentee that the catianed data will be in the parsing output
1.1 albertel 48: </li>
49: <li>
1.5 ! albertel 50: <i>$Apache::lonxml::evaluate</i> - controls whether
1.2 albertel 51: run::evaluate actually derefences variable references
1.1 albertel 52: </li>
53: <li>
1.2 albertel 54: <i>%Apache::lonxml::insertlist</i> - data structure for edit
55: mode, determines what tags can go into what other tags
1.1 albertel 56: </li>
57: <li>
1.2 albertel 58: <i>@Apache::lonxml::namespace</i> - stores the list of tag
59: namespaces used in the insertlist.tab file that are currently
60: active, used only in edit mode.
1.1 albertel 61: </li>
1.3 albertel 62: <li>
63: <i>$Apache::lonxml::registered</i> - set to 1 once the remote
64: has been updated to know what resource we are looking at.
65: </li>
1.4 albertel 66: <li>
67: <i>$Apache::lonxml::request</i> - current Apache request
68: object, or undef
69: </li>
1.5 ! albertel 70: <li>
! 71: <i>$Apache::lonxml::curdepth</i> - 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: <i>@Apache::lonxml::depthcounter</i>,
! 77: <i>$Apache::lonxml::depth</i>,
! 78: <i>$Apache::lonxml::olddepth</i>
! 79: </li>
! 80: <li>
! 81: <i>$Apache::lonxml::prevent_entity_encode</i> - 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.
1.1 albertel 85: </ul>
1.5 ! albertel 86:
! 87: <p>
! 88: In common usage, <i>$Apache::lonxml::prevent_entity_encode</i>,
! 89: <i>$Apache::lonxml::evaluate</i>,
! 90: <i>$Apache::lonxml::metamode</i>,
! 91: <i>$Apache::lonxml::import</i>, 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: </p>
! 95:
1.1 albertel 96: <h3>Notable Perl subroutines</h3>
97: <p>
98: If not specified these functions are in Apache::lonxml
99: </p>
100: <ul>
101: <li>
1.5 ! albertel 102: <i>xmlparse</i> - 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
1.1 albertel 107: </li>
108: <li>
109: <i>recurse</i> - acts just like <i>xmlparse</i>, except it
110: doesn't do the style definition check it always calls
111: <i>callsub</i>
112: </li>
113: <li>
114: <i>callsub</i> - 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: <i>afterburn</i> - 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: <i>register_insert</i> - builds the
128: %Apache::lonxml::insertlist structure of what tags can have
129: what other tags inside.
130: </li>
1.3 albertel 131: <li>
132: <i>whichuser</i> - 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>
1.5 ! albertel 137: <li>
! 138: <i>setup_globals</i> - 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: <i>init_safespace</i> - creates Holes to external functions,
! 145: creates some global variables, and set the permitted operators
! 146: of the global Safespace intepreter.
! 147: </li>
1.1 albertel 148: </ul>
149: <h3>Functions Tag Handlers can use</h3>
150: <p>
151: If not specified these functions are in Apache::lonxml
152: </p>
153: <ul>
154: <li>
155: <i>debug</i> - 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: <i>warning</i> - 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: <i>error</i> - 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: <i>get_all_text</i> - 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>
1.5 ! albertel 180: <i>get_param</i> - 4 arguments, first is a scaler sting of
1.1 albertel 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
1.5 ! albertel 187: Apache::scripttag::start_script for an example.)
! 188:
! 189: This version only handles scalar variables.
! 190: </li>
! 191: <li>
! 192: <i>get_param_var</i> - 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: <i>description</i> - 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: <i>whichuser</i> - 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: <i>inner_xmlparse</i> - 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
1.1 albertel 222: </li>
223: <li>
224: <i>newparser</i> - 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: <i>register</i> - 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
1.5 ! albertel 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: <i>deregister</i> - used to remove a previously registered tag
! 248: implementation. It will restore the previous registration if
! 249: there was one.
1.1 albertel 250: </li>
251: <li>
252: <i>startredirection</i> - 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: <i>endredirection</i> - 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: <i>Apache::run::evaluate</i> - 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
1.5 ! albertel 268: argument. (See Apache::lonxml::inner_xmlparse for an example.)
1.1 albertel 269: </li>
270: <li>
271: <i>Apache::run::run</i> - 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>
1.2 albertel 282: <b><definetag></b> - 2 arguments, <i>name</i> name of
283: new tag being defined, if proceeded with a / defining an end
284: tag, required; <i>parms</i> parameters of the new tag, the
285: value of these parameters can be accesed by $parametername.
1.1 albertel 286: </li>
287: <li>
1.2 albertel 288: <b><render></b> - define what the new tag does for a non meta target
1.1 albertel 289: </li>
290: <li>
1.2 albertel 291: <b><meta></b> - define what the new tag does for a meta target
1.1 albertel 292: </li>
293: <li>
1.2 albertel 294: <b><tex> / <web> / <latexsource></b> -
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.
1.1 albertel 298: </li>
299: </ul>
300: <hr>
301: <address><a href="mailto:albertel@marvin.lite.msu.edu">Guy Albertelli</a></address>
302: <!-- Created: Sun May 20 15:47:08 EDT 2001 -->
303: <!-- hhmts start -->
1.5 ! albertel 304: Last modified: Thu Jun 6 01:16:44 EDT 2002
1.1 albertel 305: <!-- hhmts end -->
306: </body>
307: </html>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to xml.html CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [LON-CAPA] / doc / homework