Extension:EasyTimeline/installation

From MediaWiki.org
Jump to: navigation, search

This section deals with issues on how to activate EasyTimeline in other MediaWiki installations.

EasyTimeline is an extension to the MediaWiki software. However you need to do a few things in order to activate it.

Note: when you run MediaWiki on another platform than Linux, the following may not apply or be incomplete.

Download Ploticus[edit | edit source]

EasyTimeline uses the open source program Ploticus, which is not included in the MediaWiki installation. Download the proper version for your OS here.

If you can't put the Ploticus executable pl in /usr/local/bin, or any of the other suggested locations, just make sure it's executable and put the appropriate location in LocalSettings.php ("how" explained below).

Important: Ploticus 2.30 has (Oct 29, 2004) a critical bug. Upgrade to 2.32 2.33.

Download PHP/PERL scripts[edit | edit source]

EasyTimeline.pl is the actual plug-in, written in perl.

Timeline.php is the MediaWiki php wrapper that invokes the perl script with proper arguments, and feeds generated image and image map (if applicable) to the html output.

Follow these links to get the latest revision of both files: php file, perl file. php internationalization file.

...or if you have shell access, go to your extensions directory, and type ...

svn co http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/timeline/

Do not use the EasyTimeline.pl script, or its compiled version, from the authors support page. These are meant for offline usage (= outside WikiMedia).

Important: Newest Ploticus (from 2.31) has changed behaviour. You'll need to patch the php file, see Charts not clickable below.

Install fonts[edit | edit source]

This might be necessary, especially if your system isn't configured with X. Download a font package that contains FreeSans.ttf, for example, from RPMbone. -Broken Link

Or, if you are on Ubuntu with shell access, you can simply do

sudo aptitude install ttf-freefont

Install these (dependencies can be ignored) files, note the installation path, and copy that path and include it somewhere in LocalSettings.php (or patch the extension, in the renderTimeLine extension):

 putenv("GDFONTPATH=[...]"); // where [...] is the font path copied from above.

Configure MediaWiki[edit | edit source]

Settings[edit | edit source]

Add the following to you LocalSettings.php file:

require_once "$IP/extensions/timeline/Timeline.php"; // Add EasyTimeline extension
$fontFile = 'ascii'; // Use the internal Ploticus font

On RHEL/CentOS, for instance, /usr/bin/pl is the ploticus executable. If the ploticus location on your system does not match the defaults listed at the top of extensions/timeline/Timeline.php, you will need to explicitly set the paths, e.g.

require_once "$IP/extensions/timeline/Timeline.php"; // Add EasyTimeline extension
$fontFile = 'ascii'; // Use the internal Ploticus font
$wgTimelineSettings->ploticusCommand = "/usr/bin/pl"; // alternate location of ploticus, depending on OS

Alternatively you may create symlinks to the alternate location.

Note Note: The extension's default settings for ploticus and perl:

$wgTimelineSettings->ploticusCommand = "/usr/bin/ploticus";
$wgTimelineSettings->perlCommand = "/usr/bin/perl";

Script location[edit | edit source]

EasyTimeline.pl needs to be installed in $IP/extensions/timeline/EasyTimeline.pl (or make a symlink, of course)

Image directory[edit | edit source]

Create a directory for timeline images and ensure it's read/writable by your web server's user. For example if your web server user is "www-data", you would do:

cd (wiki root directory)
mkdir images/timeline
chown www-data images/timeline

Known problems[edit | edit source]

Command Variables are Non-Transclusion[edit | edit source]

This problem occurs when an editor attempts to add certain words inside of the timeline which may be commands under document. One such example word instance would be for the word construction; when used in a timeline as a dated entry, an error type occurs, rendering the word construction as a command and not a clickable link.

Charts not clickable[edit | edit source]

Ploticus 2.30 is buggy and does never produce a HTML map file, so no clickable images.

Ploticus 2.31 has fixed this but has changed behaviour: map file is now written to stdout instead of file :(

So you need to apply the patch described below or download Timeline.php 1.7 with patch applied here (broken Link!).

Patch by Twhite

[twhite@home]$ diff EasyTimeline.php Timeline-1.7.php
48,58d47
<                 else {
<                    $lines = split("\n", $ret);
<                    $handle = fopen($fname.".map", "w");
<                    for($i=0;$i < count($lines);$i++) {
<                       // check if string is area part
<                       if(strpos($lines[$i], "area shape") == 1) {
<                          fwrite($handle, $lines[$i] . "\n");
<                       }
<                    }
<                    fclose($handle);
<                 }

Note: This bug has been resolved in Ploticus 2.32

If that still does not resolve problems you may want to simply change line 176 of EasyTimeline.pl to:

  $MapPNG = $true ; # switched when link or hint found

since it doesn't seem to apply when wikistyled links are just used on text tags and it can be annoying to figure that out.

Windows only: Timeline error: Executable not found. Command line was:[edit | edit source]

If you are getting an error something like

Timeline error: Executable not found. Command line was:
"C:/Perl/bin/perl.exe" "C:/Apache2/htdocs/wiki/extensions/timeline/EasyTimeline.pl"
-i "C:/Apache2/htdocs/wiki/images/timeline/bebc64ea32049f9fe1f251640849a318"
-m -P "C:/pl232win32/bin/pl.exe"
-T "C:/Apache2/htdocs/wiki/images/tmp" -A "/wiki/$1"

try going into your php file (usually at Timeline.php or EasyTimeline.php) and changing

$ret = `{$cmdline}`; 

into

$ret = `"{$cmdline}"`;

You may also have modified the extension directory name, which will result in the same error even with the above fix. Set timelineFile to something like this in LocalSettings.php:

$wgTimelineSettings->timelineFile = "$IP\\extensions\\EasyTimeline\\EasyTimeline.pl";

Windows only: set path to perl[edit | edit source]

When your mediawiki installation runs on Windows you will need to update Timeline.php. Set $wgTimelineSettings->perlCommand to the path to perl.exe. The default is /usr/bin/perl, this needs to be changed for Windows.

No texts displayed[edit | edit source]

The newest release of EasyTimeline contains a quick fix for unicode support. This requires free font FreeSans.ttf. If easytimeline.pl mentions FreeSans.ttf you have this recent version and maybe do not have that font in a directory where Ploticus looks. You might try to find where that is on your system: see Ploticus docs online, or revert to previous EasyTimeline.pl 1.13 at http://wikipedia.cvs.sourceforge.net/wikipedia/extensions/timeline/EasyTimeline.pl.

If you want a different font with reasonable code point coverage, try DejaVu, either Sans Condensed or Sans Extra-Light depending on your preferences.

Tweaking GDFONTPATH[edit | edit source]

On a Ubuntu system with ttf-freefont installed, the following change to Timeline.php will set GDFONTPATH as required by Ploticus to render text with FreeSans.ttf.

$cmdline = 'GDFONTPATH=/usr/share/fonts/truetype/freefont' . ' ' .
           wfEscapeShellArg( $wgTimelineSettings->perlCommand, $IP . "/extensions/timeline/EasyTimeline.pl" ) .
  " -i " . wfEscapeShellArg( $fname ) . " -m -P " . wfEscapeShellArg( $wgTimelineSettings->ploticusCommand ) .
  " -T " . wfEscapeShellArg( $wgTmpDirectory ) . " -A " . wfEscapeShellArg( $wgArticlePath );

... or simply add "putenv("GDFONTPATH=/usr/share/fonts/truetype/freefont");" to your LocalSettings.php.