Extension:Flattr

MediaWiki extensions manual - list

Flattr Release status: beta
Implementation	Tag
Description	Adds a Flattr button to a page. Can use either pre created "things" or auto submitting mode
Author(s)	Christian RiesenTalk
Last version	0.7
MediaWiki	1.15
License	Public Domain
Download	See below
Example	Toreas Bottom of the page
Parameters $wgFlattrUserid, $wgFlattrForceUserid
Tags flattr
Hooks used ParserFirstCallInit
Check usage (experimental)

What can this extension do?

This allows you to add flattr buttons to your wiki. Flattr is a way to show appreciation by sharing money with everyone you think deserves it. Read more on the flattr page for details.

On flattr you can create a "thing" as they call it manually. In that case you only need to add the URL. The alternative is to use the autosubmit feature, by filling in some more fields, which will create your own thing upon the first flattr you get.

It's a tag, so you use it in the places you want to use it in and wont add a flattr tag to just every single page (and why would you want that, it wouldn't make much sense).

Warning: This is given as is, so not 100% sure it's secure, and if someone kills your wiki and internets with it, well, I warned you here. I'm using it on a closed wiki, where only a handful trust people can use it.

If you like this extension, you can flattr me by going here.

Usage

There are two ways, predefined and auto submitted flattrs

Predefined

This is the simplest. When you add it, you get a code from flattr that has the url you submitted in it. Just put it in the url attribute. The URL needs to be submitted to Flattr BEFORE you can use this! Or you will get an error!

Examples:

<flattr url="http://example.com/" />
<flattr url="http://toreas.com/Chapter_1" />
<flattr url="{{SERVER}}/{{FULLPAGENAMEE}}" />

Close the tags always with the /> at the end to make certain it works properly.

Autosubmitting

Here it needs some more from your setup side, but you won't need any input from flattr's page (except your user id). Once logged in, go to this page and find the line with this content: var flattr_uid = 'X'; where X is your user id.

Now you can use this by simply filling out all the required fields. Url and tags are optional. Url is for canonical urls while tags is simply some text with comma separation for each tag. If url is not given, the current displaying pages url is taken. All other fields are required.

X is your uid!

Categories can be (all in lowercase) text, images, video, audio, software or rest.

Minimal required example:

<flattr 
 uid="X"
 title="Toreas Chapter 1"
 description="Chapter 1 of Toreas: Crouching behind a fallen tree, Eric shivered slightly. It was cold, wet and night. He ..."
 category="text"
 language="en_GB"
 />

In this minimal example, the url will be taken from where the button is displayed automatically. Languages is required and a list of them can be found on this Flattr page. Take the short notifications, so it's en_GB for English. Be precise, case does matter!

Using all options example:

<flattr 
 uid="X"
 title="Toreas the open fantasy story"
 description="Toreas is a free and open fantasy story and new chapters are released every few days. You can share it with everybody as it is public domain"
 category="text"
 tags="Fantas, Novel, Free Fantasy Novel, Book, Fantasy Book, Fantasy Story, Story"
 language="en_GB"
 url="http://toreas.com/"
 button="compact"
 />

This last example creates a compact style button.

Download instructions

Please cut and paste the code found below and place it in $IP/extensions/Flattr/Flattr.php. Note: $IP stands for the root directory of your MediaWiki installation, the same directory that holds LocalSettings.php.

You can find a special version of this extension for MediaWiki 1.7.1 here.

Installation

To install this extension and add the following to LocalSettings.php:

require_once("$IP/extensions/Flattr/Flattr.php");

If you chose to use the optional settings, insert this instead of the above and read the instructions below for what these settings mean:

require_once("$IP/extensions/Flattr/Flattr.php");
$wgFlattrUserid = X;
$wgFlattrForceUserid = true;

Configuration parameters

Variable name	Default value	Description
$wgFlattrUserid	null	Sets the default or (with the switch below) locked user id. If this is set, no userid has to be given to the tag anymore, as it will take this one. If you do set one, and the $wgFlattrForceUserid is not set or false, this value will be overridden.
$wgFlattrForceUserid	false	If set to true, it will use the value of $wgFlattrUserid, no matter what the vlaue of uid is when the tag is called. Allows you to lock the uid effectively for your entire wiki.

Code

<?php
if( !defined( 'MEDIAWIKI' ) ) {
        echo( "This is an extension to the MediaWiki package and cannot be run standalone.\n" );
        die( -1 );
}
 
// Extension credits that will show up on Special:Version    
$wgExtensionCredits['parserhook'][] = array(
    'path'         => __FILE__,
        'name'         => 'Flattr',
        'version'      => '0.7',
        'author'       => 'Christian Riesen', 
        'url'          => 'http://www.mediawiki.org/wiki/Extension:Flattr',
        'description'  => 'Allows safe placements of flattr buttons on your wiki'
);
 
