statusnet/README

   1 ____ StatusNet Plugin ____
   2 by Tobias Diekershoff
   3    http://diekershoff.homeunix.net/friendika/profile/tobias
   4    tobias.diekershoff(at)gmx.net
   5
   6 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   7 !! This addon is currently under development. If you have any problem       !!
   8 !! with it, please contact the Author.                                      !!
   9 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  10
  11 With this addon to Friendica you can give your user the possibility to post
  12 their public messages to any StatusNet instance (like identi.ca for example).
  13 The messages will be strapped their rich context and shortened to to the character
  14 limit of the StatusNet instance in question if necessary. If shortening of the
  15 message was performed a link will be added to the notice pointing to the
  16 original message on your server.
  17
  18 There is a similar plugin to forward public messages to Twitter: Twitter Plugin.
  19
  20 Online version of this document: http://ur1.ca/35mpb
  21
  22 ___ Requirements ___
  23
  24 Due to the distributed nature of the StatusNet network, each user who wishes to
  25 forward public messages to a StatusNet account has to get the OAuth credentials
  26 for themselves, which makes this addon a little bit more user unfriendly than
  27 the Twitter Plugin is. Nothing too geeky though!
  28
  29 The inclusion of a shorturl for the original posting in cases when the message
  30 was longer than the maximal allowed notice length requires it, that you have
  31 PHP5+ and curl on your server.
  32 Where to find
  33
  34 In the Friendica git repository /addon/statusnet/, this directory contains all
  35 required PHP files (including the Twitter OAuth library [1] by Abraham Williams,
  36 MIT licensed and the Slinky library [2] by Beau Lebens, BSD license), a CSS file
  37 for styling of the user configuration and an image to Sign in with StatusNet.
  38
  39 [1] https://github.com/abraham/twitteroauth
  40 [2] http://dentedreality.com.au/projects/slinky
  41
  42 ___ Configuration ___
  43
  44 __ Global Configuration __
  45
  46 If you have configured an admin account, you can configure this plugin from
  47 the admin panel. First activate it from the plugin section of the panel.
  48 Afterwards you will have a separate configuration page for the plugin, where
  49 you can provide a set of globally available OAuth credentials for different
  50 StatusNet pages which will be available for all users of your server.
  51
  52 If you don't use the admin panel, you can configure the relay using the
  53 .htconfig.php file of your friendica installation. To activate the relay add
  54 it's name to the list of activated addons.
  55
  56  $a->config['system']['addon'] = "statusnet, ..."
  57
  58 If you want to provide preconfigured StatusNet instances for your user add the
  59 credentials for them by adding
  60
  61 $a->config['statusnet']['sites'] = array (
  62    array ('sitename' => 'identi.ca', 'apiurl' => 'https://identi.ca/api/',
  63      'consumersecret' => 'OAuth Consumer Secret here', 'consumerkey' => 'OAuth
  64      Consumer Key here'),
  65    array ('sitename' => 'Some other Server', 'apiurl' =>
  66      'http://status.example.com/api/', 'consumersecret'  => 'OAuth
  67      Consumer Secret here', 'consumerkey' => 'OAuth Consumer Key here')
  68 );
  69
  70 to the config file.
  71
  72 Regardless of providing global OAuth credentials for your users or not, they
  73 can always add their own OAuth-Key and -Secret thus enable the relay for any
  74 StatusNet instance they may have an account at.
  75
  76 __ User Configuration __
  77
  78 When the addon is activated the user has to aquire three things in order to
  79 connect to the StatusNet account of choice.
  80  * the base URL for the StatusNet API, for identi.ca this is
  81    https://identi.ca/api/
  82  * OAuth Consumer key & secret
  83
  84 To get the OAuth Consumer key pair the user has to (a) ask her Friendica admin
  85 if a pair already exists or (b) has to register the Friendica server as a
  86 client application on the StatusNet server. This can be done from the account
  87 settings under "Connect -> Connections -> Register an OAuth client application
  88 -> Register a new application".
  89
  90 During the registration of the OAuth client remember the following:
  91  * there is no callback url
  92  * register a desktop client
  93  * with read & write access
  94  * the Source URL should be the URL of your Friendica server
  95
  96 After the required credentials for the application are stored in the
  97 configuration you have to actually connect your Friendica account with
  98 StatusNet. To do so follow the Sign in with StatusNet button, allow the access
  99 and copy the security code into the plugin configuration. Friendica will then
 100 try to acquire the final OAuth credentials from the API, if successful the
 101 plugin settings will allow you to select to post your public messages to your
 102 StatusNet account.