| Index: trunk/extensions/SemanticResultFormats/Ploticus/README |
| — | — | @@ -14,12 +14,22 @@ |
| 15 | 15 | * $srfgPloticusPath (REQUIRED) |
| 16 | 16 | - path to ploticus executable. (typically /usr/bin/ploticus or /usr/bin/pl) |
| 17 | 17 | |
| 18 | | - * $srfgGDFontPath (default: '') |
| 19 | | - - if you plan to use alternate TrueType fonts in your plot. |
| 20 | | - (e.g. '/usr/share/fonts/truetype/freefont:/usr/share/fonts/truetype/msttcorefonts') |
| | 18 | + * $srfgEnvSettings (default: '') |
| | 19 | + - Ploticus behavior can be further modified by setting environment variables. You can pass this env vars using this setting. |
| | 20 | + E.g. if you plan to use alternate TrueType fonts in your plot. |
| | 21 | + GDFONTPATH=/usr/share/fonts/truetype/freefont:/usr/share/fonts/truetype/msttcorefonts |
| | 22 | + |
| | 23 | + E.g. if you plan to use additional fonts in SWF files |
| | 24 | + SWF_FONTS_DIR=/usr/share/ming/fonts/ttf-dejavu/fdb/ |
| | 25 | + |
| | 26 | + E.g. set global ploticus config parameters with a config file. See http://ploticus.sourceforge.net/doc/config.html for details. |
| | 27 | + PLOTICUS_CONFIG=/etc/ploticus/ploticus.conf |
| | 28 | + |
| | 29 | + Remember, you can pass multiple environment variables, e.g. |
| | 30 | + GDFONTPATH=/usr/share/fonts/truetype/freefont PLOTICUS_CONFIG=/etc/ploticus/ploticus.conf |
| 21 | 31 | |
| 22 | 32 | * $srfgPloticusCacheAgeHours (default: 168 - 7 days) |
| 23 | | - - number of hours cached plot files are stored in the ploticus cache before they are forcibly purged regardless of liveupdating setting. |
| | 33 | + - number of hours cached plot files are stored in the ploticus cache before they are forcibly purged. |
| 24 | 34 | Set to 0 if you prefer to purge the cache manually. |
| 25 | 35 | This is required, especially with liveupdating plots, since changing query results will "orphan" plot cache files as the computed hash filename |
| 26 | 36 | will change even if the query definition itself is NOT changed. |
| — | — | @@ -35,7 +45,8 @@ |
| 36 | 46 | |
| 37 | 47 | * $wgEnableUploads (default: false - this is a MediaWiki setting) |
| 38 | 48 | - must be true. Be sure the upload directory has the proper permissions. If you wish to use SRF-Ploticus without enabling uploads, |
| 39 | | - you can create the 'ploticus' directory under the MW upload directory with permission 777. |
| | 49 | + you can manually create the 'ploticus' directory under the MW upload. Further, under the ploticus directory, subdirectories from 0 to f hex |
| | 50 | + (e.g. 0,1,2,3...9,a,b,c,d,e,f) should also be created, all with permission 777. |
| 40 | 51 | (see http://www.mediawiki.org/wiki/Manual:$wgUploadPath) |
| 41 | 52 | |
| 42 | 53 | == Configuration and Usage == |
| — | — | @@ -71,17 +82,18 @@ |
| 72 | 83 | Also turns showcsv on and bypasses the ploticus "cache". |
| 73 | 84 | |
| 74 | 85 | * liveupdating (bool/optional) |
| 75 | | - - 1 (default). When 1, will check if the query result has changed and regenerate the plot based |
| 76 | | - on the updatefrequency parameter. |
| 77 | | - Otherwise, when 0, the plot will only be generated once and stored in the ploticus "cache". |
| 78 | | - Its recommended to set showtimestamp to 1 when liveupdating is 0 or when updatefrequency > 0. |
| | 86 | + - 1 (default). When 1, will check if the query result has changed and regenerate the plot if so. |
| | 87 | + Otherwise, when 0, the plot will only be generated once and stored in the ploticus "cache", even |
| | 88 | + if the query results have changed. |
| 79 | 89 | |
| 80 | 90 | * updatefrequency (secs/optional) |
| 81 | | - - 60 (default). specifies how old a plot should be before its regenerated. Only valid when |
| 82 | | - liveupdating is 1. If you do not want to "cache" the plot, set updatefrequency to 0. |
| | 91 | + - 3600 (default). Specifies how old a plot should be before its regenerated even if the underlying |
| | 92 | + result data has not changed. |
| | 93 | + If you do not want to "cache" a plot, set updatefrequency to 0. |
| 83 | 94 | |
| 84 | 95 | * showtimestamp (bool/optional) |
| 85 | 96 | - 0 (default). Shows timestamp when the plot was last regenerated. |
| | 97 | + Its recommended to set showtimestamp to 1 when liveupdating is 0 or when updatefrequency > 0. |
| 86 | 98 | |
| 87 | 99 | * showrefresh (bool/optional) |
| 88 | 100 | - 0 (default). Shows a Refresh link to force refresh of the WHOLE article. |
| — | — | @@ -130,6 +142,8 @@ |
| 131 | 143 | * #sql |
| 132 | 144 | * #write |
| 133 | 145 | * #cat |
| | 146 | + |
| | 147 | + ======= USAGE NOTES ========= |
| 134 | 148 | |
| 135 | 149 | Overlaying and combining plots from multiple queries |
| 136 | 150 | ==================================================== |
| — | — | @@ -168,12 +182,22 @@ |
| 169 | 183 | where mydump is the name of the file passed to the drawdumpoutput parameter in the earlier SRF-Ploticus queries. |
| 170 | 184 | |
| 171 | 185 | |
| 172 | | -NOTE: |
| 173 | | -===== |
| | 186 | +Imagemaps: |
| | 187 | +========= |
| 174 | 188 | Client-side imagemaps are automatically generated by SRF-Ploticus if it detects the clickmap directive in |
| 175 | 189 | either prefab and script mode. |
| 176 | 190 | Typically, Imagemaps "links/labels" should be set to resolve to "Article URL/Article Name". |
| 177 | 191 | Note that imagemaps are only valid for the imageformats PNG, GIF and JPEG. |
| 178 | 192 | |
| | 193 | + |
| | 194 | + |
| | 195 | +CREDITS: |
| | 196 | +======= |
| | 197 | +SRF-Ploticus is only possible because of all the great work done |
| | 198 | +by Steve Grubb (stevegrubb@gmail.com) in creating Ploticus. |
| | 199 | +Ploticus is distributed via the GPL license (http://ploticus.sourceforge.net/doc/Copyright.html), |
| | 200 | +which is compatible with the GPL license under which Semantic Result Formats is distributed. |
| | 201 | + |
| | 202 | + |
| 179 | 203 | For up-to-date documentation and examples please refer to |
| 180 | 204 | http://semantic-mediawiki.org/wiki/Help:Ploticus_format |
| \ No newline at end of file |
| Index: trunk/extensions/SemanticResultFormats/Ploticus/SRF_Ploticus.php |
| — | — | @@ -27,13 +27,14 @@ |
| 28 | 28 | protected $m_ploticusmode = 'prefab'; |
| 29 | 29 | protected $m_debug = false; |
| 30 | 30 | protected $m_liveupdating = true; |
| 31 | | - protected $m_updatefrequency = 60; // by default, generate plot only once per minute |
| | 31 | + protected $m_updatefrequency = 3600; // by default, generate plot only once per hour |
| 32 | 32 | protected $m_showtimestamp = false; |
| 33 | 33 | protected $m_showrefresh = false; |
| 34 | 34 | protected $m_showimagelink = false; |
| 35 | 35 | protected $m_drawdumpoutput = ''; |
| 36 | 36 | protected $m_tblwidth = ''; |
| 37 | 37 | protected $m_tblheight = ''; |
| | 38 | + protected $m_params = array(); |
| 38 | 39 | |
| 39 | 40 | protected function readParameters($params, $outputmode) { |
| 40 | 41 | SMWResultPrinter::readParameters($params, $outputmode); |
| — | — | @@ -88,9 +89,10 @@ |
| 89 | 90 | } |
| 90 | 91 | |
| 91 | 92 | protected function getResultText($res, $outputmode) { |
| 92 | | - global $smwgIQRunningNumber, $wgUploadDirectory, $wgUploadPath, $wgScriptPath, $srfgPloticusPath, $srfgGDFontPath; |
| | 93 | + global $smwgIQRunningNumber, $wgUploadDirectory, $wgUploadPath, $wgScriptPath, $srfgPloticusPath, $srfgEnvSettings; |
| 93 | 94 | |
| 94 | 95 | $this->isHTML = true; |
| | 96 | + $this->outputmode = SMW_OUTPUT_HTML; |
| 95 | 97 | |
| 96 | 98 | // check parameters |
| 97 | 99 | if(empty($this->m_ploticusparams)) |
| — | — | @@ -120,14 +122,12 @@ |
| 121 | 123 | $sanitized_ploticusparams = preg_replace($searches, $replaces, $this->m_ploticusparams); |
| 122 | 124 | |
| 123 | 125 | // Create the ploticus data directory if it doesn't exist |
| 124 | | - // create sharded directory structure to stay under the file no limits of filesystem |
| | 126 | + // create sharded directory structure for data partitioning/scalability purposes |
| 125 | 127 | $ploticusDir = $wgUploadDirectory . '/ploticus/'; |
| 126 | 128 | if (!is_dir($ploticusDir)) { |
| 127 | 129 | mkdir($ploticusDir, 0777); |
| 128 | | - for ($idx=0; $idx < 10; $idx++) |
| 129 | | - mkdir($ploticusDir . $idx); |
| 130 | | - foreach(range('a','f') as $idx) |
| 131 | | - mkdir($ploticusDir . $idx); |
| | 130 | + for ($idx=0; $idx < 16; $idx++) |
| | 131 | + mkdir($ploticusDir . dechex($idx), 0777); |
| 132 | 132 | } |
| 133 | 133 | |
| 134 | 134 | // create result csv file that we pass on to ploticus |
| — | — | @@ -151,8 +151,7 @@ |
| 152 | 152 | |
| 153 | 153 | // we create a hash based on params and csv file. |
| 154 | 154 | // this is a great way to see if the params and/or the query result has changed |
| 155 | | - $hashname = hash('md5',$this->m_ploticusparams . $this->m_imageformat . $this->m_showcsv . $this->m_ploticusmode . |
| 156 | | - $this->m_liveupdating . $this->m_updatefrequency . $this->m_showtimestamp); |
| | 155 | + $hashname = hash('md5', implode(',',$this->m_params)); |
| 157 | 156 | if ($this->m_liveupdating) { |
| 158 | 157 | // only include contents of result csv in hash when liveupdating is on |
| 159 | 158 | // in this way, doing file_exists check against hash filename will fail when query result has changed |
| — | — | @@ -175,12 +174,12 @@ |
| 176 | 175 | $scriptFile = $ploticusDir . $hashname . '.plo'; |
| 177 | 176 | $scriptURL = $wgUploadPath . '/ploticus/' . $hashname . '.plo'; |
| 178 | 177 | |
| 179 | | - // get time graph was last generated and if liveupdating is on, check to see if the |
| | 178 | + // get time graph was last generated. Also check to see if the |
| 180 | 179 | // generated plot has expired per the updatefrequency and needs to be redrawn |
| 181 | | - if (file_exists($graphFile)) { |
| | 180 | + if (($this->m_updatefrequency > 0) && file_exists($graphFile)) { |
| 182 | 181 | $graphLastGenerated = filemtime($graphFile); |
| 183 | 182 | $expireTime = $graphLastGenerated + $this->m_updatefrequency; |
| 184 | | - if ($this->m_liveupdating && $expireTime < time()) { |
| | 183 | + if ( $expireTime < time()) { |
| 185 | 184 | @unlink($graphFile); |
| 186 | 185 | } |
| 187 | 186 | } |
| — | — | @@ -198,8 +197,8 @@ |
| 199 | 198 | $srfgPloticusPath . '</em></strong></p>'); |
| 200 | 199 | } |
| 201 | 200 | |
| 202 | | - // we set GDFONTPATH if specified |
| 203 | | - $commandline = empty($srfgGDFontPath) ? ' ' : 'GDFONTPATH=' . $srfgGDFontPath . ' '; |
| | 201 | + // we set $srfgEnvSettings if specified |
| | 202 | + $commandline = empty($srfgEnvSettings) ? ' ' : $srfgEnvSettings . ' '; |
| 204 | 203 | |
| 205 | 204 | if ($this->m_ploticusmode === 'script') { |
| 206 | 205 | // Script mode. Search for special strings in ploticusparam |