Drupalit Contest

Download link below. The 'Readme.txt' which is also in the archive, follows.. (You will see at least one German sentence in it, referring to a property which should still be removed from the code in order to generalise it. It should not be that hard because the code is pretty clean otherwise. It is for Drupal 5 currently.)

This module adds a content type 'Contest'.

A contest, in this case, is a configurable period during which users can vote on a number of preselected nodes (comics). Views with number of votes and rankings can be shown (and amended in the views administration).

Voting is done through the Drupalit module.

Functionality in .tpl.php files

The Drupalit module/functionality is currently not able to display its VoteBox automatically inside of views. As noted in the drupalit module, themed views templates need to be used for this.

The functionality to display the Drupalit VoteBox (and enabling the user to vote) only during a configured time period, is also something which is solved insite template files, not in the main module. So, in order to make this module work properly:

• template files need to be installed in the correct location. See the subdirectory 'theme_examples' and its README.
• The 'Drupalit settings for nodes' must be set to 'Manually' -- otherwise the time interval will not be honored and strange things may happen.

The contest mechanism

A user with the respective access rights can create contest nodes. These have a start and an end date (which would typically both be in the future; at any rate an end date in the past is useless.)

After saving, the new contest node will have an 'assign' and 'deassign' tab. The 'assign' tab will show a list of nodes which are eligible to participate in this contest; these are nodes:

• of a certain content type (currently only 'Comic')
• which have the "Ich möchte mit meinem Beitrag am Contest teilnehmen" checkbox checked
• which are published
• which are not assigned to another active/future contest.

As long as the .tpl.php files for the nodes and the 'drupalit_contest_nodes' view are set up correctly, the votebox for participating nodes will automatically appear (on both the contest page and the individual node pages) after the start time has passed. From that point on until the end time, the participating collect Drupalit votes.

Also while the contest is active, nodes can still be unpublished and / or deassigned from the contest; it is just not very consistent to do so. Votes already cast, as visible in e.g. the 'active contests' view will be temporarily hidden (in the case of unpublishing a node) or be deleted from the database (in the case of deassigning a node).

(A remark: the 'published' status of a Contest node itself has no relation with this module. Users who can see unpublished contests, may still be able to vote in them. Others won't, simply because they can't see the contests.)

At the first cron run after the 'end' time has passed, a contest will be 'officially closed'. From that point on,

• participating comics will be eligible to participate in other contests again
• comics cannot be assigned/deassigned from this contest
• the start/end time of the contest cannot be changed anymore; not even by an administrator. (This is to prevent the possibility of comics ending up in multiple active contests, which would mess up voting results in all linked
  contests.)

Active voting results

There is one view of 'active contests' (and site administrators may create
their own views). The voting results in these views (like 'number of votes'
and 'ranking') will not be instantaneously updated when a user casts her
vote.

Since the Drupalit module has no 'hook system' of its own, the module needs
to be patched in one place in order for this to happen. A patch against
drupalit 5.x-1.4-beta2 is included.

If you do not want to patch the module, the results will be updated on every
'cron run'. If these results must be updated more frequently than a 'regular'
cron run, then the following URL which can be queried frequently:
http://YOURSITE/drupalit_contest/cron

Installation

• Install the module to your favourite location (sites/all/modules) and enable it (http://YOURSITE/admin/build/modules)
• If you want a list of participating nodes to appear on every 'contest' node (and you probably do), go to http://YOURSITE/admin/content/types/drupalit-contest/add_field, and add a field of type 'View field', configured with:
  • one allowed view in the 'Data settings': 'drupalit_contest_nodes'
  • in the 'Arguments:' textbox: '[nid]' (without the single quotes)
    ...and you probably want to check the 'Force default' checkbox above.
    [ TODO: do this programmatically ]
• at http://YOURSITE/admin/settings/drupalit, enable the 'comic' content type and set 'Drupalit settings for nodes' to 'Manually'
• at http://YOURSITE/admin/user/access#module-drupalit_contest, enable 'create drupalit_contest content' and 'edit drupalit_contest content' for the appropriate roles

Views integration

This module enables users (with appropriate permissions) to encorporate voting results into their own views.

A few notes when creating views:

You can override the views for the 'assign' and 'deassign' tabs, if you want them to look differently. Just keep the view names the same. However, you need to make sure that:

• they remain 'views bulk operations' type of views
• the right (exactly one) operation is assigned to these views. (You will see an "(De)Assign selected nodes" actions in the 'Operations' tab when editing the view.)

Before starting, think about what is the 'main node' in your view:
1) a contest
2) a node participating in a contest

Since Views 1.x has no (configurable) concept of relationships between tables, different fields / filters / arguments / sort options have been created for either case. Use ONLY items from ONE of these categories, or your view will not give any results!

If your 'main node' in the view is a contest, you can (ofcourse) also list certain data concerning participating nodes, and vice versa. But there is a conceptual difference in setting up the view (which is usually understood already by people who are in the business of creating views).

In category 1, you have at your disposal the following fields:
- Contest (this node): Start of contest (also filter/sort)
- Contest (this node): End of contest (also filter/sort)
- Contest (this node): Active (a yes/no value)
- Contest (this node): Number of participants #
- Contest (this node): Total votes (i.e. total for all nodes) #
- Contest (this node): Leader/Winner (i.e. a node title) #
* Contest (this node): closed (not a field, only filter)

If you use any of these fields, the view will be automatically filtered for only content types 'Contest'.

Note 'closed' is slightly different from 'end '; 'closed' becomes true after the first cron run after 'end'.

# PLEASE NOTE: due to either a bug in Views, or my inability to find any proper Views 1 documentation that explains what I need to know, three fields will give errors after you add them to the view. Do not fear; once you save the view, the errors will be gone and your results will display normally.

In category 2, you have at your disposal the following fields:
- Node in contest: number of votes # (i.e. total for THIS node only)
- Node in contest: time of last vote #
- Node in contest: ranking
- Node: latest contest (a contest title)
- Node: latest contest: end date
- Related contest: Title (also sort)
- Related contest: Start of contest (also filter/sort)
- Related contest: End of contest (also filter/sort)
* Related contest: Published (not a field, only filter)
* Node: is in an active contest (not a field, only filter)
* Node: is in an active OR future contest (not a field, only filter)

If you use any of the 'Related contest' fields, you may get multiple rows of data back, since a node may participate in multiple contests over time. If you want only one row of data per participating node, you should use some kind of filter. The last 2 mentioned filters are suitable for that.

(The last filter is used for determining whether a contest is (not) eligible for inclusion in another contest; the second-to-last is used for determining whether people are able to vote for nodes at this moment.)

# These two are also sort criteria. There are no sort criteria for ranking; if you want to sort on ranking then please sort 'descending' on the number of votes. (If you want to always have a consistent order for nodes having the same amount of votes, you can add 'time of last vote' as a secondary sort criteria. This is what the default views do; those who have received their last vote earlier, are ranked 'higher'.)