Documentation: actions/actions.php

Class Actions - The database abstraction layer for actions

Actions are like post-it notes, or reminders. They are a very straightforward way of managing short-lived and task-oriented items of information.

The life cycle of an action is quite simple. An action is created, then closed. An action record is created when some community member is tasked to do something. Like for paper reminders, you can create actions for yourself or for others. Then actions can be either rejected or completed by the person to which they have been assigned.

While being really simplistic, this implementation of actions is quite enough to support following patterns of workflow:

* sticky notes - Any member may create, edit, and accept action records for his own eyes. On-going actions are listed at login time, and this proves to be an efficient way to remind things to do. New actions can be created from the user profile. Click on 'My Page' once authenticated.

* team working - Since YACS is intended to support communities, it is likely that several associates will have to collaborate. By posting actions to a peer, any associate may ask another person to contribute explicitly. The tasked person will be warned of the new action by e-mail, and also on the next authentication to the web site.

* automatic triggers - Ultimately, actions can be triggered by another YACS module on specific events. For example, you may have created a PHP script that tracks important information. You can use actions to submit the outcome of this script to some human being for further processing.

Every action record has following attributes:

an anchor - usually, some user profile
a title and a description
an optional target designation - usually, the URL of another page
a status that can be: 'on-going', 'completed' or 'rejected'
dates of creation and last modification are recorded as well

This script is a reference file of this system.

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com
Florent

accept() - Accept an action

function accept($id, $status = 'on-going')

$id - int the id of the item to accept
$status = 'on-going' - string the new status

The new status can be either:

'on-going' - the action has been started
'completed' - nothing more to do
'rejected' - the task has been cancelled for some reason

The name of the surfer and the modification date is recorded as well.

Voir aussi:

actions/accept.php

delete() - Delete one action in the database and in the file system

function delete($id)

$id - the id of the action to delete
returns an error message, if any

delete_for_anchor() - Delete all actions for a given anchor

function delete_for_anchor($anchor)

$anchor - the anchor to check

get() - Get one action by id

function &get($id)

$id - int the id of the action
returns the resulting $item array, with at least keys: 'id', 'title', etc.

get_next_url() - Get id of next action

function get_next_url($item, $anchor, $order='date', $capability='?')

$item - array the current item
$anchor - string the anchor of the current item
$order='date' - string the order, either 'date' or 'reverse'
$capability='?' - string surfer actual capability ('?', 'M', or 'A')
returns some text

This function is used to build navigation bars.

Voir aussi:

articles/article.php

get_previous_url() - Get id of previous action

function get_previous_url($item, $anchor, $order='date', $capability='?')

$item - array the current item
$anchor - string the anchor of the current item
$order='date' - string the order, either 'date' or 'reverse'
$capability='?' - string surfer actual capability ('?', 'M', or 'A')
returns some text

This function is used to build navigation bars.

Voir aussi:

articles/article.php

get_url() - Get the url to view an action

function get_url($id, $action='view')

$id - int the id of the action to view
$action='view' - string the expected action ('view', 'edit', 'delete', ...)
returns an anchor to the viewing script

By default, a relative URL will be provided (e.g. 'actions/view.php?id=512'), which may be not processed correctly by search engines. If the parameter 'with_friendly_urls' has been set to 'Y' in the configuration panel, this function will return an URL parsable by search engines (e.g. 'actions/view.php/512').

Voir aussi:

control/configure.php

list_by_date() - List newest actions

function &list_by_date($offset=0, $count=10, $variant='full')

$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=10 - int the number of items to display
$variant='full' - string the list variant, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

list_by_date_for_anchor() - List newest on-going actions for one anchor

function &list_by_date_for_anchor($anchor, $offset=0, $count=20, $variant=NULL)

$anchor - string the anchor (e.g., 'user:123')
$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=20 - int the number of items to display
$variant=NULL - string the list variant, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

list_by_date_for_author() - List newest actions for one author

function &list_by_date_for_author($author_id, $offset=0, $count=20, $variant='date')

$author_id - int the id of the author of the action
$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=20 - int the number of items to display
$variant='date' - string the list variant, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Example:

include_once 'actions/actions.php';
$items = actions::list_by_date_for_author(0, COMPACT_LIST_SIZE, '', 12);
$context['text'] .= Skin::build_list($items, 'compact');

list_completed_for_anchor() - List newest completed actions for one anchor

function &list_completed_for_anchor($anchor, $offset=0, $count=20, $variant=NULL)

$anchor - string the anchor (e.g., 'user:123')
$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=20 - int the number of items to display
$variant=NULL - string the list variant, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

list_rejected_for_anchor() - List newest rejected actions for one anchor

function &list_rejected_for_anchor($anchor, $offset=0, $count=20, $variant=NULL)

$anchor - string the anchor (e.g., 'user:123')
$offset=0 - int the offset from the start of the list; usually, 0 or 1
$count=20 - int the number of items to display
$variant=NULL - string the list variant, if any
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

list_selected() - List selected actions

function &list_selected(&$result, $layout='compact', $capability='?')

&$result - resource result of database query
$layout='compact' - string 'full', etc or object, i.e., an instance of Layout_Interface
$capability='?' - string '?' or 'A', to support editors and to impersonate associates, where applicable
returns NULL on error, else an ordered array with $url => ($prefix, $label, $suffix, $icon)

Accept following variants:

'compact' - to build short lists in boxes and sidebars (this is the default)
'no_anchor' - to build detailed lists in an anchor page
'full' - include anchor information

post() - Post a new action or an updated action

function post($fields)

$fields - array an array of fields

setup() - Create or alter tables for actions

function setup()

stat() - Get some statistics

function &stat()

returns the resulting ($count, $min_date, $max_date) array

stat_for_anchor() - Get some statistics for one anchor

function &stat_for_anchor($anchor)

$anchor - the selected anchor (e.g., 'article:12')
returns the resulting ($count, $min_date, $max_date) array

We are computing this only for completed actions, since on-going and rejected actions should be kept to a minimum.

Voir aussi:

actions/list.php