/[drupal]/contributions/modules/fivestar/fivestar.module
ViewVC logotype

Diff of /contributions/modules/fivestar/fivestar.module

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph | View Patch Patch

revision 1.30, Thu Oct 22 19:58:56 2009 UTC revision 1.31, Tue Nov 3 04:24:50 2009 UTC
# Line 1  Line 1 
1  <?php  <?php
2  // $Id: fivestar.module,v 1.29 2009/10/22 19:58:18 ezrag Exp $  // $Id: fivestar.module,v 1.30 2009/10/22 19:58:56 ezrag Exp $
3    
4  /**  /**
5   * @file   * @file
6   * A simple n-star voting widget, usable in other forms.   * A simple n-star voting widget, usable in other forms.
7   */   */
8    
9    /**
10     * Implementation of hook_help().
11     */
12  function fivestar_help($path, $arg) {  function fivestar_help($path, $arg) {
13    $output = '';    $output = '';
14    switch ($path) {    switch ($path) {
# Line 29  function fivestar_help($path, $arg) { Line 32  function fivestar_help($path, $arg) {
32    
33  /**  /**
34   * Implementation of hook_menu().   * Implementation of hook_menu().
  *  
  * Provides a callback url where votes can be submitted by the client-side  
  * javascript.  
35   */   */
36  function fivestar_menu() {  function fivestar_menu() {
37    $items = array();    $items = array();
# Line 327  function _fivestar_cast_vote($type, $cid Line 327  function _fivestar_cast_vote($type, $cid
327    }    }
328  }  }
329    
330    /**
331     * Utility function to retreive VotingAPI votes.
332     *
333     * Note that this should not be used for general vote retreival, instead the
334     * VotingAPI function votingapi_select_results() should be used, which is more
335     * efficient when retrieving multiple votes.
336     *
337     * @param $type
338     *   The content type for which to retreive votes.
339     * @param $cid
340     *   The content ID for which to retreive votes.
341     * @param $tag
342     *   The VotingAPI tag for which to retreive votes.
343     * @param $uid
344     *   Optional. A user ID for which to retreive votes.
345     * @return
346     *   An array of the following keys:
347     *   - average: An array of VotingAPI results, including the average 'value'.
348     *   - count: An array of VotingAPI results, including the count 'value'.
349     *   - user: An array of VotingAPI results, including the user's vote 'value'.
350     */
351  function fivestar_get_votes($type, $cid, $tag = 'vote', $uid = NULL) {  function fivestar_get_votes($type, $cid, $tag = 'vote', $uid = NULL) {
352    global $user;    global $user;
353    
# Line 664  function fivestar_form(&$form_state, $co Line 685  function fivestar_form(&$form_state, $co
685    return fivestar_custom_widget($form_state, $values, $settings);    return fivestar_custom_widget($form_state, $values, $settings);
686  }  }
687    
688    /**
689     * Retreive and print out a static display of stars for a piece of content.
690     *
691     * @param $content_type
692     *   The type of content that will have its vote retreived. i.e. "node".
693     * @param $content_id
694     *   The ID of the content that will have its vote retreived.
695     * @param $node_type
696     *   Optional. If retreiving a node's rating, passing in the node type will
697     *   prevent Fivestar from doing an additional query to find it.
698     * @param $tag
699     *   Optional. The voting tag that will be retreived. Defaults to "vote" if none
700     *   is specified.
701     */
702  function fivestar_static($content_type, $content_id, $node_type = NULL, $tag = 'vote') {  function fivestar_static($content_type, $content_id, $node_type = NULL, $tag = 'vote') {
703    global $user;    global $user;
704    
# Line 741  function fivestar_static($content_type, Line 776  function fivestar_static($content_type,
776    return theme('fivestar_static_element', $star_display, $title, $text_display);    return theme('fivestar_static_element', $star_display, $title, $text_display);
777  }  }
778    
779    /**
780     * Form builder; Build a custom Fivestar rating widget with arbitrary settings.
781     *
782     * This function is usually not called directly, instead call
783     * drupal_get_form('fivestar_custom_widget', $values, $settings) when wanting
784     * to display a widget.
785     *
786     * @param $form_state
787     *   The form state provided by Form API.
788     * @param $values
789     *   An array of current vote values from 0 to 100, with the following array
790     *   keys:
791     *   - user: The user's current vote.
792     *   - average: The average vote value.
793     *   - count: The total number of votes so far on this content.
794     * @param $settings
795     *   An array of settings that configure the properties of the rating widget.
796     *   Available keys for the settings include:
797     *   - content_type: The type of content which will be voted upon.
798     *   - content_id: The content ID which will be voted upon.
799     *   - stars: The number of stars to display in this widget, from 2 to 10.
800     *     Defaults to 5.
801     *   - autosubmit: Whether the form should be submitted upon star selection.
802     *     Defaults to TRUE.
803     *   - allow_clear: Whether or not to show the "Clear current vote" icon when
804     *     showing the widget. Defaults to FALSE.
805     *   - required: Whether this field is required before the form can be
806     *     submitted. Defaults to FALSE.
807     *   - feedback_enable: Toggles the option to show the "Vote is being saved"
808     *     text while a vote is being registered through AJAX. Defaults to TRUE.
809     *   - labels_enable: Toggles the option to show the "Give it 2/5 stars" text
810     *     while hovering over the stars with the mouse.
811     *   - labels: An array of labels to be used. The number of labels should match
812     *     the number of stars.
813     *   - tag: The VotingAPI tag that will be registered by this widget. Defaults
814     *     to "vote".
815     */
816  function fivestar_custom_widget(&$form_state, $values, $settings) {  function fivestar_custom_widget(&$form_state, $values, $settings) {
817    $form = array(    $form = array(
818      '#attributes' => array('class' => 'fivestar-widget'),      '#attributes' => array('class' => 'fivestar-widget'),
# Line 967  function theme_fivestar_widget($form) { Line 1039  function theme_fivestar_widget($form) {
1039  }  }
1040    
1041  /**  /**
1042   * Display a plain HTML VIEW ONLY version of the widget   * Display a plain HTML view-only version of the widget with a specified rating.
  * with the specified rating  
1043   *   *
1044   * @param $rating   * @param $rating
1045   *   The desired rating to display out of 100 (i.e. 80 is 4 out of 5 stars)   *   The desired rating to display out of 100 (i.e. 80 is 4 out of 5 stars).
1046   * @param $stars   * @param $stars
1047   *   The total number of stars this rating is out of   *   The total number of stars this rating is out of.
1048   * @param $tag   * @param $tag
1049   *   Allows multiple ratings per node   *   Allows multiple ratings per node.
1050   * @return   * @return
1051   *   A themed HTML string representing the star widget   *   A themed HTML string representing the star widget.
  *  
1052   */   */
1053  function theme_fivestar_static($rating, $stars = 5, $tag = 'vote') {  function theme_fivestar_static($rating, $stars = 5, $tag = 'vote') {
1054    $output = '';    $output = '';
# Line 1011  function theme_fivestar_static($rating, Line 1081  function theme_fivestar_static($rating,
1081    return $output;    return $output;
1082  }  }
1083    
1084    /**
1085     * Display the text associated with a static star display.
1086     *
1087     * Note that passing in explicit data types is extremely important when using
1088     * this function. A NULL value will exclude the value entirely from display,
1089     * while a 0 value indicates that the text should be shown but it has no value
1090     * yet.
1091     *
1092     * All ratings are from 0 to 100.
1093     *
1094     * @param $user_rating
1095     *   The current user's rating.
1096     * @param $average
1097     *   The average rating.
1098     * @param $votes
1099     *   The total number of votes.
1100     * @param $stars
1101     *   The number of stars being displayed.
1102     * @param $feedback
1103     *   A toggle that enables AJAX indicator message when a vote is being saved.
1104     * @return
1105     *   A themed HTML string representing the star widget.
1106     */
1107  function theme_fivestar_summary($user_rating, $average_rating, $votes, $stars = 5, $feedback = TRUE) {  function theme_fivestar_summary($user_rating, $average_rating, $votes, $stars = 5, $feedback = TRUE) {
1108    $output = '';    $output = '';
1109    $div_class = '';    $div_class = '';
# Line 1218  function fivestar_expand($element) { Line 1311  function fivestar_expand($element) {
1311    return $element;    return $element;
1312  }  }
1313    
1314    /**
1315     * An #element_validate function for "fivestar" elements.
1316     */
1317  function fivestar_validate($element, &$form_state) {  function fivestar_validate($element, &$form_state) {
1318    if ($element['#required'] && (empty($element['#value']) || $element['#value'] == '-')) {    if ($element['#required'] && (empty($element['#value']) || $element['#value'] == '-')) {
1319      form_error($element, t('!name field is required.', array('!name' => $element['#title'])));      form_error($element, t('!name field is required.', array('!name' => $element['#title'])));
Legend:
Removed from v.1.30  
changed lines
  Added in v.1.31
  ViewVC Help
Powered by ViewVC 1.1.2