$wgHooks['ParserFirstCallInit'][] = 'wfFlattrSetup';
 
function wfFlattrSetup( &$parser ) {
        $parser->setHook( 'flattr', 'wfFlattrRender' );
       return true;
}
 
function wfFlattrRender( $input, $argsraw, $parser) {
        if (count($argsraw) <= 0) {
                return "<span title=\"No arguments present, needs at least one\"
                        style=\"color: red;\">flattr error 2</span>";
        }
 
        global $wgFlattrUserid, $wgFlattrForceUserid;
 
        // Check sanity on $wgFlattrForceUserid
        if (!isset($wgFlattrForceUserid) || $wgFlattrForceUserid != true || $wgFlattrForceUserid != false) {
                $wgFlattrForceUserid = false;
        }
 
        $args = array();
        foreach ($argsraw as $name => $value) {
                $value = $parser->replaceVariables($value);
                $args[$name] = htmlspecialchars($value);
        }
 
        // two version, auto discover and url set
        if (isset($args['url']) && !isset($args['uid'])) {
                // Doing it the direct way, needs to be added to the page by hand already!
                // if a UID is present then this is probably an autosubmit, but we NEED the url either way!
                return "<script type=\"text/javascript\">var flattr_url = '" 
                        . $args['url'] 
                        . "';</script><script src=\"http://api.flattr.com/button/load.js\" type=\"text/javascript\"></script>";
        } else {
                // Auto discovery way, need all required params
                $categories = array('text','images','video','audio','software','rest');
                $languages = array(     'sq_AL','be_BY','bg_BG','ca_ES',
                                                        'zh_CN','hr_HR','cs_CZ','da_DK',
                                                        'nl_NL','en_GB','et_EE','fi_FI',
                                                        'fr_FR','de_DE','el_GR','iw_IL',
                                                        'hi_IN','hu_HU','is_IS','in_ID',
                                                        'ga_IE','it_IT','ja_JP','ko_KR',
                                                        'lv_LV','lt_LT','mk_MK','ms_MY',
                                                        'mt_MT','no_NO','pl_PL','pt_PT',
                                                        'ro_RO','ru_RU','sr_RS','sk_SK',
                                                        'sl_SI','es_ES','sv_SE','th_TH',
                                                        'tr_TR','uk_UA','vi_VN');
                if (!isset($args['title']) || 
                        !isset($args['description']) ||
                        !isset($args['category']) || 
                        !isset($args['language']) || 
                        !in_array($args['category'], $categories)) {
                        return "<span title=\"Not all required attributes or category not correct\" 
                                style=\"color: red;\">flattr error 1</span>";
                }
 
                // if language is not correctly written, default to english
                if (!in_array($args['language'], $languages)) {
                        $args['language'] = 'en_GB';
                }
 
                $out = "";
                $out .= "<script type=\"text/javascript\">" . PHP_EOL;
                if (isset($wgFlattrUserid) && $wgFlattrUserid > 0 && (true === $wgFlattrForceUserid  || !isset($args['uid']))) {
                        $out .= "var flattr_uid = '" . $wgFlattrUserid . "';" . PHP_EOL;
                } else if (isset($args['uid'])) {
                        $out .= "var flattr_uid = '" . $args['uid'] . "';" . PHP_EOL;
                } else {
                        return "<span title=\"User id not present!\" 
                                style=\"color: red;\">flattr error 3</span>";
                }
 
                $out .= "var flattr_tle = '" . $args['title'] . "';" . PHP_EOL;
                $out .= "var flattr_dsc = '" . $args['description'] . "';" . PHP_EOL;
                $out .= "var flattr_cat = '" . $args['category'] . "';" . PHP_EOL;
                $out .= "var flattr_lng = '" . $args['language'] . "';" . PHP_EOL;
 
                // Tags in comma separated list!
                if (isset($args['tags'])) {
                        $out .= "var flattr_tag = '" . $args['tags'] . "';" . PHP_EOL;
                }
 
                // URL as canonical, in case the same content is on multiple pages
                if (isset($args['url'])) {
                        $out .= "var flattr_tag = '" . $args['url'] . "';" . PHP_EOL;
                }
 
                // Button style
                if (isset($args['button']) && 'compact' == $args['button']) {
                        $out .= "var flattr_btn = 'compact';" . PHP_EOL;
                }
 
                $out .= "</script>" . PHP_EOL;
                $out .= "<script src=\"http://api.flattr.com/button/load.js\" type=\"text/javascript\"></script>" . PHP_EOL;
                return $out;
        }
}