THIS DOCUMENT IS ABOUT A MECHANISM WHICH IS *NOT* YET IMPLEMENTED! IT IS JUST A TENTATIVE DESIGN!

THIS DOCUMENT IS NOW SUPERCEDED BY REALITY (the library structure)

In many places in the system we need actions that are activated through a link, 
get some input, do something server-side (often change the database), and then 
return to the page from where they were originally called.

Creating new actions involves three steps.

1) Make a php file called 'actions/XXX.php'. This file, when called with the 
appropriate REQUEST parameters, will execute the specified action and then 
redirect the browser to the return page (specified in $_REQUEST["return"]
2) Extend the file 'actionlinkfactory.php' with one or more functions that
create customized links to that action page
3) include the actionlinkfactory in your page and call the appropriate method
to add a customized action link to your page.

As an example, take a look at the topic (un)subscription actions.

== actions/topicreview.php defines three possible actions. It is called with the 
following request parameters:
- $action (one of subscribe, subscriberecursive, unsubscribe (always recursive))
- $topic_id
- $person_id
- $return (the page to which the system should return after performing the action).

== actionlinkfactory.php contains three functions to create review links:
- function getTopicSubscribeLink($topic_id, $return)
- function getRecursiveTopicSubscribeLink($topic_id, $return)
- function getTopicUnsubscribeLink($topic_id, $return)
Those functions return a link (with image) to the action/topicreview.php that cause 
the current user to be (un)subscribed for the given topic, returning to the page 
specified in $return afterwards.

== These factory methods are for example used in the search page, where you can 
subscribe to the topics that have been found through a query, using the following
line:
echo getTopicSubscribeLink($topic_id, $URL."index.php?page=search&query=".$query);
Or in the main topic tree page, using $URL."index.php" as return page.
Or in the topic-review page, using $URL."index.php?page=topicreview" as return page.