From: <de...@de...> - 2012-04-05 05:01:58
|
Author: PeterThoeny Date: 2012-04-05 00:01:50 -0500 (Thu, 05 Apr 2012) New Revision: 22783 Trac url: http://develop.twiki.org/trac/changeset/22783 Modified: twiki/branches/TWikiRelease05x01/SpreadSheetPlugin/data/TWiki/SpreadSheetPlugin.txt Log: Item6866: Use register tag handler for spreadsheet calculations for proper inside-out, left-to-right eval order - updating docs Modified: twiki/branches/TWikiRelease05x01/SpreadSheetPlugin/data/TWiki/SpreadSheetPlugin.txt =================================================================== --- twiki/branches/TWikiRelease05x01/SpreadSheetPlugin/data/TWiki/SpreadSheetPlugin.txt 2012-04-05 05:01:30 UTC (rev 22782) +++ twiki/branches/TWikiRelease05x01/SpreadSheetPlugin/data/TWiki/SpreadSheetPlugin.txt 2012-04-05 05:01:50 UTC (rev 22783) @@ -1,4 +1,4 @@ -%META:TOPICINFO{author="TWikiContributor" date="1326527407" format="1.1" version="$Rev$"}% +%META:TOPICINFO{author="TWikiContributor" date="1333601974" format="1.1" version="$Rev$"}% ---+!! TWiki Spreadsheet Plugin <!-- Contributions to this plugin are appreciated. Please update the plugin page at @@ -7,7 +7,7 @@ If you are a TWiki contributor please update the plugin in the SVN repository. --> -This plugin adds spreadsheet capabilities to TWiki topics. Formulae like ==%<nop>CALC{"$INT(7/3)"}%== are evaluated at page view time. They can be placed in table cells and outside of tables. In other words, this plugin provides general formula evaluation capability, not just classic spreadsheet functions. +This plugin adds spreadsheet capabilities to TWiki topics. Functions such as ==%<nop>CALC{"$INT(7/3)"}%== are evaluated at page view time. They can be placed in table cells and outside of tables. In other words, this plugin provides general function evaluation capability, not just classic spreadsheet functions. <table><tr><td valign="top"> __Example:__ @@ -26,9 +26,9 @@ <form name="interactive" action="%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%" method="get"> <noautolink> Formula: -<code>%<nop>CALC{"</code><input type="text" name="formula" size="40" value="%URLPARAM{ "formula" default="$PROPERSPACE(%WIKINAME%)" encode="entity" }%" class="twikiInputField" /><code>"}%</code> +<code>%<nop>CALC{"</code><input type="text" name="func" size="40" value="%URLPARAM{ "func" default="$PROPERSPACE(%WIKINAME%)" encode="entity" }%" class="twikiInputField" /><code>"}%</code> <input type="submit" value="Evaluate" class="twikiSubmit" /><br /> -Result: %CALC{%URLPARAM{ "formula" default="$PROPERSPACE(%WIKINAME%)" }%}% +Result: %CALC{%URLPARAM{ "func" default="$PROPERSPACE(%WIKINAME%)" }%}% </noautolink> </form> </td></tr><tr><td colspan="3"> @@ -39,7 +39,7 @@ ---++ Syntax Rules -The action of this plugin is triggered by the ==%<nop>CALC{"..."}%== variable, which gets rendered according to the built-in function(s) found between the quotes. +This plugin handles the ==%<nop>CALC{"..."}%== and ==%<nop>CALCULATE{"..."}%== variables. Built-in functions found between the quotes are evaluated as follows: * Built-in function are of format ==$FUNCNAME(parameter)== * Functions may be nested, such as ==%<nop>CALC{"$SUM( R2:C$COLUMN(0)..R$ROW(-1):C$COLUMN(0) )"}%== @@ -51,11 +51,19 @@ | ==R2:C1== | ==R2:C2== | ==R2:C3== | ==R2:C4== | * A table cell range is defined by two cell addresses separated by ==".."==, e.g. "row 1 through 20, column 3" is: ==R1:C3..R20:C3== * Lists can refer to values and/or table cell ranges, such as ==%<nop>CALC{"$SUM( 3, 5, $T(R1:C7), R1:C11..R1:C15 )"}%== - * Formulae can only reference cells in the current or preceeding row of the current table; they may not reference cells below the current table row - * Formulae can also be placed outside of tables; they can reference cells in the preceeding table - * Formulae can be placed in a FormattedSearch, but the CALC needs to be escaped. Learn how to [[#CalcInFormattedSearch][use a CALC in a formatted search]] + * Functions can only reference cells in the current or preceeding row of the current table; they may not reference cells below the current table row + * Functions can also be placed outside of tables; they can reference cells in the preceeding table + * Functions can be placed in a FormattedSearch, but the CALC needs to be escaped. Learn how to [[#CalcInFormattedSearch][use a CALC in a formatted search]] * Plain text can be added, such as ==%<nop>CALC{"Total: $SUM($ABOVE()) kg"}%== +---++ Use CALC or CALCULATE + +%ICON{table}% *Use =%<nop>CALC{"..."}%= _in_ table cells:* +%BR% The CALC variable handles all functions, but it gets handled with delay compared to other %SYSTEMWEB%.TWikiVariables: It gets executed after internal variables and plugin variables that use the register tag handler. You may get unexpected results if you nest CALC inside other variables (such as =%<nop>INCLUDE{%<nop>CALC{...}%}%=) because it does not get evaluated inside-out & left-to-right like ordinary TWiki variables. + +%ICON{indexlist}% *Use =%<nop>CALCULATE{"..."}%= _outside_ tables:* +%BR% The CALCULATE variable is handled inside-out & left-to-right like ordinary TWiki variables, but it does __not__ support functions that refer to table cells, such as =$LEFT()= or =$T()=. + ---++ Built-in Functions Conventions for Syntax: @@ -817,7 +825,7 @@ * Set <nop>SPREADSHEETPLUGIN_SKIPINCLUDE = 0 -This setting tells the !SpreadSheetPlugin to process the CALCs in the included page, e.g. it will not delay the evaluation of the formulae. +This setting tells the !SpreadSheetPlugin to process the CALCs in the included page, e.g. it will not delay the evaluation of the functions. ---++ Bug Tracking Example @@ -863,24 +871,32 @@ ---++ Plugin Installation Instructions -__Note:__ You do not need to install anything on the browser to use this plugin. Below installation instructions are for the administrator who needs to install this plugin on the TWiki server. +__Note:__ This plugin is pre-installed. TWiki administrators can upgrade it as needed on the TWiki server. - * Download the ZIP file from the <nop>%TOPIC% home - * Unzip ==SpreadSheetPlugin.zip== in your twiki installation directory. Content: - | *File:* | *Description:* | - | ==data/TWiki/%TOPIC%.txt== | Plugin topic | - | ==data/TWiki/%TOPIC%.txt,v== | Plugin topic repository | - | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module | - * TWiki 4 and up: Visit =configure= in your TWiki installation, and enable the plugin in the {Plugins} section. - * Test if the "Total" in the first table in this topic is correct. + * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section. + * Or, follow these __manual installation__ steps: + * Download the ZIP file from the Plugins home (see below). + * Unzip ==SpreadSheetPlugin.zip== in your twiki installation directory. Content: + | *File:* | *Description:* | + | ==data/TWiki/%TOPIC%.txt== | Plugin topic | + | ==data/TWiki/VarCALC.txt== | Documentation of the CALC variable | + | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module | + | ==lib/TWiki/Plugins/%TOPIC%/Calc.pm== | Plugin core module | + * Set the ownership of the extracted directories and files to the webserver user. + + * Plugin __configuration and testing__: + * Run the [[%SCRIPTURL{configure}%][configure]] script and enable the plugin in the __Plugins__ section. + * Test if the installation was successful: See example above. + ---++ Plugin Info | Plugin Author: | TWiki:Main.PeterThoeny | | Copyright: | © 2001-2012 Peter Thoeny, [[http://www.twiki.net/][Twiki, Inc.]]<br /> © 2008-2012 TWiki:TWiki.TWikiContributor | | License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) | -| Plugin Version: | 2012-01-13 | +| Plugin Version: | 2012-04-04 | | Change History: | <!-- specify latest version first --> | +| 2012-04-04: | TWikibug:Item6866: Added CALCULATE variable using register tag handler to support proper inside-out, left-to-right eval order like ordinary TWiki variables | | 2012-01-13: | TWikibug:Item6804: Added $FLOOR() and $CEILING() | | 2011-09-07: | TWikibug:Item6803: Fix for EVAL function bug with zeroes after decimal point | | 2011-07-09: | TWikibug:Item6725: Change global package variables from "use vars" to "our" | |