| 12 Vortex Coding Tips | |
Over time we've found some tips that make Vortex scripts easier to write and maintain:
Indent code of equal block depth equal amounts:
<A NAME=func PUBLIC>
Start
<IF $x eq 1>
<IF $y eq 2>
x is 1 and y is 2
<ELSE>
something else is true
</IF>
</IF>
</A>
|
This makes code more readable, and since Vortex strips leading spaces from the output, there's no wasted network bandwidth. (Some HTML generators are copious space wasters.)
Always declare a function's scope in any significant application. Because of back-compatibility rules, Vortex may change the implicit scope of a function from what you expect.
Don't make a function PUBLIC unless it has to be. You don't want accidental or intentional running of sensitive functions.
Every page in an app usually has common HTML for the top and bottom, so why not put that in a separate pair of functions? We usually call them look and /look for symmetry:
<A NAME=look PRIVATE>
<BODY BGCOLOR=white>
</A>
<A NAME=/look PRIVATE>
</BODY>
</A>
<A NAME=main PUBLIC>
<look>
This is main.
</look>
</A>
|
This way, a function can concentrate on its page's unique HTML without clutter. It also makes it easy to change the overall look and feel of the app.
Our examples in this tutorial sometimes omit these functions, but only for brevity.
It's often useful to write "macro" functions in Vortex, to encapsulate commonly used HTML sequences. For example:
<A NAME=fn>
<SPAN STYLE="color: #BOBOBO; font-family: Courier">
</A>
<A NAME=/fn>
</SPAN>
</A>
<A NAME=main>
We have <fn>many</fn> different <fn>font</fn> changes
in <fn>this</fn> example.
</A>
|
This not only cleans up the code and saves time, it makes it trivial to change the font look/feel later - only one function to change.
The <sum> function can be used to concatenate a list into a comma-separated-value string:
<$x = "A" "list" "of" "words">
<sum ",%s" "" $x>
<substr $ret 2 -1>
|
We use <substr> afterwards to strip off the leading two commas: one for our empty string (forces string cat), and one from the first "real" value of $x .
It's more efficient to append multiple values in a list, and sum the values all at once, than to sum multiple times:
<A NAME=func>
<$x = >
...
<$x = $x $One>
...
<$x = $x $Two>
...
<$x = $x $Three>
<sum "%s" "" $x>
<$x = $ret>
</A>
|
instead of:
<A NAME=func>
<$x = >
...
<sum "%s" "" $x $One>
<$x = $ret>
...
<sum "%s" "" $x $Two>
<$x = $ret>
...
<sum "%s" "" $x $Three>
<$x = $ret>
</A>
|
<sum> is faster than a math statement, and does not require a Texis database handle:
<sum "%s" "" $x $y>
is faster than:
<$ret = ('' + $x + $y)>
|
Not all functions in Vortex can accept full binary (varbyte) data; many stop at nul (a 0 byte). <fmt> is binary compatible; use it to print a varbyte field as-is in its entirety, no escapement and no truncation.
If you're doing a lot of the same <SQL> s, or a lot of Texis math statements (with parens), repeatedly in a loop, up the <SQLCACHE> value at the top of the script. This can make SQL run faster as more handles are used to cache statements.
Not only SELECT statements, but UPDATE and DELETE return rows in <SQL> . This can save a table read in some cases. For example, if we have a password table with user name, password, last login time, and permissions, we can verify the user name and password, update the last-login, and get the user's permissions, all in one statement:
<SQL MAX=1 "update passwd set LastLogin = 'now'
where User = $user and Pass = $pass">
</SQL>
|
Even though we didn't select anything, and only updated one column, we will get back the entire updated row. This saves us having to select it right after.
The flip side of the above example is that we might unintentionally set Vortex variables as the result of a DELETE or UPDATE . Unless you really want the returned data (as we did above), use NOVARS to make sure no vars are disturbed:
<SQL MAX=1 NOVARS "delete from tbl where id = $id"></SQL> |
Without the NOVARS , all the columns from our delete would set variables in Vortex as if it were a select.
Also, we used MAX=1 to ensure only one row was deleted, when we only want one row deleted. If $null was set and $id was empty, then without the MAX=1 , the entire table would be deleted! (The where clause went away due to $null .) MAX=1 is a "safety" here: at worst only 1 wrong row is deleted if $id is unset.
If your script suddenly does nothing, or the unexpected, look at the HTML source of the output in your browser, and check /usr/local/morph3/texis/vortex.log (or c:\morph3\texis\vortex.log under Windows) for errors. They can provide the exact location and details of what went wrong.
Vortex was designed for web sites; chances are it's got a feature that'll help you. Scan the manual and look at what those other functions do; maybe they'll come in handy. If you don't see a way to do something, ask tech support.
The <CAPTURE> function is like file redirection: it captures the output of a given block of Vortex code. This is useful for complex string construction: just print the values out in a <CAPTURE> block, instead of a long <strfmt> or concatenation statement.
The <EXEC> statement runs an arbitrary program. It's a quick and easy way to obtain data from another process into Vortex.
The <header> function can produce arbitrary headers for your script, such as redirects and cookies.
<SQL> statements sometimes take a while. Make sure that your users at least see the output you've produced up to that point while they wait, by calling <flush> just before any code that might take a while.
| Back: Other Module Options | Next: Common Vortex Mistakes |