Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 210 lines (137 sloc) 10.207 kb
85fb397 @elivz First commit
authored
1 VZ Average
5693e7d @elivz Document this shiz
authored
2 ==========
3
4 *This is beta software, use at your own risk. But please send along suggestions and bug reports.*
5
08ef2e8 @elivz Documentation additions
authored
6 VZ Average is a flexible and minimal framework for rating or tallying anything in EE that you can identify with an ID: a channel entry, a comment, a Matrix row, or anything else. A few possible uses for it include: star ratings, thumbs up/down ratings, flagging comments as offensive, voting, etc.
5693e7d @elivz Document this shiz
authored
7
c9ef3af @elivz Put the add-on files into a vz_average folder for easier installation
authored
8 It provides a simple template tag that generates a form for submitting ratings, plus several tags to display data about the ratings. I have avoided outputting any UI (unlike the other ratings add-ons out there), focussing instead on providing an abstracted data store that you can use imaginatively to achieve a wide range of effects.
5693e7d @elivz Document this shiz
authored
9
10 When used to rate a channel entry, VZ Average can also update a custom field with the average, sum, minimum, maximum, or total number of ratings. Although any of these can also be output using VZ Average's template tags, mirroring them into a custom field will allow you to search or sort entries based on the number.
11
12
13 Installation
14 ------------
15
16 Copy the VZ Average directory into /system/expressionengine/third_party/. Enable the module in the control panel.
17
18
19 {exp:vz_average:form} tag pair
20 ------------------------------
21
22 This tag pair generates the form that you will use to submit a new rating. It only generates the form tags and some hidden fields, it is up to you to add an input or select tag with `name="value"` that will pass in the actual numeric value of the rating. See below for examples.
23
24 ### entry_id = [integer]
25
26 (required) The unique ID of the thing you are rating. Most often, this will be the {entry_id} of a channel entry or the {comment_id} of a comment, but it can be any unique identifier.
27
28 ### entry_type = [string]
29
30 This is essentially a namespace for the `entry_id`. If you are storing ratings for both channel entries and comments, there is a good chance their IDs will overlap, so you would set `entry_type="comment"` for the comment rating forms to keep their data separate. You can use any and as many entry_types as you see fit.
31
5ca6109 @elivz Add 'secure_return' parameter for https sites.
authored
32 ### site_id = [integer]
33
34 In a multi-site environment, set this to the ID number of the current site. Defaults to 1.
35
5693e7d @elivz Document this shiz
authored
36 ### form_id, form_class
37
38 These simply set their respective HTML attributes on the form tag, for styling or Javascript purposes.
39
40 ### return
41
42 The path to redirect to after the form is submitted. If this parameter is not set, it will default to returning to the current page.
43
5ca6109 @elivz Add 'secure_return' parameter for https sites.
authored
44 ### secure_return = "yes"
45
46 If you set `secure_return="yes"` the visitor will be sent to the "https" version of the return URL after submitting the form.
47
5693e7d @elivz Document this shiz
authored
48 ### limit_by = [ip|member]
49
50 If you wish to prevent people from voting more than once, you can set this parameter to either `ip` or `member`. The `member` setting means that only votes from logged-in members will be accepted, so you may want to make use of the {logged_in} condition to hide or disable the form for anonymous users.
51
52 Something to keep in mind: When a duplicate vote is detected, it will *replace* that person's previous vote. This means that a person can update their previous rating.
53
54 ### max, min
55
56 You can set maximum and minimum limits on the acceptable ratings. Any rating higher than the maximum or lower than the minimum will be changed to keep it within the set range.
57
58 ### update_field = [field short_name]
59
60 The `update_field` parameter lets you store the resulting average (or sum, max, etc.) in a custom field within the entry. In order for this to work, the `entry_id` must be the actual id of a channel entry. This parameter should be set to the short_name of the field you wish to update.
61
62 *Warning: Please do not use this when storing ratings for anything other than channel entries. There is a very good chance you will end up corrupting your channel data.*
63
64 ### update_with = [average|total|min|max|count]
65
66 The type of calculation to save in the custom field. This can be one of: `average`, `sum`, `min`, `max`, or `count`.
67
eabd761 @elivz Add before and after parameters
authored
68 ### since, before = [relative or absolute date]
69
70 If the `before` or `after` parameters are set, the updated field will be filled with data calculated using only the ratings from a certain time period. Either of these parameters can take any value that is able to be parsed with [PHP's strtotime](http://php.net/manual/en/function.strtotime.php) function.
71
5693e7d @elivz Document this shiz
authored
72
73 {exp:vz_average:average}, {exp:vz_average:sum}, {exp:vz_average:min}, {exp:vz_average:max}, {exp:vz_average:count}
74 ------------------------------------------------------------------------------------------------------------------
75
76 All of these retrieve calculated values for a particular entry. They each take the same two paramters:
77
ad28c60 @elivz Refactor the output tags for less code duplication
authored
78 ### entry_id = [integer]
5693e7d @elivz Document this shiz
authored
79
80 (required) The unique ID of the entry to be displayed.
81
ad28c60 @elivz Refactor the output tags for less code duplication
authored
82 ### entry_type = [string]
5693e7d @elivz Document this shiz
authored
83
84 The type of entry to be displayed. This defaults to `channel`.
85
ad28c60 @elivz Refactor the output tags for less code duplication
authored
86 ### site_id = [integer]
87
88 In a multi-site environment, set this to the ID number of the current site. Defaults to 1.
89
f8e2a59 @elivz Allow all output tags to be limited to just the current (or a particu…
authored
90 ### current_by = [ip|member]
91
59c4f8e @elivz Clarity docs.
authored
92 Only show data for the current user, as determined by either IP address or logged in member ID. If you set this to `member` and there is no logged in member, all tags will return `0`.
f8e2a59 @elivz Allow all output tags to be limited to just the current (or a particu…
authored
93
94 ### member_id = [integer]
95
96 Only show data for a particular member.
97
a7f7899 @elivz Fix markdown
authored
98 ### decimals (only for {exp:vz_average:average})
ad28c60 @elivz Refactor the output tags for less code duplication
authored
99
100 The number of decimal places to round the average to. Defaults to 0 (displays whole numbers).
101
5693e7d @elivz Document this shiz
authored
102 ### min, max (only for {exp:vz_average:average})
103
104 If you specify a `min` and a `max`, the `{exp:vz_average:average}` tag will return a percentage rather than a fixed number. This is particularly useful for generating bar graphs, as can be seen in the first example below.
105
eabd761 @elivz Add before and after parameters
authored
106 ### before, after = [relative or absolute date]
107
108 If the `before` or `after` parameters are set, the returned number will be calculated with only the ratings from a certain time period. Either of these parameters can take any value that is able to be parsed with [PHP's strtotime](http://php.net/manual/en/function.strtotime.php) function.
109
5693e7d @elivz Document this shiz
authored
110
111 AJAX
112 ----
113
114 You can easily POST the VZ Average form using AJAX, in which case the return value will be a JSON string containing all the calculated values, which can be decoded into the following object:
115
116 {
117 'average': 0,
118 'sum': 0,
119 'min': 0,
120 'max': 0,
121 'count': 0
122 }
123
124
125 Examples
126 --------
127
128 ### Tally votes
129
130 <h2>{title} has received {exp:vz_average:count entry_id="{entry_id}"} votes!</h2>
131 {if logged_in}
132 {exp:vz_average:form entry_id="{entry_id}" limit_by="member"}
133 <input type="hidden" name="value" value="1" />
134 <input type="submit" value="Vote for {title}!" />
135 {/exp:vz_average:form}
136 {if:else}
137 <p class="alert">You must be logged in to vote :(</p>
138 {/if}
139
140 ### Simple 5-star rating widget
141
142 The `rating` custom field will be updated with the new average rating each time, allowing for the entries to be sorted from highest- to lowest-rated.
143
144 <div class="star-rating" style="position:relative; background:#00f;">
145 <meter max="5" min="0" style="width:{exp:vz_average:average entry_id="{entry_id}" min="0" max="5"}%; background:#ff0;" value="{rating}">
146 {rating} out of 5
147 </meter>
148 </div>
149 {exp:vz_average:form entry_id="{entry_id}" limit_by="ip" min="0" max="5" update_field="rating" update_type="average"}
150 <label for="rating_{entry_id}_1">1</label>
151 <input id="rating_{entry_id}_1" name="value" type="radio" value="1" />
152 <label for="rating_{entry_id}_2">2</label>
153 <input id="rating_{entry_id}_2" name="value" type="radio" value="2" />
154 <label for="rating_{entry_id}_3">3</label>
155 <input id="rating_{entry_id}_3" name="value" type="radio" value="3" />
156 <label for="rating_{entry_id}_4">4</label>
157 <input id="rating_{entry_id}_4" name="value" type="radio" value="4" />
158 <label for="rating_{entry_id}_5">5</label>
159 <input id="rating_{entry_id}_5" name="value" type="radio" value="5" />
160 {/exp:vz_average:form}
161
162 ### Allow users to flag comments as "offensive"
163
164 <ol>{exp:comment:entries entry_id="{entry_id}" status="not Closed"}
165 <li class="comment" id="comment_{comment_id}">
166 <div class="author">By {url_as_author}</div>
167 <div class="comment_body">{comment}</div>
168 <div class="published"><time>{comment_date format="%F %j, %Y"}</time></div>
169 {exp:vz_average:form entry_id="{comment_id}" entry_type="comment" limit_by="ip"}
170 <input type="hidden" name="value" value="1" />
171 <input type="submit" value="Flag as Offensive" />
172 {/exp:vz_average:form}
173 </li>
174 {/exp:comment:entries}</ol>
175
176 Note that this will not automatically close comments when they reach a certain number of "flags". That can be done with an experimental modification to VZ Average's core code. Edit `mod.vz_average.php` and add the following code beginning on line 194:
177
178 // MOD: close comments with enough flags
179 if ($entry_type == 'comment') {
180 if ($cumulative['count'] > 0)
181 {
182 $status = 'p';
183 }
184 elseif ($cumulative['count'] > 2) // Change the "2" to however many flags it takes to trigger the filter
185 {
186 $status = 'c';
187 }
188 else
189 {
190 $status = 'o';
191 }
192
193 $this->EE->db->update(
194 'exp_comments',
195 array('status' => $status),
196 array('comment_id' => $entry_id, 'site_id' => $this->EE->input->post('site_id'))
197 );
198 }
199
200
201 Roadmap
202 -------
203
204 In no particular order, these are features I hope to add in the relatively near future. If anyone has other suggestions, or wants to tackle one of these and submit a pull-request, so much the better.
205
206 * A CP interface to view rated items. Sort by most rated, highest average, etc.
207 * Support saving data to more than one custom field at a time.
208 * Add more data outputs including [weighted scoring](http://evanmiller.org/how-not-to-sort-by-average-rating.html) for better entry sorting.
209 * More/better code examples for different scenarios.
7321d15 @elivz Add site_id parameter for MSM support
authored
210 * Hooks (what do y'all want?)
Something went wrong with that request. Please try again.