| 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 />>========================<</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 |
explicitely 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 explicitely 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 <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 <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 '&'. 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 ('&', '=', '%' 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 '&' if the value for this |
| 515 |
form control is empty. (No checking is done before storing the '=' and '&', 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 explicitely, 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 <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 <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 |
<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> |