twitter/README.md

   1 Twitter Plugin
   2 ==============
   3
   4 Main authors Tobias Diekershoff and Michael Vogel.
   5
   6 With this addon to friendica you can give your user the possibility to post
   7 their *public* messages to Twitter. The messages will be strapped their rich
   8 context and shortened to 140 characters length if necessary. If shortening of
   9 the message was performed a link will be added to the Tweet pointing to the
  10 original message on your server.
  11
  12 The addon can also mirror a users Tweets into the ~friendica wall.
  13
  14 There is a similar addon for forwarding public messages to
  15 [StatusNet](http://status.net).
  16
  17 Requirements
  18 ------------
  19
  20 To use this plugin you have to register an application for your friendica
  21 instance on Twitter with
  22 * read and write access
  23 * don't set a callback URL
  24 * we do not intend to use Twitter for login
  25 The registration can be done at twitter.com/apps and you need a Twitter
  26 account for doing so.
  27
  28 After you registered the application you get an OAuth consumer key / secret
  29 pair that identifies your app, you will need them for configuration.
  30
  31 The inclusion of a shorturl for the original posting in cases when the
  32 message was longer than 140 characters requires it, that you have *PHP5+* and
  33 *curl* on your server.
  34
  35 Where to find
  36 -------------
  37
  38 In the friendica addon git repository /twitter/, this directory contains
  39 all required PHP files (including the [Twitter OAuth library][1] by Abraham
  40 Williams, MIT licensed and the [Slinky library][2] by Beau Lebens, BSD license),
  41 a CSS file for styling of the user configuration and an image to _Sign in with
  42 Twitter_.
  43
  44 [1]: https://github.com/abraham/twitteroauth
  45 [2]: http://dentedreality.com.au/projects/slinky/
  46
  47 Configuration
  48 =============
  49
  50 Global Configuration
  51 --------------------
  52
  53 If you enabled an administrator account, please use the admin panel to configure
  54 the Twitter relay. If you for any reason prefer to use a configuration file instead
  55 of the admin panels, please refer to the Alternative Configuration below.
  56
  57 Activate the plugin from the plugins section of your admin panel.  When you have
  58 done so, add your consumer key and consumer secret in the settings section of the
  59 plugin page.
  60
  61 When this is done your user can now configure their Twitter connection at
  62 "Settings -> Connector Settings" and enable the forwarding of their *public*
  63 messages to Twitter.
  64
  65 Alternative Configuration
  66 -------------------------
  67
  68 To activate this addon add twitter to the list of active addons in your
  69 .htconfig.php file
  70
  71     $a->config['system']['addon'] = "twitter, ..."
  72
  73 Afterwards you need to add your OAuth consumer key / secret pair to it by
  74 adding the following two lines
  75
  76     $a->config['twitter']['consumerkey'] = 'your consumer KEY here';
  77     $a->config['twitter']['consumersecret'] = 'your consumer SECRET here';
  78
  79
  80 Mirroring of Public Postings
  81 ----------------------------
  82
  83 To avoid endless loops of public postings that are send to Twitter and then
  84 mirrored back into your friendica stream you have to set the _name of the
  85 application you registered there_ of your friendica node is using to post to
  86 Twitter in the .htconfig.php file.
  87
  88     $a->config['twitter']['application_name'] = "yourname here";
  89
  90 Connector Options for the User
  91 ==============================
  92
  93 When the OAuth consumer informations are correctly placed into the
  94 configuration file and a user visits the "Connector Settings" page they can now
  95 connect to Twitter. To do so one has to follow the _Sign in with Twitter_
  96 button (the page will be opened in a new browser window/tab) and get a PIN from
  97 Twitter. This PIN has to be entered on the settings page. After submitting the
  98 PIN the plugin will get OAuth credentials identifying this user from the
  99 friendica account.
 100
 101 After this step was successful the user now has the following config options.
 102
 103 * **Allow posting to StatusNet** If you want your _public postings_ being
 104   optionally posted to your associated Twitter account as well, you need to
 105   check this box.
 106 * **Send public postings to StatusNet by default** if you want to have _all_
 107   your public postings being send to your Twitter account you need to check
 108   this button as well. Otherwise you have to enable the relay of your postings
 109   in the ACL dialog (click the lock button) before posting an entry.
 110 * **Mirror all posts from statusnet that are no replies or repeated messages**
 111   if you want your postings from Twitter also appear in your friendica
 112   postings, check this box. Replies to other people postings, repostings and your own
 113   postings that were send from friendica wont be mirrored into your friendica
 114   stream.
 115 * **Shortening method that optimizes the post** by default friendica checks how
 116   many characters your Twitter instance allows you to use for a posting and
 117   if a posting is longer then this amount of characters it will shorten the
 118   message posted on Twitter and add a short link back to the original
 119   posting. Optionally you can check this box to have the shortening of the
 120   message use an optimization algorithm. _TODO add infos how this is
 121   optimized_
 122 * **Send linked #-tags and @-names to StatusNet** if you want your #-tags and
 123   @-mentions linked to the friendica network, check this box. If you want to
 124   have Twitter handle these things for the relayed end of the posting chain,
 125   uncheck it.
 126 * **Clear OAuth configuration** if you want to remove the currently associated
 127   Twitter account from your friendica account you have to check this box and
 128   then hit the submit button. The saved settings will be deleted and you have
 129   to reconfigure the Twitter connector to be able to relay your public
 130   postings to a Twitter account.
 131
 132 License
 133 =======
 134
 135 The _StatusNet Connector_ is licensed under the [3-clause BSD license][3] see the
 136 LICENSE file in the addons directory.
 137
 138 [3]: http://opensource.org/licenses/BSD-3-Clause
 139
 140