flag.module in Flag 5
Same filename and directory in other branches
The Flag module.
File
flag.moduleView source
<?php
/**
* @file
* The Flag module.
*/
/**
* Implementation of hook_menu().
*/
function flag_menu($may_cache) {
$items = array();
if ($may_cache) {
$items[] = array(
'path' => 'admin/build/flags',
'title' => t('Flags'),
'callback' => 'flag_admin',
'callback arguments' => array(
'flag_admin_page',
),
'access' => user_access('administer flags'),
'description' => t('Configure flags for marking content with arbitary information (such as <em>offensive</em> or <em>bookmarked</em>).'),
'type' => MENU_NORMAL_ITEM,
);
$items[] = array(
'path' => 'admin/build/flags/edit',
'title' => t('Edit flags'),
'callback' => 'flag_admin',
'callback arguments' => array(
'drupal_get_form',
'flag_form',
),
'access' => user_access('administer flags'),
'type' => MENU_CALLBACK,
);
$items[] = array(
'path' => 'admin/build/flags/delete',
'title' => t('Delete flags'),
'callback' => 'flag_admin',
'callback arguments' => array(
'drupal_get_form',
'flag_delete_confirm',
),
'access' => user_access('administer flags'),
'type' => MENU_CALLBACK,
);
$items[] = array(
'path' => 'admin/build/flags/list',
'title' => t('List'),
'callback' => 'flag_admin',
'callback arguments' => array(
'flag_admin_page',
),
'access' => user_access('administer flags'),
'type' => MENU_DEFAULT_LOCAL_TASK,
'weight' => -1,
);
$items[] = array(
'path' => 'admin/build/flags/add',
'title' => t('Add'),
'callback' => 'flag_admin',
'callback arguments' => array(
'flag_add_page',
),
'access' => user_access('administer flags'),
'type' => MENU_LOCAL_TASK,
);
$items[] = array(
'path' => 'flag',
'title' => t('Flag'),
'callback' => 'flag_page',
'access' => user_access('access content'),
'type' => MENU_CALLBACK,
);
$items[] = array(
'path' => 'flag/confirm',
'title' => t('Flag confirm'),
'callback' => 'drupal_get_form',
'callback arguments' => array(
'flag_confirm',
),
'access' => user_access('access content'),
'type' => MENU_CALLBACK,
);
}
return $items;
}
/**
* Implementation of hook_init().
*/
function flag_init() {
// Only load for non-cached pages.
if (function_exists('drupal_set_content')) {
$path = drupal_get_path('module', 'flag');
include_once $path . '/flag.inc';
if (module_exists('views')) {
include_once $path . '/includes/flag.views.inc';
}
if (module_exists('actions')) {
include_once $path . '/includes/flag.actions.inc';
}
if (module_exists('token')) {
include_once $path . '/includes/flag.token.inc';
}
}
}
/**
* Implementation of hook_perm().
*/
function flag_perm() {
return array(
'administer flags',
);
}
/**
* Access checking to check an account for flagging ability.
*
* See documentation for $flag->user_access().
*/
function flag_access($flag, $account = NULL) {
return $flag
->user_access($account);
}
/**
* Content type checking to see if a flag applies to a certain type of data.
*
* @param $flag
* The flag object whose available types are being checked.
* @param $content_type
* The type of content being checked, usually "node".
* @param $content_subtype
* The subtype (node type) being checked.
*
* @return
* Boolean TRUE if the flag is enabled for this type and subtype.
* FALSE otherwise.
*/
function flag_content_enabled($flag, $content_type, $content_subtype = NULL) {
$return = $flag->content_type == $content_type && (!isset($content_subtype) || in_array($content_subtype, $flag->types));
return $return;
}
/**
* Implementation of hook_link().
*/
function flag_link($type, $object = NULL, $teaser = FALSE) {
if (!isset($object) || !flag_fetch_definition($type)) {
return;
}
global $user;
// Anonymous users can't create flags with this system.
if (!$user->uid) {
return;
}
// Get all possible flags for this content-type.
$flags = flag_get_flags($type);
foreach ($flags as $flag) {
if (!$flag
->user_access($user)) {
// User has no permission to use this flag.
continue;
}
if (!$flag
->uses_hook_link($teaser)) {
// Flag is not configured to show its link here.
continue;
}
if (!$flag
->applies_to_content_object($object)) {
// Flag does not apply to this content.
continue;
}
$content_id = $flag
->get_content_id($object);
// The flag links are actually fully rendered theme functions.
// The HTML attribute is set to TRUE to allow whatever the themer desires.
$links['flag-' . $flag->name] = array(
'title' => $flag
->theme($flag
->is_flagged($content_id) ? 'unflag' : 'flag', $content_id),
'html' => TRUE,
);
}
if (isset($links)) {
return $links;
}
}
/**
* Implementation of hook_flag_link().
*
* When Flag uses a link type provided by this module, it will call this
* implementation of hook_flag_link(). It returns a single link's attributes,
* using the same structure as hook_link(). Note that "title" is provided by
* the Flag configuration if not specified here.
*
* @param $flag
* The full flag object of for the flag link being generated.
* @param $action
* The action this link will perform. Either 'flag' or 'unflag'.
* @param $content_id
* The ID of the node, comment, user, or other object being flagged.
* @return
* An array defining properties of the link.
*/
function flag_flag_link(&$flag, $action, $content_id) {
$token = flag_get_token($content_id);
return array(
'href' => "flag/" . ($flag->link_type == 'confirm' ? 'confirm/' : '') . "{$action}/{$flag->name}/{$content_id}",
'query' => drupal_get_destination() . ($flag->link_type == 'confirm' ? '' : '&token=' . $token),
);
}
/**
* Implementation of hook_flag_link_types().
*/
function flag_flag_link_types() {
return array(
'toggle' => t('JavaScript toggle'),
'normal' => t('Normal link'),
'confirm' => t('Confirmation form'),
);
}
/**
* Implementation of hook_form_alter().
*/
function flag_form_alter($form_id, &$form) {
global $user;
if ($form_id == 'node_type_form') {
$flags = flag_get_flags('node', $form['#node_type']->type, $user);
foreach ($flags as $flag) {
if ($flag->show_on_form) {
$var = 'flag_' . $flag->name . '_default';
$form['workflow']['flag'][$var] = array(
'#type' => 'checkbox',
'#title' => $flag
->get_label('flag_short'),
'#default_value' => variable_get($var . '_' . $form['#node_type']->type, 0),
'#return_value' => 1,
);
}
}
if (isset($form['workflow']['flag'])) {
$form['workflow']['flag'] += array(
'#type' => 'item',
'#title' => t('Default flags'),
'#description' => t('Above are the <a href="@flag-url">flags</a> you elected to show on the node editing form. You may specify their initial state here.', array(
'@flag-url' => url('admin/build/flags'),
)),
// Make the spacing a bit more compact:
'#prefix' => '<div class="form-checkboxes">',
'#suffix' => '</div>',
);
}
}
elseif (isset($form['type']) && isset($form['#node']) && $form_id == $form['type']['#value'] . '_node_form') {
if (!$user->uid) {
return;
}
$nid = !empty($form['nid']['#value']) ? $form['nid']['#value'] : NULL;
$flags = flag_get_flags('node', $form['type']['#value'], $user);
// Filter out flags which need to be included on the node form.
foreach ($flags as $name => $flag) {
if (!$flag->show_on_form) {
unset($flags[$name]);
}
}
if (count($flags)) {
$form['flag'] = array(
'#type' => 'fieldset',
'#weight' => 1,
'#tree' => TRUE,
'#title' => t('Flags'),
'#collapsible' => TRUE,
);
}
foreach ($flags as $flag) {
if (isset($form['#node']->flag[$flag->name])) {
$flag_status = $form['#node']->flag[$flag->name];
}
else {
$flag_status_default = variable_get('flag_' . $flag->name . '_default_' . $form['type']['#value'], 0);
$flag_status = $nid ? $flag
->is_flagged($nid) : $flag_status_default;
}
$form['flag'][$flag->name] = array(
'#type' => 'checkbox',
'#title' => $flag
->get_label('flag_short', $nid),
'#description' => $flag
->get_label('flag_long', $nid),
'#default_value' => $flag_status,
'#return_value' => 1,
);
}
}
}
/**
* Implementation of hook_nodeapi().
*/
function flag_nodeapi(&$node, $op, $teaser = NULL, $page = NULL) {
global $user;
switch ($op) {
case 'update':
case 'insert':
// Response to the flag checkboxes added to the form in flag_form_alter().
$remembered = FALSE;
if (isset($node->flag)) {
foreach ($node->flag as $name => $state) {
$flag = flag_get_flag($name);
// Flagging may trigger actions. We want actions to get the current
// node, not a stale database-loaded one:
if (!$remembered) {
$flag
->remember_content($node->nid, $node);
// Actions may modify a node, and we don't want to overwrite this
// modification:
$remembered = TRUE;
}
flag($state ? 'flag' : 'unflag', $name, $node->nid);
}
}
break;
case 'delete':
foreach (flag_get_flags('node') as $flag) {
// If the flag is being tracked by translation set and the node is part
// of a translation set, don't delete the flagging record.
// Instead, data will be updated in the 'translation_change' op, below.
if (!$flag->i18n || empty($node->tnid)) {
db_query("DELETE FROM {flag_content} WHERE fid = %d AND content_id = %d", $flag->fid, $node->nid);
db_query("DELETE FROM {flag_counts} WHERE fid = %d AND content_id = %d", $flag->fid, $node->nid);
}
}
break;
case 'translation_change':
if (isset($node->translation_change)) {
// If there is only one node remaining, track by nid rather than tnid.
// Otherwise, use the new tnid.
$content_id = $node->translation_change['new_tnid'] == 0 ? $node->translation_change['remaining_nid'] : $node->translation_change['new_tnid'];
foreach (flag_get_flags('node') as $flag) {
if ($flag->i18n) {
db_query("UPDATE {flag_content} SET content_id = %d WHERE fid = %d AND content_id = %d", $content_id, $flag->fid, $node->translation_change['old_tnid']);
db_query("UPDATE {flag_counts} SET content_id = %d WHERE fid = %d AND content_id = %d", $content_id, $flag->fid, $node->translation_change['old_tnid']);
}
}
}
break;
}
}
/**
* Implementation of hook_user().
*/
function flag_user($op, &$edit, &$account, $category = NULL) {
switch ($op) {
case 'delete':
// Remove flags by this user.
$result = db_query("SELECT fc.fid, fc.content_id, c.count FROM {flag_content} fc LEFT JOIN {flag_counts} c ON fc.content_id = c.content_id AND fc.content_type = c.content_type WHERE fc.uid = %d", $account->uid);
while ($flag_data = db_fetch_object($result)) {
$flag_data->count--;
db_query("UPDATE {flag_counts} SET count = %d WHERE fid = %d AND content_id = %d", $flag_data->count, $flag_data->fid, $flag_data->content_id);
}
db_query("DELETE FROM {flag_content} WHERE uid = %d", $account->uid);
break;
case 'view':
$items = array();
$flags = flag_get_flags('user');
foreach ($flags as $flag) {
if (!$flag
->user_access()) {
// User has no permission to use this flag.
continue;
}
if (!$flag
->applies_to_content_object($account)) {
// Flag does not apply to this content.
continue;
}
if (!$flag
->uses_hook_link(array())) {
// Flag not set to appear on profile.
continue;
}
$items[t('Actions')] = array(
array(
'title' => $flag
->get_title($account->uid),
'value' => $flag
->theme($flag
->is_flagged($account->uid) ? 'unflag' : 'flag', $account->uid),
'class' => 'profile-' . $flag->name,
),
);
}
return $items;
}
}
/**
* Implementation of hook_node_type().
*/
function flag_node_type($op, $info) {
switch ($op) {
case 'delete':
// Remove entry from flaggable content types.
db_query("DELETE FROM {flag_types} WHERE type = '%s'", $info->type);
break;
}
}
/**
* Menu callback pass-through for all admin pages.
*/
function flag_admin() {
include_once drupal_get_path('module', 'flag') . '/includes/flag.admin.inc';
$args = func_get_args();
$function = array_shift($args);
return call_user_func_array($function, $args);
}
/**
* Menu callback for (un)flagging a node.
*
* Used both for the regular callback as well as the JS version.
*/
function flag_page($action, $flag_name, $content_id) {
$js = isset($_REQUEST['js']);
$token = $_REQUEST['token'];
// Check the flag token, then perform the flagging.
if (!flag_check_token($token, $content_id)) {
$error = t('Bad token. You seem to have followed an invalid link.');
}
else {
$result = flag($action, $flag_name, $content_id);
if (!$result) {
$error = t('You are not allowed to flag, or unflag, this content.');
}
}
// If an error was received, set a message and exit.
if (isset($error)) {
if ($js) {
drupal_set_header('Content-Type: text/javascript; charset=utf-8');
print drupal_to_js(array(
'status' => FALSE,
'errorMessage' => $error,
));
exit;
}
else {
drupal_set_message($error);
drupal_access_denied();
return;
}
}
// If successful, return data according to the request type.
if ($js) {
drupal_set_header('Content-Type: text/javascript; charset=utf-8');
$flag = flag_get_flag($flag_name);
$flag->link_type = 'toggle';
print drupal_to_js(array(
'status' => TRUE,
'newLink' => $flag
->theme($flag
->is_flagged($content_id) ? 'unflag' : 'flag', $content_id, TRUE),
// Further information for the benefit of custom JavaScript event handlers:
'contentId' => $content_id,
'contentType' => $flag->content_type,
'flagName' => $flag->name,
'flagStatus' => $flag
->is_flagged($content_id) ? 'flagged' : 'unflagged',
));
exit;
}
else {
$flag = flag_get_flag($flag_name);
drupal_set_message($flag
->get_label($action . '_message', $content_id));
drupal_goto();
}
}
/**
* Form for confirming the (un)flagging of a piece of content.
*/
function flag_confirm($action = 'flag', $flag_name, $content_id = '') {
$form = array();
$form['action'] = array(
'#type' => 'value',
'#value' => $action,
);
$form['flag_name'] = array(
'#type' => 'value',
'#value' => $flag_name,
);
$form['content_id'] = array(
'#type' => 'value',
'#value' => $content_id,
);
$flag = flag_get_flag($flag_name);
$question = $flag
->get_label($action . '_confirmation', $content_id);
$path = isset($_GET['destination']) ? $_GET['destination'] : '<front>';
$yes = $flag
->get_label($action . '_short', $content_id);
return confirm_form($form, $question, $path, '', $yes);
}
function flag_confirm_submit($form_id, $form_values) {
$action = $form_values['action'];
$flag_name = $form_values['flag_name'];
$content_id = $form_values['content_id'];
$result = flag($action, $flag_name, $content_id);
if (!$result) {
drupal_set_message(t('You are not allowed to flag, or unflag, this content.'));
}
else {
$flag = flag_get_flag($flag_name);
drupal_set_message($flag
->get_label($action . '_message', $content_id));
}
}
/**
* Flags or unflags an item.
*
* @param $account
* The user on whose behalf to flag. Leave empty for the current user.
* @return
* FALSE if some error occured (e.g., user has no permission, flag isn't
* applicable to the item, etc.), TRUE otherwise.
*/
function flag($action, $flag_name, $content_id, $account = NULL) {
if (!($flag = flag_get_flag($flag_name))) {
// Flag does not exist.
return FALSE;
}
return $flag
->flag($action, $content_id, $account);
}
/**
* Implementation of hook_flag(). Trigger actions if any are available.
*/
function flag_flag($action, $flag, $content_id, $account) {
if (module_exists('actions') && function_exists('_actions_get_hook_aids')) {
$flag_action = $flag
->get_flag_action($content_id);
$flag_action->action = $action;
$context = (array) $flag_action;
$aids = _actions_get_hook_aids($action, $action);
foreach ($aids as $aid => $action_info) {
// The 'if ($aid)' is a safeguard against http://drupal.org/node/271460#comment-886564
if ($aid) {
actions_do($aid, $flag, $context);
}
}
}
if (module_exists('rules')) {
$event_name = ($action == 'flag' ? 'flag_flagged_' : 'flag_unflagged_') . $flag->name;
$arguments = array(
'flag' => $flag,
'flag_content_id' => $content_id,
'flagging_user' => $account,
);
rules_invoke_event($event_name, $arguments);
}
}
/**
* Implementation of hook_node_operations().
*
* Add additional options on the admin/build/node page.
*/
function flag_node_operations() {
global $user;
$flags = flag_get_flags('node', NULL, $user);
$operations = array();
foreach ($flags as $flag) {
$operations['flag_' . $flag->name] = array(
'label' => $flag
->get_label('flag_short'),
'callback' => 'flag_nodes',
'callback arguments' => array(
'flag',
$flag->name,
),
'behavior' => array(),
);
$operations['unflag_' . $flag->name] = array(
'label' => $flag
->get_label('unflag_short'),
'callback' => 'flag_nodes',
'callback arguments' => array(
'unflag',
$flag->name,
),
'behavior' => array(),
);
}
return $operations;
}
/**
* Callback function for hook_node_operations().
*/
function flag_nodes($nodes, $action, $flag_name) {
foreach ($nodes as $nid) {
flag($action, $flag_name, $nid);
}
}
/**
* Theme an individual link and a message after the link is marked.
*
* @param $flag
* The flag object.
* @param $action
* Which link to show: either "flag" or "unflag".
* @param $content_id
* The ID of the content being flagged.
* @param $after_flagging
* This function is called for both the link both before and after being
* flagged. If displaying to the user immediately after flagging, this value
* will be boolean TRUE. This is usually used in conjunction with immedate
* JavaScript-based toggling of flags.
*/
function theme_flag($flag, $action, $content_id, $after_flagging = FALSE) {
static $template;
if (!isset($template)) {
$template = './' . drupal_get_path('module', 'flag') . '/theme/flag.tpl.php';
}
$variables = array(
'flag' => $flag,
'action' => $action,
'content_id' => $content_id,
'after_flagging' => $after_flagging,
);
flag_template_preprocess('flag', $variables);
extract($variables);
ob_start();
include $template;
$output = ob_get_contents();
ob_end_clean();
// Unfortunately, the antique jQuery shipped with Drupal 5 has a bug: the
// expression $('<tag>something</tag>') fails is 'something' contains a
// newline. That's because jQuery's source has:
//
// // Handle HTML strings
// if ( typeof a == "string" ) {
// var m = /^[^<]*(<.+>)[^>]*$/.exec(a);
// if ( m ) a = jQuery.clean( [ m[1] ] );
// }
//
// Note the "<.+>", which doesn't match newlines. In newer jQuery's that
// expression was changed to:
//
// var quickExpr = /^[^<]*(<(.|\s)+>)[^>]*$|^#(\w+)$/
//
// Note the \s which does match newlines.
//
// So we have to remove all newlines:
$output = strtr($output, "\r\n", ' ');
return $output;
}
/**
* A preprocess function for our theme('flag'). It generates the
* variables needed there.
*
* See 'flag.tpl.php' for documentation for these variables.
*
* Note: The Drupal 5 version of this module calls this function directly.
*/
function template_preprocess_flag(&$variables) {
static $first_time = TRUE;
// Some typing shotcuts:
$flag =& $variables['flag'];
$action = $variables['action'];
$content_id = $variables['content_id'];
// Generate the link URL.
$link_types = flag_get_link_types();
$link_type_module = $link_types[$flag->link_type]['module'];
$link = module_invoke($link_type_module, 'flag_link', $flag, $action, $content_id);
if (isset($link['title']) && empty($link['html'])) {
$link['title'] = check_plain($link['title']);
}
if ($flag->link_type == 'toggle' && $first_time) {
$variables['setup'] = $first_time;
$first_time = FALSE;
}
else {
$variables['setup'] = FALSE;
}
$variables['link_href'] = check_url(url($link['href'], $link['query'], $link['fragment']));
$variables['link_text'] = isset($link['title']) ? $link['title'] : strip_tags($flag
->get_label($action . '_short', $content_id), '<em><strong><img>');
$variables['link_title'] = isset($link['attributes']['title']) ? check_plain($link['attributes']['title']) : check_plain(strip_tags($flag
->get_label($action . '_long', $content_id)));
$variables['flag_name_css'] = str_replace('_', '-', $flag->name);
$variables['last_action'] = $action == 'flag' ? 'unflagged' : 'flagged';
$variables['flag_classes_array'] = array();
$variables['flag_classes_array'][] = 'flag';
$variables['flag_classes_array'][] = $variables['action'] . '-action';
$variables['flag_classes_array'][] = 'flag-link-' . $flag->link_type;
if (isset($link['attributes']['class'])) {
$variables['flag_classes_array'][] = $link['attributes']['class'];
}
if ($variables['after_flagging']) {
$inverse_action = $action == 'flag' ? 'unflag' : 'flag';
$variables['message_text'] = $flag
->get_label($inverse_action . '_message', $content_id);
$variables['flag_classes_array'][] = $variables['last_action'];
}
$variables['flag_classes'] = implode(' ', $variables['flag_classes_array']);
}
/**
* In Drupal 5 it is possible to put a phptemplate_flag() function in your
* 'template.php', and within that function instructions to make Drupal scan
* for various template files for theming a flag.
*
* The syntax for that phptemplate_flag() is somewhat arcane --and may need
* updating when our API changes-- so here we provide a ready-made version of
* that funtion. You should call it from your phptemplate_flag(). See
* 'theme/README.txt'.
*/
function flag_phptemplate_adapter($flag, $action, $content_id, $after_flagging = FALSE) {
// Prepare the variables to be available in the template.
$variables = array(
'flag' => $flag,
'action' => $action,
'content_id' => $content_id,
'after_flagging' => $after_flagging,
);
flag_template_preprocess('flag', $variables);
// Prepare an array of suggested templates to try.
$suggestions = array();
foreach ($flag
->theme_suggestions() as $suggestion) {
$suggestions[] = str_replace('_', '-', $suggestion);
}
$suggestions = array_reverse($suggestions);
// Hand control to the phptemplate engine.
$output = _phptemplate_callback('flag', $variables, $suggestions);
// Finally, handle Drupal 5's jQuery bug. See explanation in theme_flag().
$output = strtr($output, "\r\n", ' ');
return $output;
}
/**
* Call module flag preprocess functions for Drupal 5.
*
* The preprocess functions for themes and phptemplate can be done in
* _phptemplate_variables(), but this adds preprocessing to modules that don't
* have this access in Drupal 5.
*
* @param $hook
* The name of the template file hook whose variables are being preprocessed.
* @param $variables
* The existing variables that will be passed to the template file.
*/
function flag_template_preprocess($hook, &$variables) {
if (function_exists('template_preprocess_' . $hook)) {
$function = 'template_preprocess_' . $hook;
$function($variables);
}
foreach (module_implements('preprocess_' . $hook) as $module) {
$function = $module . '_preprocess_' . $hook;
$function($variables);
}
}
/**
* Format a string containing a count of items.
*
* _flag_format_plural() is a version of format_plural() which
* accepts the format string as a single argument, where the singular and
* plural forms are separated by pipe. A 'zero' form is allowed as well.
*
* _flag_format_plural() is used where we want the admin, not the
* programmer, to be able to nicely and easily format a number.
*
* If three forms are provided, separated by pipes, then the first is
* considered the zero form and is used if $count is 0. The zero form may
* well be an empty string.
*
* @param $count
* The item count to display.
* @param $format
* The singular, plural, and optionally the zero, forms separated
* by pipe characters.
* @return
* A formatted, translated string.
*
* Examples for $format:
*
* @code
* "@count"
* "1 vote|@count votes"
* "needs voting|1 vote|@count votes"
* "|1 vote|@count votes"
* "|@count|@count"
* @endcode
*/
function _flag_format_plural($count, $format) {
$elements = explode('|', $format ? $format : '@count', 3);
if (count($elements) == 3) {
list($zero, $singular, $plural) = $elements;
}
elseif (count($elements) == 2) {
list($singular, $plural) = $elements;
$zero = NULL;
}
else {
// count($elements) == 1
$singular = $plural = $elements[0];
$zero = NULL;
}
if (isset($zero) && intval($count) == 0) {
return $zero;
}
else {
return format_plural(intval($count), $singular, $plural);
}
}
/**
* Return an array of flag names keyed by fid.
*/
function _flag_get_flag_names() {
$flags = flag_get_flags();
$flag_names = array();
foreach ($flags as $flag) {
$flag_names[$flag->fid] = $flag->name;
}
return $flag_names;
}
/**
* Return an array of flag link types suitable for a select list or radios.
*/
function _flag_link_type_options() {
$options = array();
$types = flag_get_link_types();
foreach ($types as $type_name => $type) {
$options[$type_name] = $type['title'];
}
return $options;
}
// ---------------------------------------------------------------------------
// Non-Views public API
/**
* Get flag counts for all flags on a node.
*
* @param $content_type
* The content type (usually 'node').
* @param $content_id
* The content ID (usually the node ID).
* @param $reset
* Reset the internal cache and execute the SQL query another time.
*
* @return $flags
* An array of the structure [name] => [number of flags].
*/
function flag_get_counts($content_type, $content_id, $reset = FALSE) {
static $counts;
if ($reset) {
$counts = array();
if (!isset($content_type)) {
return;
}
}
if (!isset($counts[$content_type][$content_id])) {
$counts[$content_type][$content_id] = array();
$result = db_query("SELECT f.name, fc.count FROM {flags} f LEFT JOIN {flag_counts} fc ON f.fid = fc.fid WHERE fc.content_type = '%s' AND fc.content_id = %d", $content_type, $content_id);
while ($row = db_fetch_object($result)) {
$counts[$content_type][$content_id][$row->name] = $row->count;
}
}
return $counts[$content_type][$content_id];
}
/**
* Load a single flag either by name or by flag ID.
*
* @param $name
* The the flag name.
* @param $fid
* The the flag id.
*/
function flag_get_flag($name = NULL, $fid = NULL) {
$flags = flag_get_flags();
if (isset($name)) {
if (isset($flags[$name])) {
return $flags[$name];
}
}
elseif (isset($fid)) {
foreach ($flags as $flag) {
if ($flag->fid == $fid) {
return $flag;
}
}
}
}
/**
* List all flags available.
*
* If node type or account are entered, a list of all possible flags will be
* returned.
*
* @param $content_type
* Optional. The type of content for which to load the flags. Usually 'node'.
* @param $content_subtype
* Optional. The node type for which to load the flags.
* @param $account
* Optional. The user accont to filter available flags. If not set, all
* flags for will this node will be returned.
* @param $reset
* Optional. Reset the internal query cache.
*
* @return $flags
* An array of the structure [fid] = flag_object.
*/
function flag_get_flags($content_type = NULL, $content_subtype = NULL, $account = NULL, $reset = FALSE) {
static $flags;
// Retrieve a list of all flags, regardless of the parameters.
if (!isset($flags) || $reset) {
$flags = array();
// Database flags.
$result = db_query("SELECT f.*, fn.type FROM {flags} f LEFT JOIN {flag_types} fn ON fn.fid = f.fid");
while ($row = db_fetch_object($result)) {
if (!isset($flags[$row->name])) {
$flags[$row->name] = flag_flag::factory_by_row($row);
}
else {
$flags[$row->name]->types[] = $row->type;
}
}
// Add code-based flags provided by modules.
$default_flags = flag_get_default_flags();
foreach ($default_flags as $name => $default_flag) {
// Insert new enabled flags into the database to give them an FID.
if ($default_flag->status && !isset($flags[$name])) {
$default_flag
->save();
$flags[$name] = $default_flag;
}
if (isset($flags[$name])) {
// Ensure overridden flags are associated with their parent module.
$flags[$name]->module = $default_flag->module;
// Update the flag with any properties that are "locked" by the code version.
if (isset($default_flag->locked)) {
$flags[$name]->locked = $default_flag->locked;
foreach ($default_flag->locked as $property) {
$flags[$name]->{$property} = $default_flag->{$property};
}
}
}
}
}
// Make a variable copy to filter types and account.
$filtered_flags = $flags;
// Filter out flags based on type and subtype.
if (isset($content_type) || isset($content_subtype)) {
foreach ($filtered_flags as $name => $flag) {
if (!flag_content_enabled($flag, $content_type, $content_subtype)) {
unset($filtered_flags[$name]);
}
}
}
// Filter out flags based on account permissions.
if (isset($account) && $account->uid != 1) {
foreach ($filtered_flags as $name => $flag) {
if (!flag_access($flag, $account)) {
unset($filtered_flags[$name]);
}
}
}
return $filtered_flags;
}
/**
* Retrieve a list of flags defined by modules.
*
* @param $include_disabled
* Unless specified, only enabled flags will be returned.
* @return
* An array of flag prototypes, not usable for flagging. Use flag_get_flags()
* if needing to perform a flagging with any enabled flag.
*/
function flag_get_default_flags($include_disabled = FALSE) {
$default_flags = array();
$flag_status = variable_get('flag_default_flag_status', array());
foreach (module_implements('flag_default_flags') as $module) {
$function = $module . '_flag_default_flags';
foreach ($function() as $config) {
$flag = flag_flag::factory_by_array($config);
$flag->module = $module;
// Add flags that have been enabled.
if (!isset($flag_status[$flag->name]) && (!isset($flag->status) || $flag->status) || !empty($flag_status[$flag->name])) {
$flag->status = TRUE;
$default_flags[$flag->name] = $flag;
}
elseif ($include_disabled) {
$flag->status = FALSE;
$default_flags[$flag->name] = $flag;
}
}
}
return $default_flags;
}
/**
* Find what a user has flagged, either a single node or on the entire site.
*
* @param $content_type
* The type of content that will be retrieved. Usually 'node'.
* @param $content_id
* Optional. The content ID to check for flagging. If none given, all
* content flagged by this user will be returned.
* @param $uid
* Optional. The user ID whose flags we're checking. If none given, the
* current user will be used.
* @param $reset
* Reset the internal cache and execute the SQL query another time.
*
* @return $flags
* If returning a single node's flags, an array of the structure
* [flag_name] => (fcid => [fcid], uid => [uid], content_id => [content_id], timestamp => [timestamp], ...)
*
* If returning all nodes, an array of arrays for each flag:
* [flag_name] => [content_id] => Object from above.
*
*/
function flag_get_user_flags($content_type, $content_id = NULL, $uid = NULL, $reset = FALSE) {
static $flagged_content;
if ($reset) {
$flagged_content = array();
if (!isset($content_type)) {
return;
}
}
$uid = !isset($uid) ? $GLOBALS['user']->uid : $uid;
if (isset($content_id)) {
if (!isset($flagged_content[$uid][$content_type][$content_id])) {
$flag_names = _flag_get_flag_names();
$flagged_content[$uid][$content_type][$content_id] = array();
$result = db_query("SELECT * FROM {flag_content} WHERE content_type = '%s' AND content_id = %d AND (uid = %d OR uid = 0)", $content_type, $content_id, $uid);
while ($flag_content = db_fetch_object($result)) {
$flagged_content[$uid][$content_type][$content_id][$flag_names[$flag_content->fid]] = $flag_content;
}
}
return $flagged_content[$uid][$content_type][$content_id];
}
else {
if (!isset($flagged_content[$uid][$content_type]['all'])) {
$flag_names = _flag_get_flag_names();
$flagged_content[$uid][$content_type]['all'] = array();
$result = db_query("SELECT * FROM {flag_content} WHERE content_type = '%s' AND (uid = %d OR uid = 0)", $content_type, $uid);
while ($flag_content = db_fetch_object($result)) {
$flagged_content[$uid][$content_type]['all'][$flag_names[$flag_content->fid]][$flag_content->content_id] = $flag_content;
}
}
return $flagged_content[$uid][$content_type]['all'];
}
}
/**
* Return a list of users who have flagged a piece of content.
*/
function flag_get_content_flags($content_type, $content_id, $reset = FALSE) {
static $content_flags;
if (!isset($content_flags[$content_type][$content_id]) || $reset) {
$flag_names = _flag_get_flag_names();
$result = db_query("SELECT * FROM {flag_content} WHERE content_type = '%s' AND content_id = %d ORDER BY timestamp DESC", $content_type, $content_id);
while ($flag_content = db_fetch_object($result)) {
$content_flags[$content_type][$content_id]['users'][$flag_content->uid][$flag_names[$flag_content->fid]] = $flag_content;
}
}
return $content_flags[$content_type][$content_id]['users'];
}
/**
* A utility function for outputting a flag link.
*
* You should call this function from your template when you want to put the
* link on the page yourself. For example, you could call this function from
* your 'node.tpl.php':
*
* <?php print flag_create_link('bookmarks', $node->nid); ?>
*
* @param $flag_name
* The "machine readable" name of the flag; e.g. 'bookmarks'.
* @param $content_id
* The content ID to check for flagging. This is usually a node ID.
*/
function flag_create_link($flag_name, $content_id) {
$flag = flag_get_flag($flag_name);
if (!$flag) {
// Flag does not exist.
return;
}
if (!$flag
->user_access()) {
// User has no permission to use this flag.
return;
}
if (!$flag
->applies_to_content_id($content_id)) {
// Flag does not apply to this content.
return;
}
return $flag
->theme($flag
->is_flagged($content_id) ? 'unflag' : 'flag', $content_id);
}
/**
* Return an array of link types provided by modules.
*/
function flag_get_link_types($reset = FALSE) {
static $link_types;
if (!isset($link_types) || $reset) {
$link_types = array();
foreach (module_implements('flag_link_types') as $module) {
$module_types = module_invoke($module, 'flag_link_types');
foreach ($module_types as $type_name => $type_title) {
$link_types[$type_name] = array(
'module' => $module,
'title' => $type_title,
);
}
}
}
return $link_types;
}
/**
* Get a private token used to protect links from spoofing - CSRF.
*/
function flag_get_token($nid) {
return drupal_get_token($nid);
}
/**
* Check to see if a token value matches the specified node.
*/
function flag_check_token($token, $seed) {
return drupal_get_token($seed) == $token;
}Functions
Name |
Description |
|---|---|
| flag | Flags or unflags an item. |
| flag_access | Access checking to check an account for flagging ability. |
| flag_admin | Menu callback pass-through for all admin pages. |
| flag_check_token | Check to see if a token value matches the specified node. |
| flag_confirm | Form for confirming the (un)flagging of a piece of content. |
| flag_confirm_submit | |
| flag_content_enabled | Content type checking to see if a flag applies to a certain type of data. |
| flag_create_link | A utility function for outputting a flag link. |
| flag_flag | Implementation of hook_flag(). Trigger actions if any are available. |
| flag_flag_link | Implementation of hook_flag_link(). |
| flag_flag_link_types | Implementation of hook_flag_link_types(). |
| flag_form_alter | Implementation of hook_form_alter(). |
| flag_get_content_flags | Return a list of users who have flagged a piece of content. |
| flag_get_counts | Get flag counts for all flags on a node. |
| flag_get_default_flags | Retrieve a list of flags defined by modules. |
| flag_get_flag | Load a single flag either by name or by flag ID. |
| flag_get_flags | List all flags available. |
| flag_get_link_types | Return an array of link types provided by modules. |
| flag_get_token | Get a private token used to protect links from spoofing - CSRF. |
| flag_get_user_flags | Find what a user has flagged, either a single node or on the entire site. |
| flag_init | Implementation of hook_init(). |
| flag_link | Implementation of hook_link(). |
| flag_menu | Implementation of hook_menu(). |
| flag_nodeapi | Implementation of hook_nodeapi(). |
| flag_nodes | Callback function for hook_node_operations(). |
| flag_node_operations | Implementation of hook_node_operations(). |
| flag_node_type | Implementation of hook_node_type(). |
| flag_page | Menu callback for (un)flagging a node. |
| flag_perm | Implementation of hook_perm(). |
| flag_phptemplate_adapter | In Drupal 5 it is possible to put a phptemplate_flag() function in your 'template.php', and within that function instructions to make Drupal scan for various template files for theming a flag. |
| flag_template_preprocess | Call module flag preprocess functions for Drupal 5. |
| flag_user | Implementation of hook_user(). |
| template_preprocess_flag | A preprocess function for our theme('flag'). It generates the variables needed there. |
| theme_flag | Theme an individual link and a message after the link is marked. |
| _flag_format_plural | Format a string containing a count of items. |
| _flag_get_flag_names | Return an array of flag names keyed by fid. |
| _flag_link_type_options | Return an array of flag link types suitable for a select list or radios. |