Annotation of doc/homework/xml.html, revision 1.4
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.2 albertel 26: <i>@Apache::lonxml::pwd</i> - path to the directory containing the file currently being processed
1.1 albertel 27: </li>
28: <li>
1.2 albertel 29: <i>@Apache::lonxml::outputstack</i> <br />
30: <i>$Apache::lonxml::redirection</i> - these two are used for
31: capturing a subset of the output for later processing, don't
32: touch them directly use &startredirection and &endredirection
1.1 albertel 33: </li>
34: <li>
1.2 albertel 35: <i>$Apache::lonxml::import</i> - controls whether the
36: <import> tag actually does anything
1.1 albertel 37: </li>
38: <li>
1.3 albertel 39: <i>@Apache::lonxml::extlinks</i> - a list of URLs that the
40: user is allowed to look at because of the current resource
41: (images, and links)
1.1 albertel 42: </li>
43: <li>
1.2 albertel 44: <i>#Apache::lonxml::metamode</i> - some output is turned off,
45: the meta target wants a specific subset, use <output> to
46: guarentee that the catianed data will be in the parsing output
1.1 albertel 47: </li>
48: <li>
1.2 albertel 49: <i>#Apache::lonxml::evaluate</i> - controls whether
50: run::evaluate actually derefences variable references
1.1 albertel 51: </li>
52: <li>
1.2 albertel 53: <i>%Apache::lonxml::insertlist</i> - data structure for edit
54: mode, determines what tags can go into what other tags
1.1 albertel 55: </li>
56: <li>
1.2 albertel 57: <i>@Apache::lonxml::namespace</i> - stores the list of tag
58: namespaces used in the insertlist.tab file that are currently
59: active, used only in edit mode.
1.1 albertel 60: </li>
1.3 albertel 61: <li>
62: <i>$Apache::lonxml::registered</i> - set to 1 once the remote
63: has been updated to know what resource we are looking at.
64: </li>
1.4 ! albertel 65: <li>
! 66: <i>$Apache::lonxml::request</i> - current Apache request
! 67: object, or undef
! 68: </li>
1.1 albertel 69: </ul>
70:
71: <h3>Notable Perl subroutines</h3>
72: <p>
73: If not specified these functions are in Apache::lonxml
74: </p>
75: <ul>
76: <li>
77: <i>xmlparse</i> - see the XMLPARSE figure
78: </li>
79: <li>
80: <i>recurse</i> - acts just like <i>xmlparse</i>, except it
81: doesn't do the style definition check it always calls
82: <i>callsub</i>
83: </li>
84: <li>
85: <i>callsub</i> - callsub looks if a perl subroutine is defined
86: for the current tag and calls. Otherwise it just returns the
87: tag as it was read in. It also will throw on a default editing
88: interface unless the tag has a defined subroutine that either
89: returns something or requests that call sub not add the
90: editing interface.
91: </li>
92: <li>
93: <i>afterburn</i> - called on the output of xmlparse, it can
94: add highlights, anchors, and links to regular expersion
95: matches to the output.
96: </li>
97: <li>
98: <i>register_insert</i> - builds the
99: %Apache::lonxml::insertlist structure of what tags can have
100: what other tags inside.
101: </li>
1.3 albertel 102: <li>
103: <i>whichuser</i> - returns a list of $symb, $courseid,
104: $domain, $name that is correct for calls to lonnet functions
105: for this setup. Uses form.grade_ parameters, if the user is
106: allowed to mgr in the course
107: </li>
1.1 albertel 108: </ul>
109: <h3>Functions Tag Handlers can use</h3>
110: <p>
111: If not specified these functions are in Apache::lonxml
112: </p>
113: <ul>
114: <li>
115: <i>debug</i> - a function to call to printout debugging
116: messages. Will only print when Apache::lonxml::debug is set to
117: 1
118: </li>
119: <li>
120: <i>warning</i> - a function to use for warning messages. The message
121: will appear at the top of a resource when it is viewed in
122: construction space only.
123: </li>
124: <li>
125: <i>error</i> - a function to use for error messages. The
126: message will appear at the top of a resource when it is viewed
127: in construction space, and will message the resource author
128: and course instructor, while informing the student that an
129: error has occured otherwise.
130: </li>
131: <li>
132: <i>get_all_text</i> - 2 args, tag to look for (need to use
133: /tag to look for an end tag) and a HTML::TokeParser reference,
134: it will repedelyt get text from the TokeParser until the
135: requested tag is found. It will return all of the document it
136: pulled form the TokeParser. (See
137: Apache::scripttag::start_script for an example of usage.)
138: </li>
139: <li>
140: <i>get_param</i> - 4 arguments, firsth is a scaler sting of
141: the argument needed, second is a reference to the parser
142: arguments stack, third is a reference to the Safe space, and
143: fourth is an optional "context" value. This subroutine allows
144: a tag to get a tag argument, after being interpolated inside
145: the Safe space. This should be used if the tag might use a
146: safe space variable reference for the tag argument. (See
147: Apaceh::scripttag::start_script for an example.)
148: </li>
149: <li>
150: <i>newparser</i> - 3 args, first is a reference to the parser
151: stack, second should be a reference to a string scaler
152: containg the text the newparser should run over, third should
153: be a scaler of the directory path the file the parser is
154: parsing was in. (See Apache::scripttag::start_import for an
155: example.)
156: </li>
157: <li>
158: <i>register</i> - should be called in a file's BEGIN block. 2
159: arguments, a scaler string, and a list of strings. This allows
160: a file to register what tags it handles, and what the
161: namespace of those tags are. Example:
162: <pre>
163: sub BEGIN {
164: &Apache::lonxml::register('Apache::scripttag',('script','display'));
165: }
166: </pre>
167: Would tell xmlparse that in Apache::scripttag it can find
168: handlers for <script> and <display>
169: </li>
170: <li>
171: <i>startredirection</i> - used when a tag wants to save a
172: portion of the document for its end tag to use, but wants the
173: intervening document to be normally processed. (See
174: Apache::scripttag::start_window for an example.)
175: </li>
176: <li>
177: <i>endredirection</i> - used to stop preventing xmlparse from
178: hiding output. The return value is everthing that xmlparse has
179: processed since the corresponding startredirection. (See
180: Apache::scripttag::end_window for an example.)
181: </li>
182: <li>
183: <i>Apache::run::evaluate</i> - 3 args, first a string, second
184: a reference to the Safe space, 3 a string to be evaluated
185: before the first arg. This subroutine will do variable
186: interpolation and simple function interpolations on the first
187: argument. (See Apache::lonxml::xmlparse for an example.)
188: </li>
189: <li>
190: <i>Apache::run::run</i> - 2 args, first a string, second a
191: reference to the Safe space. This handles passing the passed
192: string into the Safe space for evaluation and then returns the
193: result. (See Apache::scripttag::start_script for an example.)
194: </li>
195: </ul>
196:
197: <h2>Style Files</h2>
198: <h3>Style File specific tags</h3>
199: <ul>
200: <li>
1.2 albertel 201: <b><definetag></b> - 2 arguments, <i>name</i> name of
202: new tag being defined, if proceeded with a / defining an end
203: tag, required; <i>parms</i> parameters of the new tag, the
204: value of these parameters can be accesed by $parametername.
1.1 albertel 205: </li>
206: <li>
1.2 albertel 207: <b><render></b> - define what the new tag does for a non meta target
1.1 albertel 208: </li>
209: <li>
1.2 albertel 210: <b><meta></b> - define what the new tag does for a meta target
1.1 albertel 211: </li>
212: <li>
1.2 albertel 213: <b><tex> / <web> / <latexsource></b> -
214: define what a new tag does for a specific no meta target, all
215: data inside a <render> is render to all targets except
216: when surrounded by a specific target tags.
1.1 albertel 217: </li>
218: </ul>
219: <hr>
220: <address><a href="mailto:albertel@marvin.lite.msu.edu">Guy Albertelli</a></address>
221: <!-- Created: Sun May 20 15:47:08 EDT 2001 -->
222: <!-- hhmts start -->
1.4 ! albertel 223: Last modified: Thu May 23 17:19:29 EDT 2002
1.1 albertel 224: <!-- hhmts end -->
225: </body>
226: </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