Commit bd378e67 authored by jhodgdon's avatar jhodgdon

Issue #1347914 by batigolix, NROTC_Webmaster, sven.lauer: Clean up API docs for filter module

parent 494cf588
/** /**
* @file * @file
* RTL admin styling for the filter module. * RTL admin styling for the Filter module.
*/ */
/** /**
......
/** /**
* @file * @file
* Admin styling for the filter module. * Admin styling for the Filter module.
*/ */
/** /**
......
...@@ -2,14 +2,15 @@ ...@@ -2,14 +2,15 @@
/** /**
* @file * @file
* Admin page callbacks for the filter module. * Admin page callbacks for the Filter module.
*/ */
/** /**
* Menu callback; Displays a list of all text formats and allows them to be rearranged. * Form constructor for a form to list and reorder text formats.
* *
* @ingroup forms * @see filter_menu()
* @see filter_admin_overview_submit() * @see filter_admin_overview_submit()
* @ingroup forms
*/ */
function filter_admin_overview($form) { function filter_admin_overview($form) {
// Overview of all formats. // Overview of all formats.
...@@ -45,6 +46,9 @@ function filter_admin_overview($form) { ...@@ -45,6 +46,9 @@ function filter_admin_overview($form) {
return $form; return $form;
} }
/**
* Form submission handler for filter_admin_overview().
*/
function filter_admin_overview_submit($form, &$form_state) { function filter_admin_overview_submit($form, &$form_state) {
foreach ($form_state['values']['formats'] as $id => $data) { foreach ($form_state['values']['formats'] as $id => $data) {
if (is_array($data) && isset($data['weight'])) { if (is_array($data) && isset($data['weight'])) {
...@@ -95,7 +99,25 @@ function theme_filter_admin_overview($variables) { ...@@ -95,7 +99,25 @@ function theme_filter_admin_overview($variables) {
} }
/** /**
* Menu callback; Display a text format form. * Page callback: Displays the text format add/edit form.
*
* @param object|null $format
* (optional) An object representing a format, with the following properties:
* - format: A machine-readable name representing the ID of the text format
* to save. If this corresponds to an existing text format, that format
* will be updated; otherwise, a new format will be created.
* - name: The title of the text format.
* - cache: An integer indicating whether the text format is cacheable (1) or
* not (0). Defaults to 1.
* - status: (optional) An integer indicating whether the text format is
* enabled (1) or not (0). Defaults to 1.
* - weight: (optional) The weight of the text format, which controls its
* placement in text format lists. If omitted, the weight is set to 0.
*
* @return
* A form array.
*
* @see filter_menu()
*/ */
function filter_admin_format_page($format = NULL) { function filter_admin_format_page($format = NULL) {
if (!isset($format->name)) { if (!isset($format->name)) {
...@@ -109,11 +131,24 @@ function filter_admin_format_page($format = NULL) { ...@@ -109,11 +131,24 @@ function filter_admin_format_page($format = NULL) {
} }
/** /**
* Generate a text format form. * Form constructor for the text format add/edit form.
*
* @param $format
* A format object having the properties:
* - format: A machine-readable name representing the ID of the text format to
* save. If this corresponds to an existing text format, that format will be
* updated; otherwise, a new format will be created.
* - name: The title of the text format.
* - cache: An integer indicating whether the text format is cacheable (1) or
* not (0). Defaults to 1.
* - status: (optional) An integer indicating whether the text format is
* enabled (1) or not (0). Defaults to 1.
* - weight: (optional) The weight of the text format, which controls its
* placement in text format lists. If omitted, the weight is set to 0.
* *
* @ingroup forms
* @see filter_admin_format_form_validate() * @see filter_admin_format_form_validate()
* @see filter_admin_format_form_submit() * @see filter_admin_format_form_submit()
* @ingroup forms
*/ */
function filter_admin_format_form($form, &$form_state, $format) { function filter_admin_format_form($form, &$form_state, $format) {
$is_fallback = ($format->format == filter_fallback_format()); $is_fallback = ($format->format == filter_fallback_format());
...@@ -287,7 +322,9 @@ function theme_filter_admin_format_filter_order($variables) { ...@@ -287,7 +322,9 @@ function theme_filter_admin_format_filter_order($variables) {
} }
/** /**
* Validate text format form submissions. * Form validation handler for filter_admin_format_form().
*
* @see filter_admin_format_form_submit()
*/ */
function filter_admin_format_form_validate($form, &$form_state) { function filter_admin_format_form_validate($form, &$form_state) {
$format_format = trim($form_state['values']['format']); $format_format = trim($form_state['values']['format']);
...@@ -304,7 +341,9 @@ function filter_admin_format_form_validate($form, &$form_state) { ...@@ -304,7 +341,9 @@ function filter_admin_format_form_validate($form, &$form_state) {
} }
/** /**
* Process text format form submissions. * Form submission handler for filter_admin_format_form().
*
* @see filter_admin_format_form_validate()
*/ */
function filter_admin_format_form_submit($form, &$form_state) { function filter_admin_format_form_submit($form, &$form_state) {
// Remove unnecessary values. // Remove unnecessary values.
...@@ -336,10 +375,14 @@ function filter_admin_format_form_submit($form, &$form_state) { ...@@ -336,10 +375,14 @@ function filter_admin_format_form_submit($form, &$form_state) {
} }
/** /**
* Menu callback; confirm deletion of a format. * Form constructor for the text format deletion confirmation form.
* *
* @ingroup forms * @param $format
* An object representing a text format.
*
* @see filter_menu()
* @see filter_admin_disable_submit() * @see filter_admin_disable_submit()
* @ingroup forms
*/ */
function filter_admin_disable($form, &$form_state, $format) { function filter_admin_disable($form, &$form_state, $format) {
$form['#format'] = $format; $form['#format'] = $format;
...@@ -353,7 +396,7 @@ function filter_admin_disable($form, &$form_state, $format) { ...@@ -353,7 +396,7 @@ function filter_admin_disable($form, &$form_state, $format) {
} }
/** /**
* Process filter disable form submission. * Form submission handler for filter_admin_disable().
*/ */
function filter_admin_disable_submit($form, &$form_state) { function filter_admin_disable_submit($form, &$form_state) {
$format = $form['#format']; $format = $form['#format'];
...@@ -362,4 +405,3 @@ function filter_admin_disable_submit($form, &$form_state) { ...@@ -362,4 +405,3 @@ function filter_admin_disable_submit($form, &$form_state) {
$form_state['redirect'] = 'admin/config/content/formats'; $form_state['redirect'] = 'admin/config/content/formats';
} }
/**
* @file
* Attaches administration-specific behavior for the Filter module.
*/
(function ($) { (function ($) {
"use strict"; "use strict";
......
...@@ -24,12 +24,12 @@ ...@@ -24,12 +24,12 @@
* input filters they provide. * input filters they provide.
* *
* Filtering is a two-step process. First, the content is 'prepared' by calling * Filtering is a two-step process. First, the content is 'prepared' by calling
* the 'prepare callback' function for every filter. The purpose of the 'prepare * the 'prepare callback' function for every filter. The purpose of the
* callback' is to escape HTML-like structures. For example, imagine a filter * 'prepare callback' is to escape HTML-like structures. For example, imagine a
* which allows the user to paste entire chunks of programming code without * filter which allows the user to paste entire chunks of programming code
* requiring manual escaping of special HTML characters like < or &. If the * without requiring manual escaping of special HTML characters like < or &. If
* programming code were left untouched, then other filters could think it was * the programming code were left untouched, then other filters could think it
* HTML and change it. For many filters, the prepare step is not necessary. * was HTML and change it. For many filters, the prepare step is not necessary.
* *
* The second step is the actual processing step. The result from passing the * The second step is the actual processing step. The result from passing the
* text through all the filters' prepare steps gets passed to all the filters * text through all the filters' prepare steps gets passed to all the filters
...@@ -39,10 +39,10 @@ ...@@ -39,10 +39,10 @@
* *
* For performance reasons content is only filtered once; the result is stored * For performance reasons content is only filtered once; the result is stored
* in the cache table and retrieved from the cache the next time the same piece * in the cache table and retrieved from the cache the next time the same piece
* of content is displayed. If a filter's output is dynamic, it can override the * of content is displayed. If a filter's output is dynamic, it can override
* cache mechanism, but obviously this should be used with caution: having one * the cache mechanism, but obviously this should be used with caution: having
* filter that does not support caching in a particular text format disables * one filter that does not support caching in a particular text format
* caching for the entire format, not just for one filter. * disables caching for the entire format, not just for one filter.
* *
* Beware of the filter cache when developing your module: it is advised to set * Beware of the filter cache when developing your module: it is advised to set
* your filter to 'cache' => FALSE while developing, but be sure to remove that * your filter to 'cache' => FALSE while developing, but be sure to remove that
...@@ -56,8 +56,9 @@ ...@@ -56,8 +56,9 @@
* - title: (required) An administrative summary of what the filter does. * - title: (required) An administrative summary of what the filter does.
* - description: Additional administrative information about the filter's * - description: Additional administrative information about the filter's
* behavior, if needed for clarification. * behavior, if needed for clarification.
* - settings callback: The name of a function that returns configuration form * - settings callback: The name of a function that returns configuration
* elements for the filter. See hook_filter_FILTER_settings() for details. * form elements for the filter. See hook_filter_FILTER_settings() for
* details.
* - default settings: An associative array containing default settings for * - default settings: An associative array containing default settings for
* the filter, to be applied when the filter has not been configured yet. * the filter, to be applied when the filter has not been configured yet.
* - prepare callback: The name of a function that escapes the content before * - prepare callback: The name of a function that escapes the content before
...@@ -69,9 +70,9 @@ ...@@ -69,9 +70,9 @@
* Note that setting this to FALSE makes the entire text format not * Note that setting this to FALSE makes the entire text format not
* cacheable, which may have an impact on the site's overall performance. * cacheable, which may have an impact on the site's overall performance.
* See filter_format_allowcache() for details. * See filter_format_allowcache() for details.
* - tips callback: The name of a function that returns end-user-facing filter * - tips callback: The name of a function that returns end-user-facing
* usage guidelines for the filter. See hook_filter_FILTER_tips() for * filter usage guidelines for the filter. See hook_filter_FILTER_tips()
* details. * for details.
* - weight: A default weight for the filter in new text formats. * - weight: A default weight for the filter in new text formats.
* *
* @see filter_example.module * @see filter_example.module
......
...@@ -2,7 +2,7 @@ ...@@ -2,7 +2,7 @@
/** /**
* @file * @file
* Install, update and uninstall functions for the filter module. * Install, update, and uninstall functions for the Filter module.
*/ */
/** /**
......
/**
* @file
* Attaches behavior for the Filter module.
*/
(function ($) { (function ($) {
"use strict"; "use strict";
/** /**
* Automatically display the guidelines of the selected text format. * Displays the guidelines of the selected text format automatically.
*/ */
Drupal.behaviors.filterGuidelines = { Drupal.behaviors.filterGuidelines = {
attach: function (context) { attach: function (context) {
......
This diff is collapsed.
...@@ -2,12 +2,13 @@ ...@@ -2,12 +2,13 @@
/** /**
* @file * @file
* User page callbacks for the filter module. * User page callbacks for the Filter module.
*/ */
/** /**
* Menu callback; show a page with long filter tips. * Page callback: Displays a page with long filter tips.
*
* @see filter_menu()
*/ */
function filter_tips_long($format = NULL) { function filter_tips_long($format = NULL) {
if (!empty($format)) { if (!empty($format)) {
...@@ -19,13 +20,12 @@ function filter_tips_long($format = NULL) { ...@@ -19,13 +20,12 @@ function filter_tips_long($format = NULL) {
return $output; return $output;
} }
/** /**
* Returns HTML for a set of filter tips. * Returns HTML for a set of filter tips.
* *
* @param $variables * @param $variables
* An associative array containing: * An associative array containing:
* - tips: An array containing descriptions and a CSS id in the form of * - tips: An array containing descriptions and a CSS ID in the form of
* 'module-name/filter-id' (only used when $long is TRUE) for each * 'module-name/filter-id' (only used when $long is TRUE) for each
* filter in one or more text formats. Example: * filter in one or more text formats. Example:
* @code * @code
......
...@@ -100,7 +100,7 @@ function testFormatAdmin() { ...@@ -100,7 +100,7 @@ function testFormatAdmin() {
} }
/** /**
* Test filter administration functionality. * Tests filter administration functionality.
*/ */
function testFilterAdmin() { function testFilterAdmin() {
// URL filter. // URL filter.
......
...@@ -31,7 +31,7 @@ public static function getInfo() { ...@@ -31,7 +31,7 @@ public static function getInfo() {
} }
/** /**
* Test CRUD operations for text formats and filters. * Tests CRUD operations for text formats and filters.
*/ */
function testTextFormatCrud() { function testTextFormatCrud() {
// Add a text format with minimum data only. // Add a text format with minimum data only.
......
...@@ -18,6 +18,9 @@ public static function getInfo() { ...@@ -18,6 +18,9 @@ public static function getInfo() {
); );
} }
/**
* Tests if the default text format is accessible to users.
*/
function testDefaultTextFormats() { function testDefaultTextFormats() {
// Create two text formats, and two users. The first user has access to // Create two text formats, and two users. The first user has access to
// both formats, but the second user only has access to the second one. // both formats, but the second user only has access to the second one.
......
...@@ -126,6 +126,9 @@ function testFormatPermissions() { ...@@ -126,6 +126,9 @@ function testFormatPermissions() {
$this->assertResponse(404); $this->assertResponse(404);
} }
/**
* Tests if text format is available to a role.
*/
function testFormatRoles() { function testFormatRoles() {
// Get the role ID assigned to the regular user. // Get the role ID assigned to the regular user.
$roles = $this->web_user->roles; $roles = $this->web_user->roles;
...@@ -149,7 +152,7 @@ function testFormatRoles() { ...@@ -149,7 +152,7 @@ function testFormatRoles() {
} }
/** /**
* Test editing a page using a disallowed text format. * Tests editing a page using a disallowed text format.
* *
* Verifies that regular users and administrators are able to edit a page, * Verifies that regular users and administrators are able to edit a page,
* but not allowed to change the fields which use an inaccessible text * but not allowed to change the fields which use an inaccessible text
......
...@@ -36,7 +36,7 @@ function setUp() { ...@@ -36,7 +36,7 @@ function setUp() {
} }
/** /**
* Test that hooks run correctly on creating, editing, and deleting a text format. * Tests that hooks run correctly on creating, editing, and deleting a text format.
*/ */
function testFilterHooks() { function testFilterHooks() {
// Add a text format. // Add a text format.
......
...@@ -9,6 +9,9 @@ ...@@ -9,6 +9,9 @@
use Drupal\simpletest\WebTestBase; use Drupal\simpletest\WebTestBase;
/**
* Tests the behavior of check_markup() when it is called without text format.
*/
class FilterNoFormatTest extends WebTestBase { class FilterNoFormatTest extends WebTestBase {
public static function getInfo() { public static function getInfo() {
return array( return array(
...@@ -18,6 +21,10 @@ public static function getInfo() { ...@@ -18,6 +21,10 @@ public static function getInfo() {
); );
} }
/**
* Tests if text with no format is filtered the same as text in the fallback
* format.
*/
function testCheckMarkupNoFormat() { function testCheckMarkupNoFormat() {
// Create some text. Include some HTML and line breaks, so we get a good // Create some text. Include some HTML and line breaks, so we get a good
// test of the filtering that is applied to it. // test of the filtering that is applied to it.
......
...@@ -51,7 +51,7 @@ function setUp() { ...@@ -51,7 +51,7 @@ function setUp() {
} }
/** /**
* Test that filtered content is emptied when an actively used filter module is disabled. * Tests that filtered content is emptied when an actively used filter module is disabled.
*/ */
function testDisableFilterModule() { function testDisableFilterModule() {
// Create a new node. // Create a new node.
......
...@@ -23,7 +23,7 @@ public static function getInfo() { ...@@ -23,7 +23,7 @@ public static function getInfo() {
} }
/** /**
* Test the line break filter. * Tests the line break filter.
*/ */
function testLineBreakFilter() { function testLineBreakFilter() {
// Setup dummy filter object. // Setup dummy filter object.
...@@ -283,7 +283,7 @@ function testFilterXSS() { ...@@ -283,7 +283,7 @@ function testFilterXSS() {
} }
/** /**
* Test filter settings, defaults, access restrictions and similar. * Tests filter settings, defaults, access restrictions and similar.
* *
* @todo This is for functions like filter_filter and check_markup, whose * @todo This is for functions like filter_filter and check_markup, whose
* functionality is not completely focused on filtering. Some ideas: * functionality is not completely focused on filtering. Some ideas:
...@@ -339,7 +339,7 @@ function testHtmlFilter() { ...@@ -339,7 +339,7 @@ function testHtmlFilter() {
} }
/** /**
* Test the spam deterrent. * Tests the spam deterrent.
*/ */
function testNoFollowFilter() { function testNoFollowFilter() {
// Setup dummy filter object. // Setup dummy filter object.
...@@ -370,7 +370,7 @@ function testNoFollowFilter() { ...@@ -370,7 +370,7 @@ function testNoFollowFilter() {
} }
/** /**
* Test the loose, admin HTML filter. * Tests the loose, admin HTML filter.
*/ */
function testFilterXSSAdmin() { function testFilterXSSAdmin() {
// DRUPAL-SA-2008-044 // DRUPAL-SA-2008-044
...@@ -764,7 +764,7 @@ function testUrlFilterContent() { ...@@ -764,7 +764,7 @@ function testUrlFilterContent() {
} }
/** /**
* Test the HTML corrector filter. * Tests the HTML corrector filter.
* *
* @todo This test could really use some validity checking function. * @todo This test could really use some validity checking function.
*/ */
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment