|
If you've played with the patent example, by now you
might have noticed that it remembers your last query when you click
on a patent for details, even though that's not a form submission.
Also, for each patent link, it automatically knows to bring up the
correct patent you clicked on, a different one for each link. How does
Vortex remember those variables, even though each browser click
results in a new call to Vortex from scratch? We call this state
retention : retaining the state of the script across invocations.
In most languages one has to do this "manually" by embedding variables
in URLs.
EXPORT
In Vortex, state retention is automatically handled with the <EXPORT>
directive. This tells Vortex what variables are to be
preserved for future transactions. In our patent example, we're
preserving $id
, because it tells us what patent to bring
up in the <details>
function. Also $skip
, which
tells us what page in the result set we're on. Finally,
$query
and $when
are remembered, so we can
fill out the search form with the user's last query even on a details
page.
<EXPORT>
variables are saved whenever the special Vortex
variable $url
is printed. There are three ways this
happens, depending on the flag given to <EXPORT>
or the use
of the variable:
- State table - TABLE
Variables that are given the EXPORT
flag TABLE
, or are
not in a <LOOP>
, are written to the state table (vortex
). These are known as state-table variables.
- URL state - URL
Variables that are given the flag URL
, or are in a <LOOP>
or <SQL>
loop, have their current value(s)
saved, but scrambled to the URL instead. These are known as URL
state variables. All of our <EXPORT>
variables in the
patent example have this flag.
- Query string - QUERY
Variables that are given the flag QUERY
are saved as a
URL-encoded query-string to the special variable $urlq
.
State saving
When the special variable $url
is printed, its value
will contain the normal URL to re-invoke the script, but will also
reflect URL state variables (scrambled), as well as a handle to the
state-table variables. That's why you see gobbledy-gook like /+_wwYmelVlM+e4qwwwqFqc
in some URLs: Every time $url
is printed in the <SQL>
loop, all the <EXPORT>
variables are encoded in there.
This is the other magic function of $url
: not only is
it a URL back to the script, but it preserves state variables as well.
State restoration
When the user clicks one of our $url
links, our
<EXPORT>
variables are automatically restored. So
in our <details>
function, we know the correct patent
$id
to select for display. We also know the user's
original query, in $query
and $when
.
What type to use?
As a general rule, small variables that take up little space
and only have one value at a time are best saved as <EXPORT URL>
variables. All of our patent example exports fit this bill;
the user's queries are probably small, and so is the $id
:
while it has 10 different values, it only has 1 value per row
in the <SQL>
loop. URL
variables have the advantage
of speed: the state table does not need to be written.
Large variables, on the other hand, should be <EXPORT TABLE>
.
This costs a table write, but we can store very large data.
|