NAME

Podius::Property::Rating - component property useful for rating

SYNOPSIS

Supposed to be used in the Podius::Component manpage and the Podius::Property manpage module trees only.

DESCRIPTION

This property represent a simple polling where the participants with unique ids may rate something by giving a mark that is an integer value in certain interval. There are two main useful modes, when the interval is from 1 to some positive integer (5 by default), and when the interval is from -N to N (if -N is -1, then such poll correspond to just ``I like it, +1'' or ``I dislike it, -1''). The interval may be arbitrary actually, but these two main modes seems to be the most useful (the value 0 is a bit special in any mode and means no vote).

Some simple statistics may be queried, the number of votes, the sum of all marks, and the average (that is the ratio of the previous two integers, except when there are no votes, in which case it is 0).

The same participant can't vote several times, but may change their previous vote if needed.

REQUIREMENTS

the Podius::Property manpage, the Podius::Property::ScalarHash manpage.

METHODS

is_set

description
Whether a value for the given key is set.

Note, the validity of the value is verified and theoretically this method may delete the value if invalid, so you can't assume this method is read-only (use access for a read-only query).

parameters
  * key to query
returns
Boolean 1 if set, or 0 otherwise.

is_valid

description
Whether the given value is valid for this property (should be positive integer in the known range).

parameters
  * value to verify
returns
Boolean 1 if valid, or 0 otherwise.

set

description
Very similar to access(key, value) form, but applies checks on value. Also the existing key value can't be replaced by default.

parameters
  * key to apply
  * value to set
  * optional can_replace flag (default 0 means can't replace value)
returns
1 if new value is set, 0 if the value was not modified, undef on invalid input (like no key or not valid value, see is_valid).

unset

description
Very similar to access(key, undef) form.

parameters
  * key to apply
returns
1 if existing value was unset, 0 if no key value existed, undef on invalid input (no key).

access_sum

description
Only accessor form is available.

parameters
None.

returns
An integer that is the sum of all existing values.

access_min_value

description
Only accessor form is available.

parameters
None.

returns
An integer that is the minimal possible acceptable value (may be negative).

access_max_value

description
Only accessor form is available.

parameters
None.

returns
An integer that is the maximal possible acceptable value (may be negative).

access_average

description
Only accessor form is available.

parameters
  * precision (0 - round to the nearest integer, N - round to N floating
    points, "halfs" - means round to the nearest 0.5-times number)
returns
A number that is the rounded average of all existing values (mainly access_sum divided by access_num, or 0 if there are no any values).

access_stars

description
Only accessor form is available.

This is a convenient way to get a ``stars'' representation of this property. It calls access_average('halfs'). i.e. a star type may be ``full'', ``half'' (half-full) or ``void'' (empty).

parameters
  * optional parameter hash, the defaults are:
      star_half => '<%=$CHAR_STAR_HALF%>'
      star_full => '<%=$CHAR_STAR_FULL%>'
      star_void => '<%=$CHAR_STAR_VOID%>'
      delimeter => '&nbsp;'
returns
A string representing a rating in ``stars''.