Drupal
/
drupal
mirror of https://git.drupalcode.org/project/drupal.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Issue #1357138 by jstoller, xenophyle: Clean up API docs for Forum module

8.0.x
Jennifer Hodgdon 2012-06-13 14:09:45 -07:00
parent 4759212091
commit 0da848d52c
12 changed files with 340 additions and 162 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
core/modules/forum/forum-icon.tpl.php
View File

@ -2,7 +2,7 @@
/** /**
* @file * @file
* Default theme implementation to display an appropriate icon for a forum post. * Displays an appropriate icon for a forum post.
* *
* Available variables: * Available variables:
* - $new_posts: Indicates whether or not the topic contains new posts. * - $new_posts: Indicates whether or not the topic contains new posts.
@ -12,6 +12,8 @@
* *
* @see template_preprocess_forum_icon() * @see template_preprocess_forum_icon()
* @see theme_forum_icon() * @see theme_forum_icon()
*
* @ingroup themeable
*/ */
?> ?>
<div class="topic-status-<?php print $icon_class ?>" title="<?php print $icon_title ?>"> <div class="topic-status-<?php print $icon_class ?>" title="<?php print $icon_title ?>">

45
core/modules/forum/forum-list.tpl.php
View File

@ -2,34 +2,35 @@
/** /**
* @file * @file
* Default theme implementation to display a list of forums and containers. * Displays a list of forums and containers.
* *
* Available variables: * Available variables:
* - $forums: An array of forums and containers to display. It is keyed to the * - $forums: An array of forums and containers to display. It is keyed to the
* numeric id's of all child forums and containers. * numeric IDs of all child forums and containers. Each $forum in $forums
* - $forum_id: Forum id for the current forum. Parent to all items within * contains:
* the $forums array. * - $forum->is_container: TRUE if the forum can contain other forums. FALSE
* * if the forum can contain only topics.
* Each $forum in $forums contains: * - $forum->depth: How deep the forum is in the current hierarchy.
* - $forum->is_container: Is TRUE if the forum can contain other forums. Is * - $forum->zebra: 'even' or 'odd' string used for row class.
* FALSE if the forum can contain only topics. * - $forum->icon_class: 'default' or 'new' string used for forum icon class.
* - $forum->depth: How deep the forum is in the current hierarchy. * - $forum->icon_title: Text alternative for the forum icon.
* - $forum->zebra: 'even' or 'odd' string used for row class. * - $forum->name: The name of the forum.
* - $forum->icon_class: 'default' or 'new' string used for forum icon class. * - $forum->link: The URL to link to this forum.
* - $forum->icon_title: Text alternative for the forum icon. * - $forum->description: The description of this forum.
* - $forum->name: The name of the forum. * - $forum->new_topics: TRUE if the forum contains unread posts.
* - $forum->link: The URL to link to this forum. * - $forum->new_url: A URL to the forum's unread posts.
* - $forum->description: The description of this forum. * - $forum->new_text: Text for the above URL, which tells how many new posts.
* - $forum->new_topics: True if the forum contains unread posts. * - $forum->old_topics: A count of posts that have already been read.
* - $forum->new_url: A URL to the forum's unread posts. * - $forum->num_posts: The total number of posts in the forum.
* - $forum->new_text: Text for the above URL which tells how many new posts. * - $forum->last_reply: Text representing the last time a forum was posted or
* - $forum->old_topics: A count of posts that have already been read. * commented in.
* - $forum->num_posts: The total number of posts in the forum. * - $forum_id: Forum ID for the current forum. Parent to all items within the
* - $forum->last_reply: Text representing the last time a forum was posted or * $forums array.
* commented in.
* *
* @see template_preprocess_forum_list() * @see template_preprocess_forum_list()
* @see theme_forum_list() * @see theme_forum_list()
*
* @ingroup themeable
*/ */
?> ?>
<table id="forum-<?php print $forum_id; ?>"> <table id="forum-<?php print $forum_id; ?>">

4
core/modules/forum/forum-rtl.css
View File

@ -1,3 +1,7 @@
/**
* @file
* Right-to-left styling for the Forum module.
*/
#forum td.forum .icon { #forum td.forum .icon {
float: right; float: right;

12
core/modules/forum/forum-submitted.tpl.php
View File

@ -2,18 +2,20 @@
/** /**
* @file * @file
* Default theme implementation to format a simple string indicated when and * Formats a forum post submission string.
* by whom a topic was submitted. *
* The submission string indicates when and by whom a topic was submitted.
* *
* Available variables: * Available variables:
*
* - $author: The author of the post. * - $author: The author of the post.
* - $time: How long ago the post was created. * - $time: How long ago the post was created.
* - $topic: An object with the raw data of the post. Unsafe, be sure * - $topic: An object with the raw data of the post. Potentially unsafe. Be
* to clean this data before printing. * sure to clean this data before printing.
* *
* @see template_preprocess_forum_submitted() * @see template_preprocess_forum_submitted()
* @see theme_forum_submitted() * @see theme_forum_submitted()
*
* @ingroup themeable
*/ */
?> ?>
<?php if ($time): ?> <?php if ($time): ?>

