Updates to README and MANIFEST files.
[matthijs/upstream/blosxom-plugins.git] / general / karma
1 # Bloxsom Plugin: Karma
2 # Author: Fletcher T. Penney < http://fletcher.freeshell.org/ >
3 # Original Concept: Beau Lebens
4 # Idea of using a form - Pasi Savolainen
5
6 # Version: 0.6
7
8 package karma;
9
10 # --- Configurable variables ----
11
12 # Where is the data kept?
13 $datafile = "$blosxom::plugin_state_dir/karma.dat";
14
15 # FYI, the data format is as follows
16 # Visits Positives Negatives Interest_Index Karma_Index Controversy_Index /Path/To/Article
17 # tabs are used as separators
18
19 # List of ip addresses to ignore for visit counts.
20 # Use '|' as a separator if you have more than one
21 # ie. $ip_list = '192.168.1.1|192.168.1.2'
22
23 $ip_list = '';
24
25 # CGI variable names to use for specifying certain minimum scores
26 $minkarma_var           = "minkarma";
27 $mincontroversy_var     = "mincontroversy";
28 $mininterest_var        = "mininterest";
29
30 # For instance, by adding "?minkarma=5", stories with a karma of less than 5 would be filtered.
31 # You can change the terminology above if you don't like the names.
32
33 # -------------------------------
34
35 use CGI;
36
37 # Initialize variables
38 $stats = "";            # This variable will contain the results
39 $votelinks = "";        # This variable will contain the links to submit a vote
40
41 my $vote = "";
42 my $karmadata = "";
43 my $do_increment = 0;
44 my $matchfound = 0;
45 my $visits = 0;
46 my $pos = 0;
47 my $neg = 0;
48 my $visits = 0;
49 my $interest_index = 0;
50 my $karma_index = 0;
51 my $controversy_index = 0;
52
53 $minkarma = 0;
54 $mincontroversy = 0;
55 $mininterest = 0;
56
57 $message = "";          # Use this to report messages to the visitor
58
59
60 sub start {
61
62         $path_noflavour = $blosxom::path_info;
63         if ($path_noflavour !~ s/\.[^\.]*$//) {
64                 $path_noflavour =~ s/\/$//;
65                 $path_noflavour .= "\/index";
66                 $path_noflavour =~ s/^([^\/])/$1/;
67         }
68         $path_noflavour =~ s/^\/*//;
69
70         $remoteIP = $ENV{'REMOTE_ADDR'};        # Get IP address for visitor
71         $ip_list = 'disable' if ($ip_list eq "");       # Prevent an empty match expression
72
73         # Check to see if we are viewing a single story.
74         # If so, we want to increment the visits, unless this is a vote submission
75         # This does create the problem of reading a story on a category page, and voting for it
76         # No visit will be recorded - still looking for a solution
77
78         if (($path_noflavour !~ /index$/) && ($path_noflavour !~ /\/$/)) {
79                 $do_increment = 1 if ($remoteIP !~ /($ip_list)/);
80
81                 # Check to see whether a vote has been set
82                 if (CGI::param("setkarma")) {
83                         $vote = CGI::param("setkarma");
84                         # If this is a vote, we don't want to update visit count
85                         # They have already read the article and been counted
86                         $do_increment = 0;
87                 }
88         }
89
90         # Now we want to read in the data file, and update if appropriate
91         if (($do_increment eq 1) || ($vote ne "")) {
92                 # The file should be locked during this process in case of two simultaneous accesses
93                 open (DATA, "<$datafile");
94                 flock (DATA, 2);        # I think I am using this properly...
95                 while ( $line = <DATA>) {
96                         if ($line =~ /(\d+)\t(\d+)\t(\d+)\t[\.\d]+\t[\.\d]+\t[\.\d]+\t\/$path_noflavour$/) {
97                                 # This is the story currently being viewed, so read in info
98                                 $visits = $1 + $do_increment;
99                                 $pos = $2;
100                                 $neg = $3;
101                                 $pos ++ if ($vote =~ /^p/i);
102                                 $neg ++ if ($vote =~ /^n/i);
103                                 $total_votes = $pos + $neg;
104
105                                 # Try to correct for uncounted visits
106                                 $visits = $total_votes if ($total_votes > $visits);
107
108                                 $interest_index = ($pos + $neg)/$visits if ($visits ne 0);
109                                 $karma_index = $pos/($total_votes) if ( $total_votes ne 0);
110                                 $controversy_index = 2*$interest_index *(0.5 - abs($karma_index - 0.5));
111
112                                 $line = "$visits\t$pos\t$neg\t$interest_index\t$karma_index\t$controversy_index\t\/$path_noflavour\n";
113                                 $matchfound = 1;
114                         }
115                         $karmadata .= $line;
116                 }
117
118                 close (DATA);
119                 open (DATA, ">$datafile");
120                 flock (DATA, 2);        # Lock again, if it was unlocked
121                 print DATA $karmadata;
122
123                 # If no match was found for the story, create a new record
124                 if ($matchfound eq 0) {
125                         $visits = 1;
126                         $pos = $neg = 0;
127                         $pos ++ if ($vote =~ /^p/i);
128                         $neg ++ if ($vote =~ /^n/i);
129                         $total_votes = $pos + $neg;
130
131                         $interest_index = ($pos + $neg)/$visits if ($visits ne 0);
132                         $karma_index = $pos/($total_votes) if ( $total_votes ne 0);
133                         $controversy_index = 2*$interest_index *(0.5 - abs($karma_index - 0.5));
134
135                         $line = "$visits\t$pos\t$neg\t$interest_index\t$karma_index\t$controversy_index\t\/$path_noflavour\n";
136                         print DATA "$line";
137                         $karmadata .= "$line\n";
138                 }
139                 close (DATA);
140         } else {
141                 # Read in the existing data only - we are not viewing a single story
142                 open(DATA, "<$datafile");
143                 while ( $line = <DATA>) {$karmadata.=$line;}
144                 close (DATA);
145         }
146         flock(DATA, 8);         # Unlock file
147
148         # Here is where we can create list of top controversies, etc
149         # And we have info loaded for the sort routine if necessary
150         # Currently the karma plugin can filter for certain scores, but not sort
151
152         1;
153 }
154
155
156 sub filter {
157         my ($pkg, $files_ref) = @_;
158         my @files_list = keys %$files_ref;
159         my $dofilter = 0;
160         if (CGI::param($minkarma_var)) {
161                 $minkarma = CGI::param($minkarma_var);
162                 $dofilter = 1;
163         }
164
165         if (CGI::param($mincontroversy_var)) {
166                 $mincontroversy = CGI::param($mincontroversy_var);
167                 $dofilter = 1;
168         }
169
170         if (CGI::param($mininterest_var)) {
171                 $mininterest = CGI::param($mininterest_var);
172                 $dofilter = 1;
173         }
174
175
176         if ($dofilter eq 1) {
177         foreach $file (@files_list) {
178                 $realfile = $file;
179                 $file =~ s/^$blosxom::datadir//;
180                 $file =~ s/\.$blosxom::file_extension//;
181                 if ($karmadata =~ /(\d+)\t(\d+)\t(\d+)\t([\.\d]+)\t([\.\d]+)\t([\.\d]+)\t$file/) {
182                         if ($minkarma && ($5 < $minkarma/10)) {
183                                 delete $files_ref->{$realfile};
184                         }
185                         if ($mincontroversy && ($6 < $mincontroversy/10)) {
186                                 delete $files_ref->{$realfile};
187                         }
188                         if ($mininterest && ($4 < $mininterest/10)) {
189                                 delete $files_ref->{$realfile};
190                         }
191                 } else {
192                         delete $files_ref->{$realfile};
193                 }
194         }
195         }
196         1;
197 }
198
199 sub story {
200         my $karma_index = 0;
201         my $interest_index = 0;
202         my $controversy_index = 0;
203         my $total_votes = 0;
204         $pos = $neg = $visits = 0;
205
206         my ($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
207
208         if ($karmadata =~ /(\d+)\t(\d+)\t(\d+)\t([\.\d]+)\t([\.\d]+)\t([\.\d]+)\t$path\/$filename/) {
209                 $visits = $1;
210                 $pos = $2;
211                 $neg = $3;
212                 $total_votes = $pos + $neg;
213                 $visits = $total_votes if ($total_votes > $visits);
214                 $interest_index = $4;
215                 $karma_index = $5;
216                 $controversy_index = $6;
217
218                 # Clean up the values for display - we'll want to use the originals (or at least 
219                 # more decimal places for comparisons)
220                 # All values are integers on scale from 1-10
221                 $karma_index = int($karma_index * 10);
222                 $controversy_index = int($controversy_index * 10);
223                 $interest_index = int($interest_index * 10);
224         }
225
226
227         # Here you can define the HTML code that gets used to display your results
228         $stats = "Visits: $visits | Positives: $pos | Negatives: $neg<br>";
229         $stats.= "Karma: $karma_index | Interest: $interest_index | Controversy: $controversy_index";
230
231         # And this is the HTML code for the two vote submission links
232         #$votelinks = "<a href=\"$blosxom::url$path/$filename.$blosxom::flavour?setkarma=p\">I liked this article</a> | <a href=\"$blosxom::url$path/$filename.$blosxom::flavour?setkarma=n\">I didn't like it</a>.";
233         
234         $votelinks = qq!<form method="POST" action="$blosxom::url$path/$filename.html">
235         <div><input type="submit" name="setkarma" value="p">I liked this article |
236         <input type="submit" name="setkarma" value="n">I didn't like it
237         </div></form>!;
238                 
239         1;
240 }
241
242 1;
243
244
245 __END__
246
247
248 =head1 NAME
249
250 Blosxom Plug-in: karma
251
252 =head1 DESCRIPTION
253
254 Karma allows you to have your visitors score articles in a positive/negative fashion.  It then calculates various scores that you can use to incorporate a "Top 10 Articles" section, or something similar, into your website.
255
256 To install:
257
258 1) place the karma plugin in your plugins directory, with proper file permissions
259
260 2) ensure the configuration variables are properly set:
261         $datafile should be left alone, unless you have customized where plugins store information
262
263         $ip_list should include the IP addresses of any visitors you do NOT wish to be counted in scoring.  For instance, you should probably include your own IP address to prevent falsely biasing the numbers as you read and reread your site looking for errors
264
265         The $minkarma_var, $mincontroversy_var, and $mininterest_var variables can be used to customize the url's used to filter articles.
266
267 3) You can modify the HTML code snippets at the bottom of the story subroutine ($karma::stats and $karma::votelinks) to alter the display of the scores, and the vote submission links as you see fit.
268
269
270 Once installed, modify your story.flavour files to include the $karma::stats and $karma::votelinks variables.
271
272 Now, when you visit your site, you should see the scoring and links displayed with each story.  Each time you view a story individually, its visit count is advanced one.  Each time you click on the "I liked..." or "I didn't..." links, the positive and negative vote scores will be modified appropriately.
273
274 These numbers are used to calculate several variables:
275
276         $karma_index - this is a rating from 0 to 10 of how positively the story was viewed
277
278         $interest_index - this is a rating from 0 to 10 of what proportion of people who viewed the story bothered to vote on it.  This will be artificially low, as many people might view the story as part of a category, and their visit will NOT be counted.  I am open to ideas as to how to more accurately handle this, keeping in mind that many stories that are displayed are not actually read (ie, older stories at the bottom of a blog...)
279
280         $controversy_index - this is a rating that I came up with just for fun.  It is a measure of how many people voted, and how divergent their opinions were.  For instance, as the interest_index goes up, the controversy_index goes up.  As the votes are more evenly split between positives and negatives, the controversy_index goes up.  A story with 100% positive (or negative) votes, will have a 0 controversy index (everyone is in agreement, therefore there is no controversy...)  It's not a very scientific number at all, but sort of fun nonetheless.
281
282 4) You can add links to your site that will display the articles with the highest interest, karma, or controversy by using the $minkarma_var variables discussed in #3 above.
283
284 For instance you could add a url in your header file like this:
285 <a href="/weblog/index.html?minkarma=5">Show The Most-Liked Articles</a>
286
287 This would allow the display of only those articles with a karma above 5.  In the future, I hope to add a sort routine that would sort stories by the various indices, but currently the stories are unsorted.
288
289 =head1 NOTE
290
291 This plugin filters out articles only.  It does not locate any articles on its own.
292
293 Also, it uses the filter routine.  Therefore, it will interact with any other plugins that make use of the filtered articles list.  You may need to add numbers to the beginning of plugin names (ie, "55karma") to control the load order if you seem to be having unintended results.  For instance, karma will prevent some topics from being added by my "menu" plugin, unless it loads after menu.
294
295 =head1 AUTHOR
296
297 Fletcher T. Penney - http://fletcher.freeshell.org
298 Concept by Beau Lebens
299
300 This plugin is now maintained by the Blosxom Sourceforge Team,
301 <blosxom-devel@lists.sourceforge.net>.
302
303 =head1 LICENSE
304
305 This source is submitted to the public domain.  Feel free to use and modify it.  If you like, a comment in your modified source attributing credit to myself and Beau Lebens would be appreciated.
306
307 THIS SOFTWARE IS PROVIDED AS IS AND WITHOUT ANY WARRANTY OF ANY KIND.  USE AT YOUR OWN RISK!