statusnet/README.md

   1 StatusNet Connector
   2 ===================
   3 Main authors Tobias Diekershoff and Michael Vogel.
   4
   5 With this addon to Friendica you can give your user the possibility to post
   6 their public messages to any StatusNet instance.  The messages will be strapped
   7 their rich context and shortened to to the character limit of the StatusNet
   8 instance in question if necessary. If shortening of the message was performed a
   9 link will be added to the notice pointing to the original message on your
  10 server.
  11
  12 Requirements
  13 ------------
  14
  15 Due to the distributed nature of the StatusNet network, each user who wishes to
  16 forward public messages to a StatusNet account has to get the OAuth credentials
  17 for themselves, which makes this addon a little bit more user unfriendly than
  18 the Twitter Plugin is. Nothing too geeky though!
  19
  20 The inclusion of a shorturl for the original posting in cases when the message
  21 was longer than the maximal allowed notice length requires it, that you have
  22 PHP5+ and curl on your server.
  23 Where to find
  24
  25 In the Friendica git repository /addon/statusnet/, this directory contains all
  26 required PHP files (including the [Twitter OAuth library] [1] by Abraham Williams,
  27 MIT licensed and the [Slinky library] [2] by Beau Lebens, BSD license), a CSS file
  28 for styling of the user configuration and an image to Sign in with StatusNet.
  29
  30 [1]:https://github.com/abraham/twitteroauth
  31 [2]:http://dentedreality.com.au/projects/slinky
  32
  33 Configuration
  34 =============
  35
  36 Global Configuration
  37 --------------------
  38
  39 **If you have configured an admin account, you can configure this plugin from
  40 the admin panel.** First activate it from the plugin section of the panel.
  41 Afterwards you will have a separate configuration page for the plugin, where
  42 you can provide a set of globally available OAuth credentials for different
  43 StatusNet pages which will be available for all users of your server.
  44
  45 If you don't use the admin panel, you can configure the relay using the
  46 .htconfig.php file of your friendica installation. To activate the relay add
  47 it's name to the list of activated addons.
  48
  49     $a->config['system']['addon'] = "statusnet, ..."
  50
  51 If you want to provide preconfigured StatusNet instances for your user add the
  52 credentials for them by adding
  53
  54     $a->config['statusnet']['sites'] = array (
  55        array ('sitename' => 'identi.ca', 'apiurl' => 'https://identi.ca/api/',
  56          'consumersecret' => 'OAuth Consumer Secret here', 'consumerkey' => 'OAuth
  57          Consumer Key here'),
  58        array ('sitename' => 'Some other Server', 'apiurl' =>
  59          'http://status.example.com/api/', 'consumersecret'  => 'OAuth
  60          Consumer Secret here', 'consumerkey' => 'OAuth Consumer Key here')
  61     );
  62
  63 to the config file.
  64
  65 Regardless of providing global OAuth credentials for your users or not, they
  66 can always add their own OAuth-Key and -Secret thus enable the relay for any
  67 StatusNet instance they may have an account at.
  68
  69 User Configuration
  70 ------------------
  71
  72 When the addon is activated the user has to aquire three things in order to
  73 connect to the StatusNet account of choice.
  74
  75 * the base URL for the StatusNet API, for identi.ca this is https://identi.ca/api/
  76 * OAuth Consumer key & secret
  77
  78 To get the OAuth Consumer key pair the user has to (a) ask her Friendica admin
  79 if a pair already exists or (b) has to register the Friendica server as a
  80 client application on the StatusNet server. This can be done from the account
  81 settings under "Connect -> Connections -> Register an OAuth client application
  82 -> Register a new application".
  83
  84 During the registration of the OAuth client remember the following:
  85
  86 * there is no callback url
  87 * register a desktop client
  88 * with read & write access
  89 * the Source URL should be the URL of your Friendica server
  90
  91 After the required credentials for the application are stored in the
  92 configuration you have to actually connect your Friendica account with
  93 StatusNet. To do so follow the Sign in with StatusNet button, allow the access
  94 and copy the security code into the plugin configuration. Friendica will then
  95 try to acquire the final OAuth credentials from the API, if successful the
  96 plugin settings will allow you to select to post your public messages to your
  97 StatusNet account.
  98
  99 Mirroring of Public Postings
 100 ----------------------------
 101
 102 To avoid endless loops of public postings that are send to StatusNet and then
 103 mirrored back into your friendica stream you have to set the _name of the
 104 application you registered there_ of your friendica node is using to post to
 105 StatusNet in the .htconfig.php file.
 106
 107     $a->config['statusnet']['application_name'] = "yourname here";
 108
 109 Connector Options for the User
 110 ==============================
 111
 112 * **Allow posting to StatusNet** If you want your _public postings_ being
 113   optionally posted to your associated StatusNet accout as well, you need to
 114   check this box.
 115 * **Send public postings to StatusNet by default** if you want to have _all_
 116   your public postings beeing send to your StatusNet account you need to check
 117   this button as well. Otherwise you have to enable the relay of your postings
 118   in the ACL dialog (click the lock button) before posting an entry.
 119 * **Mirror all posts from statusnet that are no replies or repeated messages**
 120   _TODO add info about the mirroring_
 121 * **Shortening method that optimizes the post** by default friendica checks how
 122   many characters your StatusNet instance allows you to use for a posting and
 123   if a posting is longer then this amount of characters it will shorten the
 124   message posted on StatusNet and add a short link back to the original
 125   posting. Optionally you can check this box to have the shortening of the
 126   message use an optimization algorithm. _TODO add infos how this is
 127   optimized_
 128 * **Send linked #-tags and @-names to StatusNet** if you want your #-tags and
 129   @-mentions linked to the friendica network, check this box. If you want to
 130   have StatusNet handle these things for the relayed end of the posting chain,
 131   uncheck it.
 132 * **Clear OAuth configuration** if you want to remove the currently associated
 133   StatusNet account from your friendica account you have to check this box and
 134   then hit the submit button. The saved settings will be deleted and you have
 135   to reconfigure the StatusNet connector to be able to relay your public
 136   postings to a StatusNet account.
 137
 138 License
 139 =======
 140
 141 The _StatusNet Connector_ is licensed unter the [3-clause BSD license][3] see the
 142 LICENSE file in the addons directory.
 143
 144 [3]: http://opensource.org/licenses/BSD-3-Clause