44
core/modules/forum/forum-topic-list.tpl.php
View File

@ -2,35 +2,39 @@
/** /**
* @file * @file
* Default theme implementation to display a list of forum topics. * Displays a list of forum topics.
* *
* Available variables: * Available variables:
* - $header: The table header. This is pre-generated with click-sorting * - $header: The table header. This is pre-generated with click-sorting
* information. If you need to change this, see * information. If you need to change this, see
* template_preprocess_forum_topic_list(). * template_preprocess_forum_topic_list().
* - $pager: The pager to display beneath the table. * - $pager: The pager to display beneath the table.
* - $topics: An array of topics to be displayed. * - $topics: An array of topics to be displayed. Each $topic in $topics
* - $topic_id: Numeric id for the current forum topic. * contains:
* * - $topic->icon: The icon to display.
* Each $topic in $topics contains: * - $topic->moved: A flag to indicate whether the topic has been moved to
* - $topic->icon: The icon to display. * another forum.
* - $topic->moved: A flag to indicate whether the topic has been moved to * - $topic->title: The title of the topic. Safe to output.
* another forum. * - $topic->message: If the topic has been moved, this contains an
* - $topic->title: The title of the topic. Safe to output. * explanation and a link.
* - $topic->message: If the topic has been moved, this contains an * - $topic->zebra: 'even' or 'odd' string used for row class.
* explanation and a link. * - $topic->comment_count: The number of replies on this topic.
* - $topic->zebra: 'even' or 'odd' string used for row class. * - $topic->new_replies: A flag to indicate whether there are unread
* - $topic->comment_count: The number of replies on this topic. * comments.
* - $topic->new_replies: A flag to indicate whether there are unread comments. * - $topic->new_url: If there are unread replies, this is a link to them.
* - $topic->new_url: If there are unread replies, this is a link to them. * - $topic->new_text: Text containing the translated, properly pluralized
* - $topic->new_text: Text containing the translated, properly pluralized count. * count.
* - $topic->created: An outputtable string represented when the topic was posted. * - $topic->created: A string representing when the topic was posted. Safe
* - $topic->last_reply: An outputtable string representing when the topic was * to output.
* last replied to. * - $topic->last_reply: An outputtable string representing when the topic was
* - $topic->timestamp: The raw timestamp this topic was posted. * last replied to.
* - $topic->timestamp: The raw timestamp this topic was posted.
* - $topic_id: Numeric ID for the current forum topic.
* *
* @see template_preprocess_forum_topic_list() * @see template_preprocess_forum_topic_list()
* @see theme_forum_topic_list() * @see theme_forum_topic_list()
*
* @ingroup themeable
*/ */
?> ?>
<table id="forum-topic-<?php print $topic_id; ?>"> <table id="forum-topic-<?php print $topic_id; ?>">

77
core/modules/forum/forum.admin.inc
View File

