| Index: trunk/extensions/SemanticResultFormats/Ploticus/README |
| — | — | @@ -1,6 +1,10 @@ |
| 2 | 2 | == Overview == |
| 3 | 3 | SRF-Ploticus is a query printer for Semantic MediaWiki that uses |
| 4 | 4 | Ploticus to create plots, charts and graphics out of query results. |
| | 5 | +Ploticus visualizations are highly configurable and the user can even develop |
| | 6 | +custom visualizations using the Ploticus scripts. |
| | 7 | +Note however that SRF-Ploticus no longer allows Ploticus scripts to be embedded in ask queries for security reasons. |
| | 8 | +If the user wants to develop custom visualizations, the custom scripts should be deployed in the Ploticus prefab directory. |
| 5 | 9 | |
| 6 | 10 | == Installation == |
| 7 | 11 | The following should be installed and running. |
| — | — | @@ -55,16 +59,10 @@ |
| 56 | 60 | == Configuration and Usage == |
| 57 | 61 | |
| 58 | 62 | The SRF-ploticus Result Format has the following parameters: |
| 59 | | - |
| 60 | | - * ploticusmode (enum/optional) |
| 61 | | - - set to 'prefab' (default) or 'script' |
| 62 | 63 | |
| 63 | 64 | * ploticusparams (string/required) |
| 64 | | - - in prefab mode, this should be set to prefab cmdline parameters. |
| | 65 | + - this should be set to prefab cmdline parameters. See SPECIFYING PLOTICUSPARAMS below. |
| 65 | 66 | Line endings can be used to split the prefab commandline for readability. |
| 66 | | - |
| 67 | | - In script mode, set to a ploticus script. Line endings to separate directives |
| 68 | | - can and should be used in script mode. Otherwise, the ploticus script parser will fail. |
| 69 | 67 | |
| 70 | 68 | * imageformat (enum/optional) |
| 71 | 69 | - png (default), gif, jpeg, svg, svgz, swf, eps, ps, drawdump and drawdumpa (drawdump append). |
| — | — | @@ -90,7 +88,7 @@ |
| 91 | 89 | (http://ploticus.sourceforge.net/doc/prefab_stdparms.html#legend) |
| 92 | 90 | |
| 93 | 91 | * debug (bool/optional) |
| 94 | | - - 0 (default). When 1, displays ploticus prefab cmdline or script used to generate plot. |
| | 92 | + - 0 (default). When 1, displays ploticus prefab cmdline used to generate plot. |
| 95 | 93 | It also invokes ploticus itself in debug mode and creates a link to the debug file. |
| 96 | 94 | Also turns showcsv on and bypasses the ploticus "cache". |
| 97 | 95 | |
| — | — | @@ -135,12 +133,11 @@ |
| 136 | 134 | |
| 137 | 135 | * drawdumpoutput (string/optional) |
| 138 | 136 | - this parameter is only processed in prefab mode when imageformat is set to drawdump or drawdumpa. |
| 139 | | - (In script mode, use the %WORKINGDIR% keyword in your script when producing drawdumps) |
| 140 | 137 | Specifies the filename to which the drawdump output will be stored in the ploticus cache directory. |
| 141 | 138 | |
| 142 | | -PREFAB MODE |
| 143 | | -=========== |
| 144 | | -In prefab mode, ploticusparams expects commandline parameters that one would normally use when |
| | 139 | +SPECIFYING PLOTICUSPARAMS |
| | 140 | +========================= |
| | 141 | +ploticusparams expects commandline parameters that one would normally use when |
| 145 | 142 | invoking stand-alone ploticus in prefab mode. |
| 146 | 143 | |
| 147 | 144 | However, the following Ploticus commandline prefab parameters should NOT be specified: |
| — | — | @@ -148,23 +145,8 @@ |
| 149 | 146 | * output - automatically generated by the extension |
| 150 | 147 | * format (e.g. -png, -gif, etc.) - use the SRF-ploticus imageformat parameter. |
| 151 | 148 | * debug - use the SRF-Ploticus debug parameter instead |
| 152 | | - |
| 153 | | -SCRIPT MODE |
| 154 | | -=========== |
| 155 | | -In script mode, ploticusparams should be set to a ploticus script. |
| 156 | 149 | |
| 157 | | -Two special keywords can be used in the script body (case-sensitive): |
| 158 | | - * %DATAFILE.CSV% - replaced with fully qualified path to result CSV file generated by the inline query |
| 159 | | - * %WORKINGDIR% - replaced with SRF-ploticus cache directory. This is useful when creating drawdump/drawdumpa |
| 160 | | - files in script mode. |
| 161 | 150 | |
| 162 | | -For security reasons, the passed script is also "sanitized" and the following ploticus directives are disabled: |
| 163 | | - * #include |
| 164 | | - * #shell |
| 165 | | - * #sql |
| 166 | | - * #write |
| 167 | | - * #cat |
| 168 | | - |
| 169 | 151 | ======= USAGE NOTES ========= |
| 170 | 152 | |
| 171 | 153 | Overlaying and combining plots from multiple queries |
| — | — | @@ -211,6 +193,10 @@ |
| 212 | 194 | Typically, imagemaps "links/labels" should be set to resolve to "Article URL/Article Name". |
| 213 | 195 | Note that imagemaps are only valid for PNG, GIF, JPEG and SVG. |
| 214 | 196 | |
| | 197 | +HISTORY: |
| | 198 | +======= |
| | 199 | +2011-02-22 Removed script mode and added escapeshellcmd to ploticus cmdline call to close security vulnerability. If user needs flexibility of script mode, the script will have to be developed and deployed into the prefabs script as a custom prefab. |
| | 200 | + |
| 215 | 201 | CREDITS: |
| 216 | 202 | ======= |
| 217 | 203 | SRF-Ploticus is only possible because of all the great work done |