modules/decisions/API.txt

The Mode API for Decisions.module
====================================

voting modes
------------

New voting modes can be defined by creating a file in
modes/foo.inc. The mode must define the hooks defined below.

Mode hooks
==========

In addition to the usual module hooks defined by Drupal,
decisions.module also has its own hooks. modes that do not define
mandatory hooks will create warnings and problems.

decisions_algorithms
--------------------

Mandatory. Return a list of algorithms provided by this decision mode. The list
if of the form:

algorithm => description

where algorithm is a short name for the algorithm (suitable for storage in the
database) and description a freeform description of the algorithm that will be
presented to the user.

decisions_voting_form
---------------------

Mandatory. This hook has the duty to return a HTML form suitable for
submitting new votes in the decision. It can also add arbitrary
HTML. It is suggested to setup the form using the new form API and
call drupal_get_form() to allow the theme to override the display.

TODO: right now, there is a common theme hook for all hooks, which
might be a problem.

decision_view_results
---------------------

Mandatory. This hook is called when the user has already voted or when
the module thinks it's relevant to display a decision's results. This
will generally call _voting_api_get_raw_votes() or something similar.

decisions_format_votes
----------------------

Mandatory. Format the votes of a user on a single line. Returns a
string.

decision_vote
-------------

Mandatory. This hook is called when a vote is registered. Form data
setup in decisions_view_voting_$mode() will as an argument. This will
usually call votingapi_set_vote() or similar.

decisions_vote_validate
-----------------------

Optional. Additional validation of vote submissions. Defaults to no
validation. This hook should behave as a normal form validation hook
(ie. hook_validate() in drupal terminology), that is, amongst other
things, set errors using form_set_error(). It should return TRUE if
the form is valid, FALSE otherwise.
1	The Mode API for Decisions.module
2	====================================
3
4	voting modes
5	------------
6
7	New voting modes can be defined by creating a file in
8	modes/foo.inc. The mode must define the hooks defined below.
9
10	Mode hooks
11	==========
12
13	In addition to the usual module hooks defined by Drupal,
14	decisions.module also has its own hooks. modes that do not define
15	mandatory hooks will create warnings and problems.
16
17	decisions_algorithms
18	--------------------
19
20	Mandatory. Return a list of algorithms provided by this decision mode. The list
21	if of the form:
22
23	algorithm => description
24
25	where algorithm is a short name for the algorithm (suitable for storage in the
26	database) and description a freeform description of the algorithm that will be
27	presented to the user.
28
29	decisions_voting_form
30	---------------------
31
32	Mandatory. This hook has the duty to return a HTML form suitable for
33	submitting new votes in the decision. It can also add arbitrary
34	HTML. It is suggested to setup the form using the new form API and
35	call drupal_get_form() to allow the theme to override the display.
36
37	TODO: right now, there is a common theme hook for all hooks, which
38	might be a problem.
39
40	decision_view_results
41	---------------------
42
43	Mandatory. This hook is called when the user has already voted or when
44	the module thinks it's relevant to display a decision's results. This
45	will generally call _voting_api_get_raw_votes() or something similar.
46
47	decisions_format_votes
48	----------------------
49
50	Mandatory. Format the votes of a user on a single line. Returns a
51	string.
52
53	decision_vote
54	-------------
55
56	Mandatory. This hook is called when a vote is registered. Form data
57	setup in decisions_view_voting_$mode() will as an argument. This will
58	usually call votingapi_set_vote() or similar.
59
60	decisions_vote_validate
61	-----------------------
62
63	Optional. Additional validation of vote submissions. Defaults to no
64	validation. This hook should behave as a normal form validation hook
65	(ie. hook_validate() in drupal terminology), that is, amongst other
66	things, set errors using form_set_error(). It should return TRUE if
67	the form is valid, FALSE otherwise.