diff --git a/twitter/LICENSE b/twitter/LICENSE new file mode 100644 index 00000000..062cc888 --- /dev/null +++ b/twitter/LICENSE @@ -0,0 +1,24 @@ +Copyright (c) 2011-2013 Tobias Diekershoff, Michael Vogel +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + * Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the distribution. + * Neither the name of the nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL BE LIABLE FOR ANY DIRECT, +INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF +ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/twitter/README b/twitter/README deleted file mode 100755 index 8041f317..00000000 --- a/twitter/README +++ /dev/null @@ -1,92 +0,0 @@ -____ Twitter Plugin ____ -By Tobias Diekershoff - http://diekershoff.homeunix.net/friendika/profile/tobias - tobias.diekershoff(at)gmx.net - -With this addon to Friendica 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. - -The addon can also mirror a users Tweets into the ~friendica wall. - -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 an application for your friendica -instance on Twitter with - * read and write access - * don't set a callback URL - * we do not intend to use Twitter for login -The registration can be done at twitter.com/apps and you need a Twitter -account for doing 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 than 140 characters requires it, that you have *PHP5+* and -*curl* on your server. - -___ Where to find ___ - -In the Friendica 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 __ - -If you enabled an administrator account, please use the admin panel to configure -the Twitter relay. If you for any reason prefer to use a configuration file instead -of the admin panels, please refer to the Alternative Configuration below. - -Activate the plugin from the plugins section of your admin panel. When you have -done so, add your consumer key and consumer secret in the settings section of the -plugin page. - -When this is done your user can now configure their Twitter connection at -"Settings -> Connector Settings" and enable the forwarding of their *public* -messages to Twitter. - -__ Alternative 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 two lines - -$a->config['twitter']['consumerkey'] = 'your consumer KEY here'; -$a->config['twitter']['consumersecret'] = 'your consumer SECRET here'; - - -__ User Configuration __ - -When the OAuth consumer informations are correctly placed into the -configuration file and a user visits the "Plugin 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 -Friendica account. - -If this first step was successful the Twitter configuration will be changed -on the "Plugin 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. - - diff --git a/twitter/README.md b/twitter/README.md new file mode 100644 index 00000000..13f0152f --- /dev/null +++ b/twitter/README.md @@ -0,0 +1,140 @@ +Twitter Plugin +============== + +Main authors Tobias Diekershoff and Michael Vogel. + +With this addon to friendica 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. + +The addon can also mirror a users Tweets into the ~friendica wall. + +There is a similar addon for forwarding public messages to +[StatusNet](http://status.net). + +Requirements +------------ + +To use this plugin you have to register an application for your friendica +instance on Twitter with +* read and write access +* don't set a callback URL +* we do not intend to use Twitter for login +The registration can be done at twitter.com/apps and you need a Twitter +account for doing 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 than 140 characters requires it, that you have *PHP5+* and +*curl* on your server. + +Where to find +------------- + +In the friendica addon git repository /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 +-------------------- + +If you enabled an administrator account, please use the admin panel to configure +the Twitter relay. If you for any reason prefer to use a configuration file instead +of the admin panels, please refer to the Alternative Configuration below. + +Activate the plugin from the plugins section of your admin panel. When you have +done so, add your consumer key and consumer secret in the settings section of the +plugin page. + +When this is done your user can now configure their Twitter connection at +"Settings -> Connector Settings" and enable the forwarding of their *public* +messages to Twitter. + +Alternative 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 two lines + + $a->config['twitter']['consumerkey'] = 'your consumer KEY here'; + $a->config['twitter']['consumersecret'] = 'your consumer SECRET here'; + + +Mirroring of Public Postings +---------------------------- + +To avoid endless loops of public postings that are send to Twitter and then +mirrored back into your friendica stream you have to set the _name of the +application you registered there_ of your friendica node is using to post to +Twitter in the .htconfig.php file. + + $a->config['twitter']['application_name'] = "yourname here"; + +Connector Options for the User +============================== + +When the OAuth consumer informations are correctly placed into the +configuration file and a user visits the "Connector 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 +friendica account. + +After this step was successful the user now has the following config options. + +* **Allow posting to StatusNet** If you want your _public postings_ being + optionally posted to your associated Twitter account as well, you need to + check this box. +* **Send public postings to StatusNet by default** if you want to have _all_ + your public postings being send to your Twitter account you need to check + this button as well. Otherwise you have to enable the relay of your postings + in the ACL dialog (click the lock button) before posting an entry. +* **Mirror all posts from statusnet that are no replies or repeated messages** + if you want your postings from Twitter also appear in your friendica + postings, check this box. Replies to other people postings, repostings and your own + postings that were send from friendica wont be mirrored into your friendica + stream. +* **Shortening method that optimizes the post** by default friendica checks how + many characters your Twitter instance allows you to use for a posting and + if a posting is longer then this amount of characters it will shorten the + message posted on Twitter and add a short link back to the original + posting. Optionally you can check this box to have the shortening of the + message use an optimization algorithm. _TODO add infos how this is + optimized_ +* **Send linked #-tags and @-names to StatusNet** if you want your #-tags and + @-mentions linked to the friendica network, check this box. If you want to + have Twitter handle these things for the relayed end of the posting chain, + uncheck it. +* **Clear OAuth configuration** if you want to remove the currently associated + Twitter account from your friendica account you have to check this box and + then hit the submit button. The saved settings will be deleted and you have + to reconfigure the Twitter connector to be able to relay your public + postings to a Twitter account. + +License +======= + +The _StatusNet Connector_ is licensed under the [3-clause BSD license][3] see the +LICENSE file in the addons directory. + +[3]: http://opensource.org/licenses/BSD-3-Clause + +