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