added README files for the piwik, twitter and statusnet addon

3 files changed, 195 insertions, 0 deletions

diff --git a/addon/piwik/README b/addon/piwik/README
new file mode 100644
index 000000000..20b78b51e
--- /dev/null
+++ b/addon/piwik/README
@@ -0,0 +1,43 @@
+____ Piwik Plugin ____
+by Tobias Diekershoff
+   tobias.diekershoff(at)gmx.net
+
+This addon allows you to embed the code necessary for the FLOSS webanalytics
+tool piwik into the Friendika pages.
+
+Online version of this Document: http://ur1.ca/35m2x
+
+___ Requirements ___
+
+To use this plugin you need a "piwik":http://piwik.org installation.
+
+___ Where to find ___
+
+In the Friendika git repository @/addon/piwik/piwik.php@ and a CSS file for
+styling the opt-out notice.
+
+___ Configuration ___
+
+Open the .htconfig.php file and add "piwik" to the list of activated addons. 
+    $a->config['system']['addon'] = "piwik, ..."
+You have to add 3 more configuration variables for the addon:
+
+$a->config['piwik']['baseurl'] = 'example.com/piwik/';
+$a->config['piwik']['sideid'] = '1';
+$a->config['piwik']['optout'] = true;
+
+The *baseurl* points to your piwik installation. Use the absolute path,
+remember trailing slashes but ignore the protocol (http/s) part of the URL.
+Change the *sideid* parameter to whatever ID you want to use for tracking your
+Friendika installation. The *optout* parameter (true|false) defines whether or
+not a short notice about the utilization of piwik will be displayed on every
+page of your Friendika site (at the bottom of the page with some spacing to the
+other content). Part of the note is a link that allows the visitor to set an
+_opt-out_ cookie which will prevent visits from that user be tracked by piwik.
+
+Currently the optional notice states the following:
+
+    This website is tracked using the Piwik analytics tool. If you do not want
+    that your visits are logged this way you can set a cookie to prevent Piwik
+    from tracking further visits of the site (opt-out).
+
diff --git a/addon/statusnet/README b/addon/statusnet/README
new file mode 100644
index 000000000..8d5e27297
--- /dev/null
+++ b/addon/statusnet/README
@@ -0,0 +1,75 @@
+____ StatusNet Plugin ____
+by Tobias Diekershoff
+   tobias.diekershoff(at)gmx.net
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+!! This addon is currently in under development. If you have any problem    !!
+!! with it, please contact the Author.                                      !!
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+With this addon to Friendika you can give your user the possibility to post
+their public messages to any StatusNet instance like identi.ca for example. The
+messages will be strapped their rich context and shortened to to the character
+limit of the StatusNet instance in question if necessary. If shortening of the
+message was performed a link will be added to the notice pointing to the
+original message on your server.
+
+There is a similar plugin to forward public messages to Twitter Twitter Plugin.
+
+Online version of this document: http://ur1.ca/35mpb
+
+___ Requirements ___
+
+Due to the distributed nature of the StatusNet network, each user who wishes to
+forward public messages to a StatusNet account has get the OAuth credentials
+for themselves, which makes this addon a little bit more user unfriendly then
+the Twitter Plugin is. Nothing to geeky though!
+
+The inclusion of a shorturl for the original posting in cases when the message
+was longer then the maximal allowed notice length requires it, that you have
+PHP5+ and curl on your server.
+Where to find
+
+In the Friendika git repository /addon/statusnet/, this directory contains all
+required PHP files (including the Twitter OAuth library [1] by Abraham Williams,
+MIT licensed and the Slinky library [2] by Beau Lebens, BSD license), a CSS file
+for styling of the user configuration and an image to Sign in with StatusNet.
+
+[1] https://github.com/abraham/twitteroauth
+[2] http://dentedreality.com.au/projects/slinky
+
+___ Configuration ___
+
+__ Global Configuration __
+
+To activate this addon add statusnet to the list of active addons in your
+.htconfig.php file 
+    $a->config['system']['addon'] = "statusnet, ...".
+
+__ User Configuration __
+
+When the addon is activated the user has to aquire three things in order to
+connect to the StatusNet account of choice.
+ * the base URL for the StatusNet API, for identi.ca this is
+   https://identi.ca/api/
+ * OAuth Consumer key & secret
+
+To get the OAuth Consumer key pair the user has to (a) ask her Friendika admin
+if a pair already exists or (b) has to register the Friendika server as a
+client application on the StatusNet server. This can be done from the account
+settings under "Connect -> Connections -> Register an OAuth client application
+-> Register new application".
+
+During the registration of the OAuth client remember the following:
+ * there is no callback url
+ * register a desktop client
+ * with read & write access
+ * the Source URL should be the URL of your Friendika server
+
+After the required credentials for the application are stored in the
+configuration you have to actually connect your Friendika account with
+StatusNet. To do so follow the Sign in with StatusNet button, allow the access
+and copy the security code into the addon configuration. Friendika will then
+try to acquire the final OAuth credentials from the API, if successful the
+addon settings will allow you to select to post your public messages to your
+StatusNet account.
diff --git a/addon/twitter/README b/addon/twitter/README
new file mode 100644
index 000000000..a49fa5cda
--- /dev/null
+++ b/addon/twitter/README
@@ -0,0 +1,77 @@
+____ Twitter Plugin ____
+By Tobias Diekershoff
+   tobias.diekershoff(at)gmx.net
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+!!   This addon is currently in under development. If you have any problem  !!
+!!   with it, please contact the Author.                                    !!
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+With this addon to Friendika you can give your user the possibility to post
+their *public* messages to Twitter. The messages will be strapped their rich
+context and shortened to 140 characters length if necessary. If shortening of
+the message was performed a link will be added to the Tweet pointing to the
+original message on your server.
+
+There is a similar addon for forwarding public messages to
+"StatusNet":http://status.net [[StatusNet Plugin]].
+
+Online version of this document: http://ur1.ca/35mml
+
+___ Requirements ___
+
+To use this plugin you have to register your Friendika instance as an
+_client application_ for Twitter with _read and write_ access, we do not intend
+to use Twitter for login. The registration can be done at twitter.com/apps
+and you need to have a Twitter account to do so.
+
+After you registered the application you get an OAuth consumer key / secret
+pair that identifies your app, you will need them for configuration.
+
+The inclusion of a shorturl for the original posting in cases when the
+message was longer then 140 characters requires it, that you have *PHP5+* and
+*curl* on your server.
+
+___ Where to find ___
+
+In the Friendika git repository /addon/twitter/, this directory contains
+all required PHP files (including the Twitter OAuth library [1] by Abraham
+Williams, MIT licensed and the Slinky library [2] by Beau Lebens, BSD license),
+a CSS file for styling of the user configuration and an image to _Sign in with
+Twitter_.
+
+[1] https://github.com/abraham/twitteroauth
+[2] http://dentedreality.com.au/projects/slinky/
+
+___ Configuration ___
+
+__ Global Configuration __
+
+To activate this addon add @twitter@ to the list of active addons in your
+.htconfig.php file 
+    $a->config['system']['addon'] = "twitter, ..."
+Afterwards you need to add your OAuth consumer key / secret pair to it by
+adding the following to lines
+
+$a->config['twitter']['consumerkey'] = 'your consumer KEY here';
+$a->config['twitter']['consumersecret'] = 'your consumer SECRET here';
+
+When this is done your user can now configure their Twitter connection at
+"Settings -> Addon Settings" and enable the forwarding of their *public*
+messages to Twitter.
+
+__ User Configuration __
+
+When the OAuth consumer informations are correctly placed into the
+configuration file and a user visits the "Addon Settings" page they can now
+connect to Twitter. To do so one has to follow the _Sign in with Twitter_
+button (the page will be opened in a new browser window/tab) and get a PIN from
+Twitter. This PIN has to be entered on the settings page. After submitting the
+PIN the plugin will get OAuth credentials identifying this user from the
+Friendika account.
+
+If this first step was successful the Twitter configuration will be changed
+on the "Addon Settings" page displaying two check boxes. One to enable/disable
+the forwarding of *all public* postings to Twitter and one to clear the
+personal configuration from the Twitter credentials.
+