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>
23: <i>$Apache::lonxml::debug</i> - debugging control
24: </li>
25: <li>
26: <i>@Apache::lonxml::pwd</i> - path to the directory containing
27: the file currently being processed
28: </li>
29: <li>
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
34: </li>
35: <li>
36: <i>$Apache::lonxml::import</i> - controls whether the
37: <import> tag actually does anything
38: </li>
39: <li>
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)
43: </li>
44: <li>
45: <i>$Apache::lonxml::metamode</i> - 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: <i>$Apache::lonxml::evaluate</i> - controls whether
51: run::evaluate actually derefences variable references
52: </li>
53: <li>
54: <i>%Apache::lonxml::insertlist</i> - data structure for edit
55: mode, determines what tags can go into what other tags
56: </li>
57: <li>
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.
61: </li>
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>
66: <li>
67: <i>$Apache::lonxml::request</i> - current Apache request
68: object, or undef
69: </li>
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.
85: </ul>
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:
96: <h3>Notable Perl subroutines</h3>
97: <p>
98: If not specified these functions are in Apache::lonxml
99: </p>
100: <ul>
101: <li>
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
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>
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>
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>
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>
180: <i>get_param</i> - 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: <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
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
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.
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
268: argument. (See Apache::lonxml::inner_xmlparse for an example.)
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>
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.
286: </li>
287: <li>
288: <b><render></b> - define what the new tag does for a non meta target
289: </li>
290: <li>
291: <b><meta></b> - define what the new tag does for a meta target
292: </li>
293: <li>
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.
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 -->
304: Last modified: Thu Jun 6 01:16:44 EDT 2002
305: <!-- hhmts end -->
306: </body>
307: </html>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>