Annotation of doc/homework/xml.html, revision 1.6
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.6 ! albertel 85: </li>
! 86: <li>
! 87: <i>$Apache::lonxml::errorcount</i> - keeps count of the number
! 88: of errors generated in a parse
! 89: </li>
! 90: <li>
! 91: <i>$Apache::lonxml::warningcount</i> - keeps count of the
! 92: number of errors generated in a parse
! 93: </li>
! 94: <li>
! 95: <i>$Apache::lonxml::counter</i> <br />
! 96: <i>$Apache::lonxml::counter_changed</i> - 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>
1.1 albertel 103: </ul>
1.5 albertel 104:
105: <p>
106: In common usage, <i>$Apache::lonxml::prevent_entity_encode</i>,
107: <i>$Apache::lonxml::evaluate</i>,
108: <i>$Apache::lonxml::metamode</i>,
109: <i>$Apache::lonxml::import</i>, 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: </p>
113:
1.1 albertel 114: <h3>Notable Perl subroutines</h3>
115: <p>
116: If not specified these functions are in Apache::lonxml
117: </p>
118: <ul>
119: <li>
1.5 albertel 120: <i>xmlparse</i> - 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
1.1 albertel 125: </li>
126: <li>
127: <i>recurse</i> - acts just like <i>xmlparse</i>, except it
128: doesn't do the style definition check it always calls
129: <i>callsub</i>
130: </li>
131: <li>
132: <i>callsub</i> - 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: <i>afterburn</i> - 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: <i>register_insert</i> - builds the
146: %Apache::lonxml::insertlist structure of what tags can have
147: what other tags inside.
148: </li>
1.3 albertel 149: <li>
150: <i>whichuser</i> - 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>
1.5 albertel 155: <li>
156: <i>setup_globals</i> - 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: <i>init_safespace</i> - creates Holes to external functions,
163: creates some global variables, and set the permitted operators
164: of the global Safespace intepreter.
165: </li>
1.1 albertel 166: </ul>
167: <h3>Functions Tag Handlers can use</h3>
168: <p>
169: If not specified these functions are in Apache::lonxml
170: </p>
171: <ul>
172: <li>
173: <i>debug</i> - 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: <i>warning</i> - 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: <i>error</i> - 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: <i>get_all_text</i> - 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>
1.5 albertel 198: <i>get_param</i> - 4 arguments, first is a scaler sting of
1.1 albertel 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
1.5 albertel 205: Apache::scripttag::start_script for an example.)
206:
207: This version only handles scalar variables.
208: </li>
209: <li>
210: <i>get_param_var</i> - 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: <i>description</i> - 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: <i>whichuser</i> - 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: <i>inner_xmlparse</i> - 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
1.1 albertel 240: </li>
241: <li>
242: <i>newparser</i> - 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: <i>register</i> - 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
1.5 albertel 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: <i>deregister</i> - used to remove a previously registered tag
266: implementation. It will restore the previous registration if
267: there was one.
1.1 albertel 268: </li>
269: <li>
270: <i>startredirection</i> - 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: <i>endredirection</i> - 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: <i>Apache::run::evaluate</i> - 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
1.5 albertel 286: argument. (See Apache::lonxml::inner_xmlparse for an example.)
1.1 albertel 287: </li>
288: <li>
289: <i>Apache::run::run</i> - 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>
1.2 albertel 300: <b><definetag></b> - 2 arguments, <i>name</i> name of
301: new tag being defined, if proceeded with a / defining an end
302: tag, required; <i>parms</i> parameters of the new tag, the
303: value of these parameters can be accesed by $parametername.
1.1 albertel 304: </li>
305: <li>
1.2 albertel 306: <b><render></b> - define what the new tag does for a non meta target
1.1 albertel 307: </li>
308: <li>
1.2 albertel 309: <b><meta></b> - define what the new tag does for a meta target
1.1 albertel 310: </li>
311: <li>
1.2 albertel 312: <b><tex> / <web> / <latexsource></b> -
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.
1.1 albertel 316: </li>
317: </ul>
318: <hr>
319: <address><a href="mailto:albertel@marvin.lite.msu.edu">Guy Albertelli</a></address>
320: <!-- Created: Sun May 20 15:47:08 EDT 2001 -->
321: <!-- hhmts start -->
1.6 ! albertel 322: Last modified: Mon Oct 21 13:23:28 EDT 2002
1.1 albertel 323: <!-- hhmts end -->
324: </body>
325: </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