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