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> -
24: </li>
25: <li>
26: <i>Apache::lonxml::pwd</i> -
27: </li>
28: <li>
29: <i>Apache::lonxml::outputstack</i> -
30: </li>
31: <li>
32: <i>Apache::lonxml::redirection</i> -
33: </li>
34: <li>
35: <i>Apache::lonxml::import</i> -
36: </li>
37: <li>
38: <i>Apache::lonxml::extlinks</i> -
39: </li>
40: <li>
41: <i>Apache::lonxml::metamode</i> -
42: </li>
43: <li>
44: <i>Apache::lonxml::evaluate</i> -
45: </li>
46: <li>
47: <i>Apache::lonxml::insertlist</i> -
48: </li>
49: <li>
50: <i>Apache::lonxml::namespace</i> -
51: </li>
52: <li>
53: <i>Apache::lonxml::</i> -
54: </li>
55: </ul>
56:
57: <h3>Notable Perl subroutines</h3>
58: <p>
59: If not specified these functions are in Apache::lonxml
60: </p>
61: <ul>
62: <li>
63: <i>xmlparse</i> - see the XMLPARSE figure
64: </li>
65: <li>
66: <i>recurse</i> - acts just like <i>xmlparse</i>, except it
67: doesn't do the style definition check it always calls
68: <i>callsub</i>
69: </li>
70: <li>
71: <i>callsub</i> - callsub looks if a perl subroutine is defined
72: for the current tag and calls. Otherwise it just returns the
73: tag as it was read in. It also will throw on a default editing
74: interface unless the tag has a defined subroutine that either
75: returns something or requests that call sub not add the
76: editing interface.
77: </li>
78: <li>
79: <i>afterburn</i> - called on the output of xmlparse, it can
80: add highlights, anchors, and links to regular expersion
81: matches to the output.
82: </li>
83: <li>
84: <i>register_insert</i> - builds the
85: %Apache::lonxml::insertlist structure of what tags can have
86: what other tags inside.
87: </li>
88: </ul>
89: <h3>Functions Tag Handlers can use</h3>
90: <p>
91: If not specified these functions are in Apache::lonxml
92: </p>
93: <ul>
94: <li>
95: <i>debug</i> - a function to call to printout debugging
96: messages. Will only print when Apache::lonxml::debug is set to
97: 1
98: </li>
99: <li>
100: <i>warning</i> - a function to use for warning messages. The message
101: will appear at the top of a resource when it is viewed in
102: construction space only.
103: </li>
104: <li>
105: <i>error</i> - a function to use for error messages. The
106: message will appear at the top of a resource when it is viewed
107: in construction space, and will message the resource author
108: and course instructor, while informing the student that an
109: error has occured otherwise.
110: </li>
111: <li>
112: <i>get_all_text</i> - 2 args, tag to look for (need to use
113: /tag to look for an end tag) and a HTML::TokeParser reference,
114: it will repedelyt get text from the TokeParser until the
115: requested tag is found. It will return all of the document it
116: pulled form the TokeParser. (See
117: Apache::scripttag::start_script for an example of usage.)
118: </li>
119: <li>
120: <i>get_param</i> - 4 arguments, firsth is a scaler sting of
121: the argument needed, second is a reference to the parser
122: arguments stack, third is a reference to the Safe space, and
123: fourth is an optional "context" value. This subroutine allows
124: a tag to get a tag argument, after being interpolated inside
125: the Safe space. This should be used if the tag might use a
126: safe space variable reference for the tag argument. (See
127: Apaceh::scripttag::start_script for an example.)
128: </li>
129: <li>
130: <i>newparser</i> - 3 args, first is a reference to the parser
131: stack, second should be a reference to a string scaler
132: containg the text the newparser should run over, third should
133: be a scaler of the directory path the file the parser is
134: parsing was in. (See Apache::scripttag::start_import for an
135: example.)
136: </li>
137: <li>
138: <i>register</i> - should be called in a file's BEGIN block. 2
139: arguments, a scaler string, and a list of strings. This allows
140: a file to register what tags it handles, and what the
141: namespace of those tags are. Example:
142: <pre>
143: sub BEGIN {
144: &Apache::lonxml::register('Apache::scripttag',('script','display'));
145: }
146: </pre>
147: Would tell xmlparse that in Apache::scripttag it can find
148: handlers for <script> and <display>
149: </li>
150: <li>
151: <i>startredirection</i> - used when a tag wants to save a
152: portion of the document for its end tag to use, but wants the
153: intervening document to be normally processed. (See
154: Apache::scripttag::start_window for an example.)
155: </li>
156: <li>
157: <i>endredirection</i> - used to stop preventing xmlparse from
158: hiding output. The return value is everthing that xmlparse has
159: processed since the corresponding startredirection. (See
160: Apache::scripttag::end_window for an example.)
161: </li>
162: <li>
163: <i>Apache::run::evaluate</i> - 3 args, first a string, second
164: a reference to the Safe space, 3 a string to be evaluated
165: before the first arg. This subroutine will do variable
166: interpolation and simple function interpolations on the first
167: argument. (See Apache::lonxml::xmlparse for an example.)
168: </li>
169: <li>
170: <i>Apache::run::run</i> - 2 args, first a string, second a
171: reference to the Safe space. This handles passing the passed
172: string into the Safe space for evaluation and then returns the
173: result. (See Apache::scripttag::start_script for an example.)
174: </li>
175: </ul>
176:
177: <h2>Style Files</h2>
178: <h3>Style File specific tags</h3>
179: <ul>
180: <li>
181: <b><definetag></b> -
182: </li>
183: <li>
184: <b><render></b> -
185: </li>
186: <li>
187: <b><meta></b> -
188: </li>
189: <li>
190: <b><tex> / <web> / <latexsource></b> -
191: </li>
192: </ul>
193:
194: <hr>
195: <address><a href="mailto:albertel@marvin.lite.msu.edu">Guy Albertelli</a></address>
196: <!-- Created: Sun May 20 15:47:08 EDT 2001 -->
197: <!-- hhmts start -->
198: Last modified: Sun May 20 23:34:57 EDT 2001
199: <!-- hhmts end -->
200: </body>
201: </html>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>