More details about the HTML, HTTP, and runtime recalculation features in wikiCalc Alpha release 0.3:
The list of new features in wikiCalc version 0.3 includes some new functions and a runtime recalculation ability. This page describes those in more detail.

TEXT AND HTML AS A DATA TYPE

Before wikiCalc version 0.3 formulas could only give numeric results. In version 0.3 two other data formats were added to numeric: text and HTML. Normal cells with text data (when you type something that doesn't look like a number or start with "=" indicating a formula) are formatted pretty much as you type them in, with a few wiki-like markup commands added. (Explicit line breaks are preserved, there are "[" commands, shortcuts for bold and italic, etc.) If you refer to such a value in a formula (for example, "1+B7" where B7 contains text), the formula treats the value as zero (for a total of "1" in the example).

In version 0.3, there are some things you can do in formulas that accept text values and result in text values. If the final result of a formula is text, then the cell displays the result as text. You can also have text constants, typed as strings of characters within quotes. So, for example, the formula ="This is text" will display just the letters and spaces in the cell. There is also a function, wkcTEXT, that takes its arguments and concatenates them all together as text values. In the example, if B7 has the contents "This is text" (without the quotes) the formula =wkcTEXT("B7 contains: ",B7) will result in "B7 contains: This is text".

There is another data type called "HTML". HTML is like text, but when displayed in a cell it is treated as HTML and given to the browser to show as written. (The other way would be to use the text escape sequences of {{lt}}, etc., to create HTML code.) There is a function named wkcHTML that takes its arguments, concatenates them, and returns an HTML value. So, for example, if B8 contained "This is <b>bold</b>", the formula =wkcHTML(B8) would display as "This is bold".

The new wkcHTTP function, described next, can return any type of value: numeric, text, or HTML.

THE wkcHTTP FUNCTION

Another new function in wikiCalc version 0.3 is the wkcHTTP function. Its use is as follows:

wkcHTTP(url, timeout, errorvalue, method, arg1, arg2, ...)

An example would be:

wkcHTTP("http://www.domain.com/cgi-bin/WKCcallableUtilities.pl", 10, "Error using HTTP", "GET", "rand", 100)

All of the arguments are optional except for url. Spaces between operators and values are ignored and make it easier to type (especially in Multi-line Editing which will wrap the text to fit the display better than single line editing that just scrolls sidewards). Like all functions, the function name "wkcHTTP" is case-insensitive, so you can use WKCHTTP.

The url is the URL, including "http://", to which an HTTP request is made. The timeout is the number of seconds after which a timeout error is assumed. The default is 10 seconds. The errorvalue is the value to be returned by the function if there is an error (timeout, URL not found, etc.). For example, if it is the number 0, then a zero will be returned, but if it is a text message, the text message will be returned. The default is "". The method is either the text string "GET" or "POST". These tell the function which type of HTTP request to make. The default is "GET".

An HTTP request is made to the URL along with the values of the arguments that follow. Cell ranges are treated as if all the cells in the range were typed in one after another in order. The arguments are formatted in the request just like HTML form arguments in an HTTP request. The first one would look like this:

V1=Tvalue

where "V1" means it's the first value (subsequent ones would be "V2", "V3", etc.), "T" is one of: "N" for a numeric value, "T" for a text value, and "H" for an HTML value.

The URL should return a plain text response with a value in the form:

Tvalue

where "T" is "N" for a numeric value (followed by just numbers, with an optional minus sign and/or decimal point), "T" for text, "H" for HTML text, or "E" for an error value (with the value being text to describe the error).

THE WKCcallableUtilities.pl PROGRAM

Included with the wikiCalc version 0.3 release is the WKCcallableUtilities.pl program. This is a normal Perl program to be installed on a normal web server. It is designed to be used from wikiCalc through the wkcHTTP function.

When invoked, the first argument (V1) is the function to be performed. The functions are as follows:
echo
Echo back the other parameters as "1=text1, 2=text2..." for V2, V3, etc.
rand
Return a random integer from 1 to V2 inclusive (default V2 is 100)
regexget
Retrieve another web page and return a portion of it found with a regular expression as follows:
arg1="regexget", arg2=url, arg3=regex, arg4=returntype

The regular expression (for Perl) should include a capturing set of parenthesis and $1 will be returned as the value of the function
"returntype" is: N, T, or H for number, text, or HTML
A text error value will be returned if there is an error

Example: wkcHTTP("url-to-here", 10, "Error", "GET", "regexget", "http://finance.yahoo.com/q?s=msft", "Last Trade:.+?<b>(.+?)<","N")
graph
Return the HTML for a graph of values that follow with optional text labels after them. Numeric values will be graphed and text values will be used as the labels in the same order.
arg1="graph", arg2=totalHeightInPixels, arg3=totalWidthInPixels, arg4=color, arg5, etc.=value1, value2..., label1, label2...

The color is a CSS type of color specification, like "red" or "#FF0000".

Here is an example of a graph using the following function:

wkcHTTP("http://appropriate-url/WKCcallableUtilities.pl", 10, "Error", "GET", "graph", 100, 300, "green", 5, 10, 1, 3, "First", "Second", "Third", "Fourth")
5
 
10
 
1
 
3
 
FirstSecondThirdFourth

RUNTIME RECALCULATION USING THE WKCrecalc.pl PROGRAM

Note: The WKCrecalc.pl program has been removed from releases of wikiCalc after 0.91 (starting with 0.95). Runtime recalculation is now built-in using the "Live View" functionality which is documented in the help on the Preview tab of the product.

This material is only kept here for historical purposes and to support old versions.

Also included in the wikiCalc version 0.3 release is the WKCrecalc.pl Perl program. It is designed to be installed on a normal web server and executed. It reads the source data file for a wikiCalc page, does a recalculation, and then returns the rendered page to the browser. The recalculated value is not saved back. This capability is most useful with spreadsheets that have some values that change without editing, either through use of functions like wkcHTTP or set in the call to WKCrecalc.pl (see below). Usually pages are static and do not need this dynamic type of recalculation.

WKCrecalc.pl takes at least one argument, "url". This should be the URL of a text file containing the saved wikiCalc data file for a page. For security reasons, normally the data files are stored in a directory that is not accessible by a web server. You must put a copy in a location that can be accessed by HTTP. This can be done automatically when a page is published by setting the page Publish Option (on the Tools tab) of "Publish Source". If the "Publish Live" box is checked, and the "URL For Services" value is set for the Site, then the HTML for the page will be a redirect to URL For Services (which should be the location of WKCrecalc.pl) with a "url" argument of the source.

Other arguments to WKCrecalc.pl may have the names of cells (e.g., "B7") with values preceded by type. Type may be "T" for text, "N" for numbers, and "F" for formulas (no "=" preceding them). These values are written over any existing values in the cells before recalculation starts. For example, an argument of "B7=TThis%20is%text" would set cell B7 to "This is text".

Also, if there is an argument called "values", its value is a URL that when invoked with an HTTP GET returns a lists of values in the following form: One line for each value, each in the form of "coord:Tvalue", where coord is "A1", "B7", etc., and "T" is either "T" for text or "N" for a number. There may be only one "values" argument.

Note that WKCrecalc.pl makes reference to three other wikiCalc modules: WKCStrings.pm, WKCSheet.pm, and WKCSheetFunctions.pm. They should also be installed in the same directory as WKCrecalc.pl. Also, in Beta 0.91, runtime recalculation does not support references to cells on other pages (e.g., western!C22). The recalc support will be improved before 1.0.
 
wikiCalc Beta Test Home