Fixed destination of "configure" link on admin/modules
[project/tweet.git] / README.txt
1
2 =============
3 == Summary ==
4 =============
5 This module provides links to post or "tweet" pages to websites like Twitter.
6 Clicking the links will open a new window or tab for the relevant site. The
7 tweet will be in focus and will contain customizable text which can include the
8 relevant URL, title, and (if the tweet link appears on a node) taxonomy terms
9 and the teaser. The Shorten URLs module is used to shorten the URLs if it is
10 installed.
11
12 URLs and titles will be for either the node which is being displayed as a
13 teaser or for the current page. Multiple links can appear on the same page, as
14 on a View of teasers. By default, links appear in the Links section when
15 viewing full nodes or teasers.
16
17 Administrators can choose whether to show the link as an icon, an icon and
18 text, or just text.  Options can be chosen separately for nodes and teasers.
19 Administrators can also choose which node types the links should appear on, or
20 could choose not to have links show up on nodes at all.  If the module is
21 configured not to display links automatically, administrators can display their
22 own links wherever they like by calling tweet_to_twitter().  A more complete
23 explanation is below.
24
25 =====================
26 == Development/API ==
27 =====================
28 If you are using this module to display links to twitter arbitrarily, you will
29 probably be using the tweet_to_twitter() function.  This constructs the link
30 you need according to the following arguments.  All arguments are optional
31 unless otherwise noted.  If no arguments are passed the link constructed will
32 be for the current page according to your settings.
33
34 If you want more control, the _tweet_to_twitter() function takes the same
35 arguments and returns an array in the format required by hook_link()
36 (http://api.drupal.org/api/function/hook_link).
37
38 -- tweet_to_twitter($site = 'Twitter', $type = '', $format = '', $nid = '') --
39 $site
40   Specifies for which site the link will be generated. Twitter is the default.
41   See tweet_sites() for a list of allowed sites.
42 $type
43   Specifies what will show up in the link: the twitter icon, the twitter icon
44   and text, or just text. Pass 'icon' to show just the icon, 'icon_text' to
45   show the icon and text, and 'text' to show just the text. Required if display
46   options for nodes are set to 'none' on the settings page.
47 $format
48   A string representing the tweet text, optionally with the case-sensitive
49   tokens [url], [title], [node-tags], and [node-teaser]. If not passed, the
50   format from the settings page will be used.
51 $nid
52   The NID of the node for which the twitter link should be constructed, or
53   the absolute URL of the page for which the twitter link should be
54   constructed. If the URL given is not the current URL, and if $nid is not a
55   NID, the title must be set manually (instead of using the [title] token) or
56   it could be incorrect.
57
58
59 If you are building a module for general use, you will probably want to use the
60 tweet_sites() function to get a list of sites for which Tweet can build links.
61
62 -- tweet_sites($enabled_only = FALSE, $reset = FALSE) --
63 $enabled_only
64   If TRUE, only enabled sites are returned. Otherwise, all defined sites are
65   returned.
66 $reset
67   Reset and rebuild the static cache.
68
69
70 ----
71 If you want to add another site for the Tweet module to use, you should
72 implement hook_tweet_sites(). That hook returns an associative array specifying
73 information that Tweet will use to build tweet links. See tweet_tweet_sites()
74 for an example. The key of each element of the array should be the name of the
75 website; the value should be another associative array. The elements of the
76 inner array include:
77
78 path
79   The base URL where Tweet will send users who click on the tweet link.
80   Ex.: 'http://twitter.com/home'
81 query_key
82   The query key that specifies the text which will appear in the tweet textarea.
83   For Twitter, this is 'status,' generating a link like
84   http://twitter.com/home?status=[tweet_text].
85 image
86   The location of the image file associated with the site. Your module may want
87   to offer a setting to override this path if you want your users to be able to
88   use custom icons.
89   Ex.: drupal_get_path('module', 'tweet') .'/twitter.png'
90
91 If you just want to modify the settings a module provides for an existing site,
92 use hook_tweet_sites_alter(&$sites), where $sites is the array of sites
93 returned by module_invoke_all('tweet_sites').
94
95 ==================
96 == Installation ==
97 ==================
98   1. Install this module as usual (FTP the files to sites/all/modules, enable 
99      at admin/build/modules).  See http://drupal.org/node/176044 for help.
100   2. If you want to use shortened URLs in your tweets, also install the
101       Shorten URLs module by the same author (see the Links section below).
102   3. If you want, go to admin/settings/tweet to change the module's settings.
103
104 ===========
105 == Links ==
106 ===========
107 Visit the module page for more information.
108
109 Module Page: http://drupal.org/project/tweet
110 Issue Queue: http://drupal.org/project/issues/tweet
111 Enable Module: http://example.com/?q=admin/build/modules
112 Settings Page: http://example.com/?q=admin/settings/tweet
113 Shorten URLs: http://drupal.org/project/shorten