Debian Codegraph @

doc/hacking-links.html

raw ◀ ▶
1 Debian patch touch this file
1 <html>
2 <head>
3 <title>netrik hacker's manual: hyperlink mechanism</title>
4 </head>
5 <body>
6
7 <h1 align="center">netrik hacker's manual<br />>========================&lt;</h1>
8
9 <p>
10 [This file contains a description of the hyperlink mechanism. See hacking.txt or
11 <a href="hacking.html">hacking.html</a> for an overview of the manual.]
12 </p>
13
14 <p>
15 In contrast to most other aspects of functionality, there is no seperate module
16 for link handling. The components forming the link mechanism are spread over
17 several other modules instead.
18 </p>
19
20 <p>
21 There is a links.c file (and a related links.h, of course), but it contains
22 only some simple helper functions -- at least for now.
23 </p>
24
25 <p>
26 There are also a number of specific files for form handling (forms.[ch],
27 form-file.[ch]), which is also part of the link handling module. (See
28 <a href="#forms">Forms</a> below.)
29 </p>
30
31 <h2>parse_struct()</h2>
32
33 <p>
34 The first step is done already in the layout module: The links need to be
35 extracted while parsing the structure of the page to generate the item tree.
36 This is described under
37 <a href="hacking-layout.html#links">Links</a> in hacking-layout.*.
38 </p>
39
40 <a name="linkStruct" id="stringLink">
41
42 <h3>Link Struct</h3>
43
44 <p>
45 The start and end position of a link, and the link's destination (extracted
46 from the "href" attribute) are stored in "string->link[]".
47 </p>
48
49 <p>
50 This is a list of "struct Link", containing the data of all links and form
51 controls inside the current text item:
52 <ul> <li>
53 The ints "start" and "end" store the start and end postitions of the link
54 inside the string
55 </li><li>
56 The page coordinates of the link are stored in "x_start", "x_end", "y_start"
57 and "y_end"
58 </li><li>
59 The "value" contains the link's destination URL for normal links, or the form
60 data for form controls. "value" is of type "struct Data_string", which is a
61 Pascal-like string structure with a data area (dynamic array of char) and an
•62 explicitly stored string length. This is necessary for binary form data, as
63 this can contain NUL bytes. For normal links, the URL is stored as a normal C
64 string in the "data" component, and the "size" component is unused.
65 </li><li>
66 "form" is an "enum Form_control", telling to what kind of link or form control
67 the link structure refers
68 </li><li>
69 "name" is a string storing the value of the "name" or "id" attribute
70 identifying a form control
71 </li><li>
72 The "enabled" flag indicates whether a form element is to be submitted to the
73 server; for conditional elements (checkboxes etc.) this depends on the
74 current state
75 </li></ul>
76 </p>
77
78 </a> <!-- linkStruct -->
79
80 <a name="linkList" id="linkList">
81
82 <h2>Link List</h2>
83
84 <p>
85 To allow easy access to all links on the page without having to scan every text
86 item, another structure is created. This structure doesn't itself store any
87 data; it only stores pointers to the entries inside the text items' link lists.
88 </p>
89
90 <p>
91 The "Link_list" structure (defined in items.h) contains:
92 </p>
93
94 <ul><li>
95 The number of strings on the page, and
96 </li><li>
97 An array of "struct Link_ptr", containing for every link:
98 </li>
99 <ul> <li>
100 The item containing the link
101 </li><li>
102 The number of the link inside the item's link list
103 </li></ul>
104 </ul>
105
106 <p>
107 This structure is created by make_link_list() (just after parse_struct()). This
108 function traverses all items, and for every encountered text item stores
109 pointers to all of its links. The only exception are links representing
110 "hidden" form input fields: These aren't stored in the link list, so they won't
111 be selectable.
112 </p>
113
114 </a> <!-- linkList -->
115
116 <a name="preRender" id="preRender">
117
118 <h2>pre_render()</h2>
119
120 <p>
121 When assigning coordinates to all items in the various sub-functions of
122 pre_render() (as another part of the layouting process), the page coordinates
123 of the links also have to be calculated. This is done in assign_ywidth(), and
124 described under <a href="hacking-layout.html#linkCoords">Link
125 Coordinates</a> in hacking-layout.*.
126 </p>
127
128 </a> <!-- preRender -->
129
130 <a name="pager" id="pager">
131
132 <h2>display()</h2>
133
134 <p>
135 After the links are extracted during layouting, they can be activated and
136 followed in the pager. (Which is described in
137 <a href="hacking-pager.html">hacking-pager.*</a>)
138 </p>
139
140 <h3>Activating Links</h3>
141
142 <p>
143 Links can be activated in the pager using the various link selection commands,
144 or the cursor movement comands if the cursor is moved over a link.
145 </p>
146
147 <p>
148 How these commands decide which link to activate, is described under
149 <a href="hacking-pager.html#select">Link Selection Commands</a> in
150 hacking-pager.*.
151 </p>
152
153 <a name="activateLink" id="activateLink">
154
155 <h4>activate_link()</h4>
156
157 <p>
158 Actually activating (or deactivating) a selected link is done with the
•159 activate_link() function. This function is explicitly called by the link
160 selection commands, but can be also called by
161 <a href="hacking-pager.html#scrollTo">scroll_to()</a> (see
162 hacking-pager.*) automatically, if the active link is scrolled out of the valid
163 screen area.
164 </p>
165
166 <p>
167 As a special case, the current link is deactivated by calling activate_link
168 with -1 as argument, so no link is active afterwards.
169 </p>
170
171 <p>
172 Before activating the requested link, the page is scrolled so that the link is
173 actually in the valid screen area. (This isn't done when called with -1, as
174 links can be deactivated even if they are no longer on the screen.) Scrolling
175 is done using
176 <a href="hacking-pager.html#scrollTo">scroll_to()</a>.
177 </p>
178
179 <p>
180 Next step is deactivating a previously active link, if any. This is done by
181 recursively calling active_link() (with -1 as argument). Of course this is also
182 done only when activating a new link -- if we are only to deactivate the
183 current active one, we won't call ourself to do so...
184 </p>
185
186 <a name="highlight" id="highlight">
187
188 <p>
189 Now the affected link is highlighted (or unhighlighted, if it is to be
190 deactivated) using the highligh_link() function from links.c. This function
191 takes the page descriptor (for the item tree and the link list), the link
192 number, and a flag indicating whether to highlight or unhighlight as arguments.
193 The higlighting is done by finding the first div of the associated string that
194 belongs to the link text, and changing the background color of it (and all
195 other divs before the link end). This is done by or-ing the color with
196 "color_map[TM_ACTIVE]"; deactivating is done by clearing the bits.
197 </p>
198
199 </a>
200
201 <p>
202 Afterwards, the screen area affected by the link activation is re-rendered.
203 </p>
204
205 <p>
206 The coordinates of the affected page area normally are determined by the
207 coordinates assigned to the link in
208 <a href="#preRender">pre_render()</a>; if the link spans
209 multiple lines (contains line wraps) however, the x-coordinates of the item
210 containing the link are taken instead, so all lines containing parts or the
211 link are repainted as a whole. (It would be too complicated to determine the
212 exact affected line parts, and it doesn't make much of a difference anyhow.)
213 </p>
214
215 <p>
216 The coordinates are truncated to the part visible on the screen, and the area
217 is repainted.
218 </p>
219
220 <p>
221 Finally, "active_link" is set to the newly activated link, and the cursor
222 position is updated. If a new link is actually activated, not the old one
223 deactivated, the cursor is set to the beginning of the link with
224 <a href="hacking-pager.html#setCursor">set_cursor()</a> (see
225 hacking-pager.*); it will keep this position as long as the link is active.
226 </p>
227
228 <p>
229 When activating a new link, some additional variables are assigned also: Hashes
230 of the link URL and contained text are copied from the link structure. These
231 are necessary to be able to activate the right link when the page is revisited
232 later, but the page content has changed in the meantime. This is explained
233 under <a href="hacking-page.html#reactivating">_Reactivating
234 Link</a> in hacking-page.*.
235 </p>
236
237 </a> <!-- activateLink -->
238
239 <h3>Following Links</h3>
240
241 <p>
242 If some link is active, it can be followed in the pager by pressing &lt;return>.
243 The pager immediatly exits in this case, with a return value indicating that a
244 link was followed; everything else has to be done by the caller. (s.b.)
245 </p>
246
247 </a> <!-- pager -->
248
249 <a name="followLink" id="followLink">
250
251 <h2>main()</h2>
252
253 <p>
254 Following the links itself is done in main(). When it sees that a link was
255 followed (the pager returned "RET_LINK"), first the "active_link" URL has to be
256 extracted.
257 </p>
258
259 <a name="getLink" id="getLink">
260
261 <p>
262 get_link() retrieves the link structure of the desired link (by the page's link
263 list) inside the item tree, and returns a pointer to it, so all link data can be
264 accessed.
265 </p>
266
267 </a>
268
269 <p>
270 The URL stored in the link structure ist copied to the local "url".
271 </p>
272
273 <p>
274 Having this, the old page is not needed any longer, and is freed using
275 <a href="hacking-layout.html#freeLayout">free_layout()</a>;
276 afterwards, the new page is loaded using
277 <a href="hacking-page.html#loadPage">load_page()</a> with the
278 current page's URL as base.
279 </p>
280
281 <p>
282 If the link only references a local anchor (the URL starts with '#'), the old
283 page isn't freed; instead, its descriptor is passed as the "reference"
284 parameter to load_page(), so the page data will be reused and only the anchor
285 activated, instead of reloading the page.
286 </p>
287
288 </a> <!-- followLink -->
289
290 <h2>init_load()</h2>
291
292 <p>
293 The full URL of the new page to be loaded needs to be determined using the link
294 URL and the current page's URL. That is done in
295 <a href="hacking-load.html#initLoad">init_load()</a> (called from
296 load_page()). This process is described in detail in
297 <a href="hacking-load.html">hacking-load.*</a>.
298 </p>
299
300 <h2>Forms</h2>
301
302 <p>
303 HTML forms are handled together with links. The "form" element of the
304 <a href="#linkStruct">Link Struct</a> indicates that the link list
305 entry refers to some form control, not to a normal link.
306 </p>
307
308 <h3>forms.c</h3>
309
310 <p>
311 forms.c contains some helper functions for handling forms.
312 </p>
313
314 <a name="setForm" id="setForm">
315
316 <h4>set_form()</h4>
317
318 <p>
319 set_form() writes the value of a form control (given by its link structure as
320 argument) to a string in the item tree, so it will be displayed on the output
321 page. It is called directly to set the initial value just after the form
322 element was extracted during structure parsing, when the link list doesn't
323 exist yet.
324 </p>
325
326 <p>
327 (It is presently also used instead of update_form() in one place -- which is a
328 hack; see below under <a href="#manipulating">Manipulating</a>.)
329 </p>
330
331 <p>
332 First it has to find out where to store the data. For this, the string
333 containing the element is searched for the first div *after* the link start.
334 (The first div of a form link, starting at the link start, is the form
335 indicator, e.g. '['; the following div then contains the value.)
336 </p>
337
338 <p>
339 Having this, the value can be stored to the string. How this is done depends on
340 the type of the form control.
341 </p>
342
343 <p>
344 For text, password, and hidden input fields, as much of the "value" as the div
345 length is copied to the string div. If there is less than the div length, the
346 remaining space is padded with '_' characters. (Hidden input fields are
347 displayed like text fields, only they are "dim", and can't be selected.)
348 </p>
349
350 <p>
351 Textareas are also handled like normal single-lined text input fields for now.
352 (The linefeeds will be simply replaced by spaces, just like any other control
353 characters.)
354 </p>
355
356 <p>
357 For radio buttons and checkboxes, either an '*' is put in, or an nbsp. This is
358 determined by the "enabled" flag of the form link. (It does *not* depend on the
359 "value"!)
360 </p>
361
362 <p>
363 For &lt;select> options, the character introducing the option (the one *before*
364 the first char of the option text) is set either to '+' or to '-', also
365 depending on whether "enabled" is set.
366 </p>
367
368 </a> <!-- setForm -->
369
370 <h4>update_form()</h4>
371
372 <p>
373 update_form() is very similar; the difference is that it takes the whole page
374 structure and a link number from the link list as arguments; the string and the
375 link structure are then extracted from the list, and set_form() is called to
376 actually set the data.
377 </p>
378
379 <a name="getForm" id="getForm">
380
381 <h4>get_form_item()</h4>
382
383 <p>
384 get_form_item() is used to find out to which form a form control belongs. (This
385 is necessary for submit buttons.) It takes the link number of the form control,
386 retrieves the right form item in the item tree, and returns a pointer to it.
387 </p>
388
389 <p>
390 The form item is found by starting with the item containing the form control
391 (determined by the <a href="#linkList">Link List</a>), and going
392 up in the item tree until an item of type ITEM_FORM is found -- it contains the
393 item with the button, so it belongs to the form in which the button is located.
394 </p>
395
396 </a> <!-- getForm -->
397
398 <a name="formIterate" id="formIterate">
399
400 <h4>form_next()</h4>
401
402 <p>
403 form_next() (together with form_start()) is used to get all form elements of
404 some form from the item tree. (This is necessary when submitting, or when
405 activating "radio" input elements.) Depending on the "filter" flag, it returns
406 either all form elements, or only the ones that are "successful" (have a name,
407 a value, and are enabled), and should be submitted to the server.
408 </p>
409
410 <p>
411 Every time it is called, it returns one link pointer, belonging to a form
412 control. When there are no more elements in the form NULL is returned.
413 </p>
414
415 <p>
416 form_next() takes/returns a "struct Form_handle" as parameter, which stores the
417 form item, the item of the last returned link, the link number of the last
418 returned link, and the "filter" flag. This is used to keep track of which form
419 elements have already been returned in previous calls. The handle has to be
420 initialized by form_start(), which takes the form item and the "filter" flag as
421 paramters, and returns the handle. (Not a pointer!)
422 </p>
423
424 <p>
425 form_next() traverses all items below the form item, using the "list_next"
426 pointers. In every text item found, it scans all of its links. Both loops work
427 directly with the handle values as loop variables. They are not initialized on
428 entering, so that they continue right where the last call to form_next()
429 stopped.
430 </p>
431
432 <p>
433 To ensure all items inside the form are scanned, form_start() has to find the
434 first item inside the form, so form_next() will start scanning there. This is
435 done by repeatedly descending to "first_child", until a childless item is found
436 -- this is always the first one in the form.
437 </p>
438
439 <p><pre>
440 +------+ start --> +------+
441 | text |-. ,->| form |
442 +------+=|===============================================================================|=>+------+
443 | | x ^
444 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +
445 | x ++++++++++++++++++++++++++++++++++++
446 | v + + |
447 | +-----+ +-----+ |
448 | 1. descend --> ,->| box |-. ,->| box |-'
449 | | +-----+=|===========|=>+-----+==>NULL
450 | | x ^ | | x ^
451 | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + | xxxxxxxxxxxxx +
452 | x +++++++++++++++++++++++++++++++++++++++++++++++ | x +++++++++++++
453 | v + + + | | v + |
454 | +------+ +------+ +-----+ | | +------+ |
455 `->| text |-->| text |-. ,->| box |-' `->| text |-'
456 ,--> +------+==>+------+=|===========|=>+-----+==============>+------+==>NULL
457 | x x | | x ^ x
458 2. descend v v | xxxxxxxxxxxxx + v
459 (goal) NULL NULL | x +++++++++++++ NULL
460 | v + |
461 | +------+ |
462 `->| text |-'
463 +------+==>NULL
464 </pre></p>
465
466 <p>
467 (See <a href="hacking-layout.html#itemTree">Structure Tree</a> in
468 hacking-layout.* for a description of the item tree.)
469 </p>
470
471 </a> <!-- formIterate -->
472
473 <a name="urlEncode" id="urlEncode">
474
475 <h4>url_encode()</h4>
476
477 <p>
478 url_encode() is responsible for creating the string that will be submitted to
479 the server as part of the URL when a form is posted using the "GET" method, or
480 in the HTTP request body when using the "POST" method with URL encoding.
481 </p>
482
483 <p>
484 This function retrieves all (successful) form controls from the given form,
485 using form_start()/form_next(). For each form control, the name and the value
486 are stored, separated by an '=' and followed by an '&amp;'. In both name and value,
487 certain characters have to be escaped, which is done in the encode_string()
488 helper function.
489 </p>
490
491 <p>
492 Spaces are replaced by a '+'. Special characters, including all
493 non-ASCII-characters as well as a "real" '+' and some other characters with
494 special meaning inside the URL ('&amp;', '=', '%' and '#') are replaced by a
495 hexadecimal representation, introduced with a '%' char. ("%HH") Other
496 characters are stored directly.
497 </p>
498
499 <p>
500 For "file" form controls, the "value" isn't submitted directly; the *contents*
501 of the file named in "value" is loaded into memory instead (using
502 <a href="#formReadFile">form_read_file()</a>, see below) and
503 encoded.
504 </p>
505
506 <p>
507 The memory for the created string is allocated in chunks, for efficency
508 reasons. This is done inside encode_string(). As soon as the currently allocated
509 size of the string doesn't suffice to hold the next character, it is grown by
510 one chunk. The test is very crude, to keep it simple: The array is considered
511 too small if there is space for less then 5 characters, as up to 5 characters
512 may be stored before the next test, in the worst case: Up to 3 for the
513 currently processed char (if it has to be hex-escaped), plus the following '='
514 if we are at the last character in the name, plus the '&amp;' if the value for this
515 form control is empty. (No checking is done before storing the '=' and '&amp;', so
516 we have to reserve the place for them here!)
517 </p>
518
519 <p>
520 The return value is a "struct Data_string" -- this is not really necessary, as
521 URL encoded strings never contain a NUL character, and thus could be passed as
522 a normal C string; but we do this anyways to get consistency with
523 mime_encode().
524 </p>
525
526 </a> <!-- urlEncode -->
527
528 <a name="mimeEncode" id="mimeEncode">
529
530 <h4>mime_encode()</h4>
531
532 <p>
533 mime_encode() does the same as url_encode, except that the data is encoded
534 using multipart MIME format.
535 </p>
536
537 <p>
538 This is much simpler: There is no encoding necessary to the data itself; only
539 the mime header information have to be stored along with the data itself.
540 </p>
541
542 <p>
543 As the size of a data block can be easily calculated here, the string is first
544 resized to fit the new block in each iteration (for each name/value pair), and
545 then the data is stored with a simple sprintf() and a few memcpy() calls. This
546 should be much more efficient than the approach in url_encode for bigger data
547 blocks, especially files.
548 </p>
549
550 <p>
551 The size is estimated by adding the size of the data strings ("name" and
552 "value") to the size of the format string -- this is not exact (the format
553 specifiers ("%s") are counted, though they are replaced in the resulting
554 string), but the few bytes too much shouldn't matter. (Especially as they will
555 be used up later anyways...)
556 </p>
557
558 <p>
559 Just like in <a href="#urlEncode">url_encode</a>, "file"
560 controls need a special handling. As in mime encoding the file name is
•561 submitted explicitly, we need an additional "file_name" parameter. This makes
562 the handling more complicated than in url_encode().
563 </p>
564
565 <p>
566 Note that, to reduce the amount of extra code, the "file_name" parameter is
567 also used with other form controls; it is simply set to the an empty string.
568 (And a dummy "%s" is passed to snprintf() so the parameter will be consumed --
569 the empty string won't affect the output.)
570 </p>
571
572 <p>
573 mime_encode() has to operate on and return a "struct Data_string" (see
574 <a href="#linkStruct">Link Structure</a> above for a description,
575 under "value"), as the form may contain binary data with NUL characters -- we
576 can't use normal C strings here.
577 </p>
578
579 </a> <!-- mimeEncode -->
580
581 <a name="formReadFile" id="formReadFile">
582
583 <h4>form_read_file()</h4>
584
585 <p>
586 Reading the files of "file" form controls into memory is done with
587 form_read_file(), which is located in form-file.c. This function takes the name
588 of a file to read as parameter, and returns a "struct Data_string" (not a
589 pointer!) with the contents of the named file.
590 </p>
591
592 <p>
593 If reading the file failed for some reason, an error message is printed, and a
594 "Data_string" with -1 as "size" (and NULL as "data") is returned, indicating
595 that an errer occured and the string doesn't contain valid data. (The caller
596 has to handle this.)
597 </p>
598
599 <p>
600 form_read_file() actually doesn't do very much -- the real loading is done in
601 the local read_file() function (also used for
602 a href="#editTextarea">edit_textarea()</a>); form_read_file() is
603 just a wrapper.
604 </p>
605
606 </a> <!-- formReadFile -->
607
608 <h3>Preparing</h3>
609
610 <p>
611 The form controls are extracted in
612 <a href="hacking-layout.html#parseStruct">parse_struct()</a>
613 (described in hacking-layout.*), just like normal links. The only difference
614 (besides of storing the "value" and "enabled" variables) is that the initial
615 value/state of a form control has to be displayed on the page, which is done by
616 set_form().
617 </p>
618
619 <a name="manipulating" id="manipulating">
620
621 <h3>Manipulating</h3>
622
623 <p>
624 When &lt;return> is pressed on a selected form control (display() returns RET_LINK,
625 and "form" of "active_link" is not FORM_NO), special action is taken in main().
626 </p>
627
628 <p>
629 On a form control, this generally involves getting a new value (either
630 implicit by the link activation, or by explicit input), which is then saved
631 either in "link->value" or in "link->enabled" (depending on the control type),
632 and also stored to the item tree with update_form(). (So the new value will
633 show up on the output page.)
634 </p>
635
636 <p>
637 For text and password input fields, the user is prompted for a new value, which
638 is stored in "link->value".
639 </p>
640
641 <p>
642 File input fields are also handled here. There is one additional test however:
643 If some file name is actually specified (not an empty value), we test whether
644 the file exists and is readable, so the user will see immediately if a wrong
645 file name was entered.
646 </p>
647
648 <p>
649 For checkboxes, simply the "link->enabled" flag is toggled.
650 </p>
651
652 <p>
653 For radio buttons, "link->enabled" is set for the activated button, and reset
654 for all other radio buttons in the form which have the same "name". This is
655 done by iterating through all form items (with form_start()/form_next() without
656 "filter"), and every time a control with the same name is found, disabling it.
657 Reflecting the disabling in the item tree can't be done with update_form()
658 however, as the link number in the link list isn't known here. (It's not
659 returned nor used by form_next().) Thus, we grab the current string item from
660 the handle used by form_next(), and call set_form() with that. This is a hack
661 (it depends on the implementation of "struct Form_handle", which it shouldn't);
662 however, I don't know any simple and reasonable way to implement that with the
663 current link storing mechanism...
664 </p>
665
666 <p>
667 For &lt;select> options, the behaviour depends on whether the select has the
668 "multiple" attribute. (Which is coded in the link type: Either "FORM_OPTION" or
669 "FORM_MULTIOPTION") If yes, they behave like checkboxes, otherwise like radio
670 buttons.
671 </p>
672
673 <p>
674 On a submit button, a page load is performed (using
675 <a href="hacking-page.html#loadPage">load_page()</a> as usual);
676 the target URL is taken from the "data.form->url" field of the item
677 representing the form to which the button belongs, retrieved with
678 <a href="#getForm">get_form_item()</a>. The "form" parameter is
679 set to the form item itself; load_page() passes this on to
680 <a href="hacking-load.html#initLoad">init_load()</a>, where it is
681 handled appropriately. (See hacking-load.*)
682 </p>
683
684 <a name="editTextarea" id="editTextarea">
685
686 <h4>edit_textarea()</h4>
687
688 <p>
689 &lt;textarea> fields are more tricky. They require an own function to do the work,
690 which is located in form-file.c.
691 </p>
692
693 <p>
694 The textarea fields aren't manipulated in netrik directly; instead, an external
695 editor is invoked. (Determined the DITOR environment variable, falling back
696 to "vi".) The form data is passed to that editor in a temporary file; after the
697 editor quits, the new content of the file is read and stored in the form.
698 </p>
699
700 <p>
701 The major difficulty is the heavy use of system functions, inducing a multitude
702 of possible error conditions which have to be checked for. On each error
703 condition, edit_textarea() exits returning a string describing the error; this
704 is then printed in main().
705 </p>
706
707 </a> <!-- editTextarea -->
708
709 </a> <!-- manipulating -->
710
711 <a name="submit" id="submit">
712
713 <h3>Submitting</h3>
714
715 <p>
716 When init_load() is called with a "form" argument, the form data is extracted
717 and encoded, and passed to the HTTP server.
718 </p>
719
720 <p>
721 For forms using the "GET" submit method, this is done in init_load() itself.
722 The data is extracted and encoded using
723 <a href="#urlEncode">url_encode()</a>; the resulting CGI
724 parameter string is then passed to
725 <a href="hacking-load.html#mergeUrls">merge_urls()</a>, where it is
726 stored as part of the resulting target URL (in place of any other CGI
727 paramters). As the form data is now part of the URL, no other special handling
728 is necessary -- it will be passed to the server with the URL.
729 </p>
730
731 <p>
732 For "POST" forms, the form item is simply passed on to http_init_load() and
733 from there to get_http_cmd(), where either url_encode() or
734 <a href="#mimeEncode">mime_encode()</a> is used to get the encoded
735 form data, which is then stored in the body of the HTTP request and passed to
736 the server.
737 </p>
738
739 </a> <!-- submit -->
740
741 <a name="anchors" id="anchors">
742
743 <h2>Anchors</h2>
744
745 <p>
746 If the loaded link contains a fragment identifier, "active_anchor" is set to
747 the desired anchor after loading the page. This is done in
748 <a href="hacking-page.html#loadPage">load_page()</a> (described
749 in hacking-layout.*), after all other steps of the loading process are
750 completed.
751 </p>
752
753 <p>
754 Similar to links, anchors are extracted while parsing the page structure.
755 However, they are stored in another way: Every anchor has an own item, either
756 of type ITEM_BLOCK_ANCHOR or ITEM_INLINE_ANCHOR, depending on the anchor type.
757 Both types are <a href="hacking-layout.html#virtual">Virtual
758 Items</a>; this is described in hacking-layout.*.
759 </p>
760
761 <a name="anchorList" id="anchorList">
762
763 <p>
764 After extracting the anchors, the "anchor_list" data structure is created
765 (using make_anchor_list()), which is very similar to the
766 "<a href="#linkList">link_list</a>". It consists only of the total
767 anchor count, and an array containing pointers to every anchor item.
768 </p>
769
770 </a>
771
772 <p>
773 Jumping to an anchor primarily implies retrieving the matching anchor number. This is
774 done (inside load_page()) by comparing the fragment identifier given in the URL
775 with the names of all anchors from the anchor list. When the right anchor is
776 found, its entry number in the anchor list is stored in "page->active_anchor".
777 </p>
778
779 <p>
780 Displaying the anchor itself is done in the pager. When
781 <a href="hacking-pager.html#display">display()</a> (described in
782 hacking-pager.*) finds an "anctive_anchor" while starting up, it calls
783 activate_anchor() to jump to and show the anchor position.
784 </p>
785
786 <a name="activateAnchor" id="activateAnchor">
787
788 <h3>activate_anchor()</h3>
789
790 <p>
791 This function first calculates the position to scroll the page to. This
792 position depends on the setting of the "anchor_offset" config variable: If this
793 has a nonzero value, the page is scrolled so that the anchor will start at the
794 reciprocal value of "anchor_offset" of the screen height; when "anchor_offset"
795 is five for example (current default), we will scroll to the anchor start
796 position minus one fifth of LINES -- the anchor start will appear one fifth of
797 the screen height below the screen top. If "anchor_offset" is zero, the anchor
798 will be shown "link_margin" lines below the screen top instead.
799 </p>
800
801 <p>
802 With this calculated "optimal" scroll position scroll_to() is called, and
803 returns the actual pager position -- this may differ from the requested when
804 the anchor is near the screen top or bottom. Having this, the actual screen
805 positions of the anchor start and end are calculated. If these are identical
806 (empty block anchor), the end position (pointing, as always, *after* the last
807 anchor line), is incremented by one to cause a mark being displayed in the next
808 line. The theoretical start and end positions are then truncated to the screen
809 boundaries.
810 </p>
811
812 <p>
813 Finally, a mark (the string "cfg.anchor_mark") is printed in the rightmost
814 column of every screen line in the area spanned by the link, as calculated
815 before. These marks are printed directly to the curses screen; they aren't
816 stored in the item tree.
817 </p>
818
819 <p>
820 The cursor is moved to the exact anchor start position using
821 <a href="hacking-pager.html">set_cursor()</a> (see
822 hacking-pager.*).
823 </p>
824
825 <p>
826 When activate_anchor() is called with -1 as anchor number, the previously
827 activated anchor is deactivated. The page isn't scrolled in this case, but the
828 screen position of the anchor is calculated as well; the marks are cleared by
829 re-rendering the area where the marks were drawn. (Calling
830 <a href="hacking-layout.html#render">render()</a> (described in
831 hacking-layout.*) with the "overpaint" flag.)
832 </p>
833
834 </a> <!-- activateAnchor -->
835
836 <p>
837 The deactivating is done by the pager after the first keypress. (*After* the
838 associated function was performed.)
839 </p>
840
841 </a> <!-- anchors -->
842
843 </body>
844 </html>