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