@ -2,7 +2,22 @@
/** /**
* @file * @file
* Administrative page callbacks for the forum module. * Administrative page callbacks for the Forum module.
*/
/**
* Page callback: Returns a form for creating a new forum or container.
*
* @param $type
* What is being added. Possible values are 'forum' and 'container'.
* @param $edit
* (optional) Associative array containing a forum term to be edited.
* Defaults to an empty array.
*
* @return
* A form for creating a new forum or container.
*
* @see forum_menu()
*/ */
function forum_form_main($type, $edit = array()) { function forum_form_main($type, $edit = array()) {
$edit = (array) $edit; $edit = (array) $edit;
@ -20,11 +35,14 @@ function forum_form_main($type, $edit = array()) {
} }
/** /**
* Returns a form for adding a forum to the forum vocabulary * Form constructor for adding and editing a forum.
*
* @param $edit
* (optional) Associative array containing a forum term to be added or edited.
* Defaults to an empty array.
* *
* @param $edit Associative array containing a forum term to be added or edited.
* @ingroup forms
* @see forum_form_submit() * @see forum_form_submit()
* @ingroup forms
*/ */
function forum_form_forum($form, &$form_state, $edit = array()) { function forum_form_forum($form, &$form_state, $edit = array()) {
$edit += array( $edit += array(
@ -67,7 +85,7 @@ function forum_form_forum($form, &$form_state, $edit = array()) {
} }
/** /**
* Process forum form and container form submissions. * Form submission handler for forum_form_forum() and forum_form_container().
*/ */
function forum_form_submit($form, &$form_state) { function forum_form_submit($form, &$form_state) {
if ($form['form_id']['#value'] == 'forum_form_container') { if ($form['form_id']['#value'] == 'forum_form_container') {
@ -106,8 +124,8 @@ function forum_form_submit($form, &$form_state) {
/** /**
* Returns HTML for a forum form. * Returns HTML for a forum form.
* *
* By default this does not alter the appearance of a form at all, * By default this does not alter the appearance of a form at all, but is
* but is provided as a convenience for themers. * provided as a convenience for themers.
* *
* @param $variables * @param $variables
* An associative array containing: * An associative array containing:
@ -120,11 +138,14 @@ function theme_forum_form($variables) {
} }
/** /**
* Returns a form for adding a container to the forum vocabulary * Form constructor for adding and editing forum containers.
*
* @param $edit
* (optional) Associative array containing a container term to be added or edited.
* Defaults to an empty array.
* *
* @param $edit Associative array containing a container term to be added or edited.
* @ingroup forms
* @see forum_form_submit() * @see forum_form_submit()
* @ingroup forms
*/ */
function forum_form_container($form, &$form_state, $edit = array()) { function forum_form_container($form, &$form_state, $edit = array()) {
$edit += array( $edit += array(
@ -178,9 +199,13 @@ function forum_form_container($form, &$form_state, $edit = array()) {
} }
/** /**
* Returns a confirmation page for deleting a forum taxonomy term. * Form constructor for confirming deletion of a forum taxonomy term.
* *
* @param $tid ID of the term to be deleted * @param $tid
* ID of the term to be deleted.
*
* @see forum_confirm_delete_submit()
* @ingroup forms
*/ */
function forum_confirm_delete($form, &$form_state, $tid) { function forum_confirm_delete($form, &$form_state, $tid) {
$term = taxonomy_term_load($tid); $term = taxonomy_term_load($tid);
@ -192,7 +217,7 @@ function forum_confirm_delete($form, &$form_state, $tid) {
} }
/** /**
* Implement forms api _submit call. Deletes a forum after confirmation. * Form submission handler for forum_confirm_delete().
*/ */
function forum_confirm_delete_submit($form, &$form_state) { function forum_confirm_delete_submit($form, &$form_state) {
taxonomy_term_delete($form_state['values']['tid']); taxonomy_term_delete($form_state['values']['tid']);
@ -204,9 +229,11 @@ function forum_confirm_delete_submit($form, &$form_state) {
} }
/** /**
* Form builder for the forum settings page. * Form constructor for the forum settings page.
* *
* @see forum_menu()
* @see system_settings_form() * @see system_settings_form()
* @ingroup forms
*/ */
function forum_admin_settings($form) { function forum_admin_settings($form) {
$number = drupal_map_assoc(array(5, 10, 15, 20, 25, 30, 35, 40, 50, 60, 80, 100, 150, 200, 250, 300, 350, 400, 500)); $number = drupal_map_assoc(array(5, 10, 15, 20, 25, 30, 35, 40, 50, 60, 80, 100, 150, 200, 250, 300, 350, 400, 500));
@ -234,7 +261,13 @@ function forum_admin_settings($form) {
} }
/** /**
* Returns an overview list of existing forums and containers * Form constructor for the forum overview form.
*
* Returns a form for controlling the hierarchy of existing forums and
* containers.
*
* @see forum_menu()
* @ingroup forms
*/ */
function forum_overview($form, &$form_state) { function forum_overview($form, &$form_state) {
module_load_include('inc', 'taxonomy', 'taxonomy.admin'); module_load_include('inc', 'taxonomy', 'taxonomy.admin');
@ -270,11 +303,17 @@ function forum_overview($form, &$form_state) {
} }
/** /**
* Returns a select box for available parent terms * Returns a select box for available parent terms.
* *
* @param $tid ID of the term which is being added or edited * @param $tid
* @param $title Title to display the select box with * ID of the term that is being added or edited.
* @param $child_type Whether the child is forum or container * @param $title
* Title for the select box.
* @param $child_type
* Whether the child is a forum or a container.
*
* @return
* A select form element.
*/ */
function _forum_parent_select($tid, $title, $child_type) { function _forum_parent_select($tid, $title, $child_type) {

4
core/modules/forum/forum.css
View File

@ -1,3 +1,7 @@
/**
* @file
* Styling for the Forum module.
*/
#forum .description { #forum .description {
font-size: 0.9em; font-size: 0.9em;

2
core/modules/forum/forum.install
View File

@ -2,7 +2,7 @@
/** /**
* @file * @file
* Install, update and uninstall functions for the forum module. * Install, update, and uninstall functions for the Forum module.
*/ */
/** /**

183
core/modules/forum/forum.module
View File

@ -236,7 +236,7 @@ function forum_entity_info_alter(&$info) {
} }
/** /**
* Entity URI callback. * Entity URI callback used in forum_entity_info_alter().
*/ */
function forum_uri($forum) { function forum_uri($forum) {
return array( return array(
@ -245,7 +245,7 @@ function forum_uri($forum) {
} }
/** /**
* Check whether a content type can be used in a forum. * Checks whether a node can be used in a forum, based on its content type.
* *
* @param Drupal\node\Node $node * @param Drupal\node\Node $node
* A node entity. * A node entity.
@ -286,7 +286,8 @@ function forum_node_view(Node $node, $view_mode) {
/** /**
* Implements hook_node_validate(). * Implements hook_node_validate().
* *
* Check in particular that only a "leaf" term in the associated taxonomy. * Checks in particular that the node is assigned only a "leaf" term in the
* forum taxonomy.
*/ */
function forum_node_validate(Node $node, $form) { function forum_node_validate(Node $node, $form) {
if (_forum_node_check_node_type($node)) { if (_forum_node_check_node_type($node)) {
@ -322,7 +323,7 @@ function forum_node_validate(Node $node, $form) {
/** /**
* Implements hook_node_presave(). * Implements hook_node_presave().
* *
* Assign forum taxonomy when adding a topic from within a forum. * Assigns the forum taxonomy when adding a topic from within a forum.
*/ */
function forum_node_presave(Node $node) { function forum_node_presave(Node $node) {
if (_forum_node_check_node_type($node)) { if (_forum_node_check_node_type($node)) {
@ -484,7 +485,7 @@ function forum_taxonomy_term_delete(Term $term) {
/** /**
* Implements hook_comment_publish(). * Implements hook_comment_publish().
* *
* This actually handles the insert and update of published nodes since * This actually handles the insertion and update of published nodes since
* comment_save() calls hook_comment_publish() for all published comments. * comment_save() calls hook_comment_publish() for all published comments.
*/ */
function forum_comment_publish($comment) { function forum_comment_publish($comment) {
@ -494,12 +495,12 @@ function forum_comment_publish($comment) {
/** /**
* Implements hook_comment_update(). * Implements hook_comment_update().
* *
* Comment module doesn't call hook_comment_unpublish() when saving individual * The Comment module doesn't call hook_comment_unpublish() when saving
* comments so we need to check for those here. * individual comments, so we need to check for those here.
*/ */
function forum_comment_update($comment) { function forum_comment_update($comment) {
// comment_save() calls hook_comment_publish() for all published comments // comment_save() calls hook_comment_publish() for all published comments,
// so we to handle all other values here. // so we need to handle all other values here.
if (!$comment->status) { if (!$comment->status) {
_forum_update_forum_index($comment->nid); _forum_update_forum_index($comment->nid);
} }
@ -672,8 +673,8 @@ function forum_block_save($delta = '', $edit = array()) {
/** /**
* Implements hook_block_view(). * Implements hook_block_view().
* *
* Generates a block containing the currently active forum topics and the * Generates a block containing the currently active forum topics and the most
* most recently added forum topics. * recently added forum topics.
*/ */
function forum_block_view($delta = '') { function forum_block_view($delta = '') {
$query = db_select('forum_index', 'f') $query = db_select('forum_index', 'f')
@ -703,13 +704,12 @@ function forum_block_view($delta = '') {
} }
/** /**
* A #pre_render callback. Lists nodes based on the element's #query property. * Render API callback: Lists nodes based on the element's #query property.
* *
* @see forum_block_view() * This function can be used as a #pre_render callback.
* *
* @return * @see forum_block_view()
* A renderable array. */
*/
function forum_block_view_pre_render($elements) { function forum_block_view_pre_render($elements) {
$result = $elements['#query']->execute(); $result = $elements['#query']->execute();
if ($node_title_list = node_title_list($result)) { if ($node_title_list = node_title_list($result)) {
@ -733,7 +733,7 @@ function forum_form(Node $node, &$form_state) {
if (!empty($node->nid)) { if (!empty($node->nid)) {
$forum_terms = $node->taxonomy_forums; $forum_terms = $node->taxonomy_forums;
// If editing, give option to leave shadows // If editing, give option to leave shadows.
$shadow = (count($forum_terms) > 1); $shadow = (count($forum_terms) > 1);
$form['shadow'] = array('#type' => 'checkbox', '#title' => t('Leave shadow copy'), '#default_value' => $shadow, '#description' => t('If you move this topic, you can leave a link in the old forum to the new forum.')); $form['shadow'] = array('#type' => 'checkbox', '#title' => t('Leave shadow copy'), '#default_value' => $shadow, '#description' => t('If you move this topic, you can leave a link in the old forum to the new forum.'));
$form['forum_tid'] = array('#type' => 'value', '#value' => $node->forum_tid); $form['forum_tid'] = array('#type' => 'value', '#value' => $node->forum_tid);
@ -746,13 +746,15 @@ function forum_form(Node $node, &$form_state) {
* Returns a tree of all forums for a given taxonomy term ID. * Returns a tree of all forums for a given taxonomy term ID.
* *
* @param $tid * @param $tid
* (optional) Taxonomy ID of the forum, if not givin all forums will be returned. * (optional) Taxonomy term ID of the forum. If not given all forums will be
* returned.
*
* @return * @return
* A tree of taxonomy objects, with the following additional properties: * A tree of taxonomy objects, with the following additional properties:
* - 'num_topics': Number of topics in the forum * - num_topics: Number of topics in the forum.
* - 'num_posts': Total number of posts in all topics * - num_posts: Total number of posts in all topics.
* - 'last_post': Most recent post for the forum * - last_post: Most recent post for the forum.
* - 'forums': An array of child forums * - forums: An array of child forums.
*/ */
function forum_forum_load($tid = NULL) { function forum_forum_load($tid = NULL) {
$cache = &drupal_static(__FUNCTION__, array()); $cache = &drupal_static(__FUNCTION__, array());
@ -859,8 +861,17 @@ function forum_forum_load($tid = NULL) {
} }
/** /**
* Calculate the number of nodes the user has not yet read and are newer * Calculates the number of new posts in a forum that the user has not yet read.
* than NODE_NEW_LIMIT. *
* Nodes are new if they are newer than NODE_NEW_LIMIT.
*
* @param $term
* The term ID of the forum.
* @param $uid
* The user ID.
*
* @return
* The number of new posts in the forum that have not been read by the user.
*/ */
function _forum_topics_unread($term, $uid) { function _forum_topics_unread($term, $uid) {
$query = db_select('node', 'n'); $query = db_select('node', 'n');
@ -876,6 +887,23 @@ function _forum_topics_unread($term, $uid) {
->fetchField(); ->fetchField();
} }
/**
* Gets all the topics in a forum.
*
* @param $tid
* The term ID of the forum.
* @param $sortby
* One of the following integers indicating the sort criteria:
* - 1: Date - newest first.
* - 2: Date - oldest first.
* - 3: Posts with the most comments first.
* - 4: Posts with the least comments first.
* @param $forum_per_page
* The maximum number of topics to display per page.
*
* @return
* A list of all the topics in a forum.
*/
function forum_get_topics($tid, $sortby, $forum_per_page) { function forum_get_topics($tid, $sortby, $forum_per_page) {
global $user, $forum_topic_list_header; global $user, $forum_topic_list_header;
@ -959,7 +987,8 @@ function forum_get_topics($tid, $sortby, $forum_per_page) {
$first_new_found = FALSE; $first_new_found = FALSE;
foreach ($result as $topic) { foreach ($result as $topic) {
if ($user->uid) { if ($user->uid) {
// folder is new if topic is new or there are new comments since last visit // A forum is new if the topic is new, or if there are new comments since
// the user's last visit.
if ($topic->forum_tid != $tid) { if ($topic->forum_tid != $tid) {
$topic->new = 0; $topic->new = 0;
} }
@ -1005,15 +1034,22 @@ function forum_preprocess_block(&$variables) {
} }
/** /**
* Process variables for forums.tpl.php * Preprocesses variables for forums.tpl.php.
* *
* The $variables array contains the following arguments: * @param $variables
* - $forums * An array containing the following elements:
* - $topics * - forums: An array of all forum objects to display for the given taxonomy
* - $parents * term ID. If tid = 0 then all the top-level forums are displayed.
* - $tid * - topics: An array of all the topics in the current forum.
* - $sortby * - parents: An array of taxonomy term objects that are ancestors of the
* - $forum_per_page * current term ID.
* - tid: Taxonomy term ID of the current forum.
* - sortby: One of the following integers indicating the sort criteria:
* - 1: Date - newest first.
* - 2: Date - oldest first.
* - 3: Posts with the most comments first.
* - 4: Posts with the least comments first.
* - forum_per_page: The maximum number of topics to display per page.
* *
* @see forums.tpl.php * @see forums.tpl.php
*/ */
@ -1084,12 +1120,15 @@ function template_preprocess_forums(&$variables) {
} }
/** /**
* Process variables to format a forum listing. * Preprocesses variables for forum-list.tpl.php.
* *
* $variables contains the following information: * @param $variables
* - $forums * An array containing the following elements:
* - $parents * - forums: An array of all forum objects to display for the given taxonomy
* - $tid * term ID. If tid = 0 then all the top-level forums are displayed.
* - parents: An array of taxonomy term objects that are ancestors of the
* current term ID.
* - tid: Taxonomy term ID of the current forum.
* *
* @see forum-list.tpl.php * @see forum-list.tpl.php
* @see theme_forum_list() * @see theme_forum_list()
@ -1130,13 +1169,13 @@ function template_preprocess_forum_list(&$variables) {
} }
/** /**
* Preprocess variables to format the topic listing. * Preprocesses variables for forum-topic-list.tpl.php.
* *
* $variables contains the following data: * @param $variables
* - $tid * An array containing the following elements:
* - $topics * - tid: Taxonomy term ID of the current forum.
* - $sortby * - topics: An array of all the topics in the current forum.
* - $forum_per_page * - forum_per_page: The maximum number of topics to display per page.
* *
* @see forum-topic-list.tpl.php * @see forum-topic-list.tpl.php
* @see theme_forum_topic_list() * @see theme_forum_topic_list()
@ -1186,7 +1225,7 @@ function template_preprocess_forum_topic_list(&$variables) {
} }
} }
else { else {
// Make this safe for the template // Make this safe for the template.
$variables['topics'] = array(); $variables['topics'] = array();
} }
// Give meaning to $tid for themers. $tid actually stands for term id. // Give meaning to $tid for themers. $tid actually stands for term id.
@ -1197,14 +1236,16 @@ function template_preprocess_forum_topic_list(&$variables) {
} }
/** /**
* Process variables to format the icon for each individual topic. * Preprocesses variables for forum-icon.tpl.php.
* *
* $variables contains the following data: * @param $variables
* - $new_posts * An array containing the following elements:
* - $num_posts = 0 * - new_posts: Indicates whether or not the topic contains new posts.
* - $comment_mode = 0 * - num_posts: The total number of posts in all topics.
* - $sticky = 0 * - comment_mode: An integer indicating whether comments are open, closed,
* - $first_new * or hidden.
* - sticky: Indicates whether the topic is sticky.
* - first_new: Indicates whether this is the first topic with new posts.
* *
* @see forum-icon.tpl.php * @see forum-icon.tpl.php
* @see theme_forum_icon() * @see theme_forum_icon()
@ -1232,9 +1273,14 @@ function template_preprocess_forum_icon(&$variables) {
} }
/** /**
* Process variables to format submission info for display in the forum list and topic list. * Preprocesses variables for forum-submitted.tpl.php.
* *
* $variables will contain: $topic * The submission information will be displayed in the forum list and topic
* list.
*
* @param $variables
* An array containing the following elements:
* - topic: The topic object.
* *
* @see forum-submitted.tpl.php * @see forum-submitted.tpl.php
* @see theme_forum_submitted() * @see theme_forum_submitted()
@ -1244,6 +1290,16 @@ function template_preprocess_forum_submitted(&$variables) {
$variables['time'] = isset($variables['topic']->created) ? format_interval(REQUEST_TIME - $variables['topic']->created) : ''; $variables['time'] = isset($variables['topic']->created) ? format_interval(REQUEST_TIME - $variables['topic']->created) : '';
} }
/**
* Gets the last time the user viewed a node.
*
* @param $nid
* The node ID.
*
* @return
* The timestamp when the user last viewed this node, if the user has
* previously viewed the node; otherwise NODE_NEW_LIMIT.
*/
function _forum_user_last_visit($nid) { function _forum_user_last_visit($nid) {
global $user; global $user;
$history = &drupal_static(__FUNCTION__, array()); $history = &drupal_static(__FUNCTION__, array());
@ -1257,6 +1313,21 @@ function _forum_user_last_visit($nid) {
return isset($history[$nid]) ? $history[$nid] : NODE_NEW_LIMIT; return isset($history[$nid]) ? $history[$nid] : NODE_NEW_LIMIT;
} }
/**
* Gets topic sorting information based on an integer code.
*
* @param $sortby
* One of the following integers indicating the sort criteria:
* - 1: Date - newest first.
* - 2: Date - oldest first.
* - 3: Posts with the most comments first.
* - 4: Posts with the least comments first.
*
* @return
* An array with the following values:
* - field: A field for an SQL query.
* - sort: 'asc' or 'desc'.
*/
function _forum_get_topic_order($sortby) { function _forum_get_topic_order($sortby) {
switch ($sortby) { switch ($sortby) {
case 1: case 1:

13
core/modules/forum/forum.pages.inc
View File

@ -2,11 +2,20 @@
/** /**
* @file * @file
* User page callbacks for the forum module. * User page callbacks for the Forum module.
*/ */
/** /**
* Menu callback; prints a forum listing. * Page callback: Prints a forum listing.
*
* @param $forum_term
* A tree of all forums for a given taxonomy term ID. Defaults to NULL. See
* the return object of forum_forum_load() for a complete definition.
*
* @return
* A string containing HTML representing the themed forum listing.
*
* @see forum_menu()
*/ */
function forum_page($forum_term = NULL) { function forum_page($forum_term = NULL) {
if (!isset($forum_term)) { if (!isset($forum_term)) {

13
core/modules/forum/forums.tpl.php
View File

@ -2,16 +2,19 @@
/** /**
* @file * @file
* Default theme implementation to display a forum which may contain forum * Displays a forum.
* containers as well as forum topics.
* *
* Variables available: * May contain forum containers as well as forum topics.
* - $forums: The forums to display (as processed by forum-list.tpl.php) *
* - $topics: The topics to display (as processed by forum-topic-list.tpl.php) * Available variables:
* - $forums: The forums to display (as processed by forum-list.tpl.php).
* - $topics: The topics to display (as processed by forum-topic-list.tpl.php).
* - $forums_defined: A flag to indicate that the forums are configured. * - $forums_defined: A flag to indicate that the forums are configured.
* *
* @see template_preprocess_forums() * @see template_preprocess_forums()
* @see theme_forums() * @see theme_forums()
*
* @ingroup themeable
*/ */
?> ?>
<?php if ($forums_defined): ?> <?php if ($forums_defined): ?>

101
core/modules/forum/lib/Drupal/forum/Tests/ForumTest.php
View File

@ -2,7 +2,7 @@
/** /**
* @file * @file
* Definition of Drupal\forum\Tests\ForumTest. * Tests for forum.module.
*/ */
namespace Drupal\forum\Tests; namespace Drupal\forum\Tests;
@ -10,14 +10,49 @@ namespace Drupal\forum\Tests;
use Drupal\node\Node; use Drupal\node\Node;
use Drupal\simpletest\WebTestBase; use Drupal\simpletest\WebTestBase;
/**
* Provides automated tests for the Forum module.
*/
class ForumTest extends WebTestBase { class ForumTest extends WebTestBase {
/**
* A user with various administrative privileges.
*/
protected $admin_user; protected $admin_user;
/**
* A user that can create forum topics and edit its own topics.
*/
protected $edit_own_topics_user; protected $edit_own_topics_user;
/**
* A user that can create, edit, and delete forum topics.
*/
protected $edit_any_topics_user; protected $edit_any_topics_user;
/**
* A user with no special privileges.
*/
protected $web_user; protected $web_user;
/**
* An array representing a container.
*/
protected $container; protected $container;
/**
* An array representing a forum.
*/
protected $forum; protected $forum;
/**
* An array representing a root forum.
*/
protected $root_forum; protected $root_forum;
/**
* An array of forum topic node IDs.
*/
protected $nids; protected $nids;
public static function getInfo() { public static function getInfo() {
@ -28,9 +63,6 @@ class ForumTest extends WebTestBase {
); );
} }
/**
* Enable modules and create users with specific permissions.
*/
function setUp() { function setUp() {
parent::setUp(array('taxonomy', 'comment', 'forum', 'node', 'block', 'menu', 'help')); parent::setUp(array('taxonomy', 'comment', 'forum', 'node', 'block', 'menu', 'help'));
// Create users. // Create users.
@ -58,12 +90,12 @@ class ForumTest extends WebTestBase {
} }
/** /**
* Tests disabling and re-enabling forum. * Tests disabling and re-enabling the Forum module.
*/ */
function testEnableForumField() { function testEnableForumField() {
$this->drupalLogin($this->admin_user); $this->drupalLogin($this->admin_user);
// Disable the forum module. // Disable the Forum module.
$edit = array(); $edit = array();
$edit['modules[Core][forum][enable]'] = FALSE; $edit['modules[Core][forum][enable]'] = FALSE;
$this->drupalPost('admin/modules', $edit, t('Save configuration')); $this->drupalPost('admin/modules', $edit, t('Save configuration'));
@ -71,7 +103,7 @@ class ForumTest extends WebTestBase {
module_list(TRUE); module_list(TRUE);
$this->assertFalse(module_exists('forum'), t('Forum module is not enabled.')); $this->assertFalse(module_exists('forum'), t('Forum module is not enabled.'));
// Attempt to re-enable the forum module and ensure it does not try to // Attempt to re-enable the Forum module and ensure it does not try to
// recreate the taxonomy_forums field. // recreate the taxonomy_forums field.
$edit = array(); $edit = array();
$edit['modules[Core][forum][enable]'] = 'forum'; $edit['modules[Core][forum][enable]'] = 'forum';
@ -82,7 +114,7 @@ class ForumTest extends WebTestBase {
} }
/** /**
* Login users, create forum nodes, and test forum functionality through the admin and user interfaces. * Tests forum functionality through the admin and user interfaces.
*/ */
function testForum() { function testForum() {
//Check that the basic forum install creates a default forum topic //Check that the basic forum install creates a default forum topic
@ -176,7 +208,10 @@ class ForumTest extends WebTestBase {
} }
/** /**
* Forum nodes should not be created without choosing forum from select list. * Tests that forum nodes can't be added without a parent.
*
* Verifies that forum nodes are not created without choosing "forum" from the
* select list.
*/ */
function testAddOrphanTopic() { function testAddOrphanTopic() {
// Must remove forum topics to test creating orphan topics. // Must remove forum topics to test creating orphan topics.
@ -198,9 +233,10 @@ class ForumTest extends WebTestBase {
} }
/** /**
* Run admin tests on the admin user. * Runs admin tests on the admin user.
* *
* @param object $user The logged in user. * @param object $user
* The logged-in user.
*/ */
private function doAdminTests($user) { private function doAdminTests($user) {
// Login the user. // Login the user.
@ -289,7 +325,7 @@ class ForumTest extends WebTestBase {
} }
/** /**
* Edit the forum taxonomy. * Edits the forum taxonomy.
*/ */
function editForumTaxonomy() { function editForumTaxonomy() {
// Backup forum taxonomy. // Backup forum taxonomy.
@ -327,15 +363,15 @@ class ForumTest extends WebTestBase {
} }
/** /**
* Create a forum container or a forum. * Creates a forum container or a forum.
* *
* @param $type * @param $type
* Forum type (forum container or forum). * The forum type (forum container or forum).
* @param $parent * @param $parent
* Forum parent (default = 0 = a root forum; >0 = a forum container or * The forum parent. This defaults to 0, indicating a root forum.
* another forum). *
* @return * @return
* taxonomy_term_data created. * The created taxonomy term data.
*/ */
function createForum($type, $parent = 0) { function createForum($type, $parent = 0) {
// Generate a random name/description. // Generate a random name/description.
@ -368,7 +404,7 @@ class ForumTest extends WebTestBase {
} }
/** /**
* Delete a forum. * Deletes a forum.
* *
* @param $tid * @param $tid
* The forum ID. * The forum ID.
@ -389,7 +425,7 @@ class ForumTest extends WebTestBase {
} }
/** /**
* Run basic tests on the indicated user. * Runs basic tests on the indicated user.
* *
* @param $user * @param $user
* The logged in user. * The logged in user.
@ -408,15 +444,15 @@ class ForumTest extends WebTestBase {
} }
/** /**
* Create forum topic. * Creates a forum topic.
* *
* @param array $forum * @param array $forum
* Forum array. * A forum array.
* @param boolean $container * @param boolean $container
* True if $forum is a container. * TRUE if $forum is a container; FALSE otherwise.
* *
* @return object * @return object
* Topic node created. * The created topic node.
*/ */
function createForumTopic($forum, $container = FALSE) { function createForumTopic($forum, $container = FALSE) {
// Generate a random subject/body. // Generate a random subject/body.
@ -458,7 +494,7 @@ class ForumTest extends WebTestBase {
} }
/** /**
* Verify the logged in user has access to a forum nodes. * Verifies that the logged in user has access to a forum node.
* *
* @param $node_user * @param $node_user
* The user who creates the node. * The user who creates the node.
@ -538,10 +574,12 @@ class ForumTest extends WebTestBase {
} }
/** /**
* Verify display of forum page. * Verifies the display of a forum page.
* *
* @param $forum * @param $forum
* A row from taxonomy_term_data table in array. * A row from the taxonomy_term_data table in an array.
* @param $parent
* (optional) An array representing the forum's parent.
*/ */
private function verifyForumView($forum, $parent = NULL) { private function verifyForumView($forum, $parent = NULL) {
// View forum page. // View forum page.
@ -561,9 +599,10 @@ class ForumTest extends WebTestBase {
} }
/** /**
* Generate forum topics to test display of active forum block. * Generates forum topics to test the display of an active forum block.
* *
* @param array $forum Forum array (a row from taxonomy_term_data table). * @param array $forum
* The forum array (a row from taxonomy_term_data table).
*/ */
private function generateForumTopics($forum) { private function generateForumTopics($forum) {
$this->nids = array(); $this->nids = array();
@ -574,10 +613,10 @@ class ForumTest extends WebTestBase {
} }
/** /**
* View forum topics to test display of active forum block. * Views forum topics to test the display of an active forum block.
* *
* @todo The logic here is completely incorrect, since the active * @todo The logic here is completely incorrect, since the active forum topics
* forum topics block is determined by comments on the node, not by views. * block is determined by comments on the node, not by views.
* @todo DIE * @todo DIE
* *
* @param $nids * @param $nids