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
* RTL admin styling for the filter module.
* RTL admin styling for the Filter module.
*/
/**
......
/**
* @file
* Admin styling for the filter module.
* Admin styling for the Filter module.
*/
/**
......
......@@ -2,14 +2,15 @@
/**
* @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()
* @ingroup forms
*/
function filter_admin_overview($form) {
// Overview of all formats.
......@@ -45,6 +46,9 @@ function filter_admin_overview($form) {
return $form;
}
/**
* Form submission handler for filter_admin_overview().
*/
function filter_admin_overview_submit($form, &$form_state) {
foreach ($form_state['values']['formats'] as $id => $data) {
if (is_array($data) && isset($data['weight'])) {
......@@ -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) {
if (!isset($format->name)) {
......@@ -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_submit()
* @ingroup forms
*/
function filter_admin_format_form($form, &$form_state, $format) {
$is_fallback = ($format->format == filter_fallback_format());
......@@ -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) {
$format_format = trim($form_state['values']['format']);
......@@ -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) {
// Remove unnecessary values.
......@@ -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()
* @ingroup forms
*/
function filter_admin_disable($form, &$form_state, $format) {
$form['#format'] = $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) {
$format = $form['#format'];
......@@ -362,4 +405,3 @@ function filter_admin_disable_submit($form, &$form_state) {
$form_state['redirect'] = 'admin/config/content/formats';
}
/**
* @file
* Attaches administration-specific behavior for the Filter module.
*/
(function ($) {
"use strict";
......
......@@ -24,12 +24,12 @@
* input filters they provide.
*
* 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
* callback' is to escape HTML-like structures. For example, imagine a filter
* which allows the user to paste entire chunks of programming code without
* requiring manual escaping of special HTML characters like < or &. If the
* programming code were left untouched, then other filters could think it was
* HTML and change it. For many filters, the prepare step is not necessary.
* the 'prepare callback' function for every filter. The purpose of the
* 'prepare callback' is to escape HTML-like structures. For example, imagine a
* filter which allows the user to paste entire chunks of programming code
* without requiring manual escaping of special HTML characters like < or &. If
* the programming code were left untouched, then other filters could think it
* 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
* text through all the filters' prepare steps gets passed to all the filters
......@@ -39,10 +39,10 @@
*
* 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
* of content is displayed. If a filter's output is dynamic, it can override the
* cache mechanism, but obviously this should be used with caution: having one
* filter that does not support caching in a particular text format disables
* caching for the entire format, not just for one filter.
* of content is displayed. If a filter's output is dynamic, it can override
* the cache mechanism, but obviously this should be used with caution: having
* one filter that does not support caching in a particular text format
* 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
* your filter to 'cache' => FALSE while developing, but be sure to remove that
......@@ -56,8 +56,9 @@
* - title: (required) An administrative summary of what the filter does.
* - description: Additional administrative information about the filter's
* behavior, if needed for clarification.
* - settings callback: The name of a function that returns configuration form
* elements for the filter. See hook_filter_FILTER_settings() for details.
* - settings callback: The name of a function that returns configuration
* form elements for the filter. See hook_filter_FILTER_settings() for
* details.
* - default settings: An associative array containing default settings for
* 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
......@@ -69,9 +70,9 @@
* Note that setting this to FALSE makes the entire text format not
* cacheable, which may have an impact on the site's overall performance.
* See filter_format_allowcache() for details.
* - tips callback: The name of a function that returns end-user-facing filter
* usage guidelines for the filter. See hook_filter_FILTER_tips() for
* details.
* - tips callback: The name of a function that returns end-user-facing
* filter usage guidelines for the filter. See hook_filter_FILTER_tips()
* for details.
* - weight: A default weight for the filter in new text formats.
*
* @see filter_example.module
......
......@@ -2,7 +2,7 @@
/**
* @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 ($) {
"use strict";
/**
* Automatically display the guidelines of the selected text format.
* Displays the guidelines of the selected text format automatically.
*/
Drupal.behaviors.filterGuidelines = {
attach: function (context) {
......
This diff is collapsed.
......@@ -2,12 +2,13 @@
/**
* @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) {
if (!empty($format)) {
......@@ -19,13 +20,12 @@ function filter_tips_long($format = NULL) {
return $output;
}
/**
* Returns HTML for a set of filter tips.
*
* @param $variables
* 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
* filter in one or more text formats. Example:
* @code
......
......@@ -100,7 +100,7 @@ function testFormatAdmin() {
}
/**
* Test filter administration functionality.
* Tests filter administration functionality.
*/
function testFilterAdmin() {
// URL filter.
......
......@@ -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() {
// Add a text format with minimum data only.
......
......@@ -18,6 +18,9 @@ public static function getInfo() {
);
}
/**
* Tests if the default text format is accessible to users.
*/
function testDefaultTextFormats() {
// 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.
......
......@@ -126,6 +126,9 @@ function testFormatPermissions() {
$this->assertResponse(404);
}
/**
* Tests if text format is available to a role.
*/
function testFormatRoles() {
// Get the role ID assigned to the regular user.
$roles = $this->web_user->roles;
......@@ -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,
* but not allowed to change the fields which use an inaccessible text
......
......@@ -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() {
// Add a text format.
......
......@@ -9,6 +9,9 @@
use Drupal\simpletest\WebTestBase;
/**
* Tests the behavior of check_markup() when it is called without text format.
*/
class FilterNoFormatTest extends WebTestBase {
public static function getInfo() {
return array(
......@@ -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() {
// Create some text. Include some HTML and line breaks, so we get a good
// test of the filtering that is applied to it.
......
......@@ -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() {
// Create a new node.
......
......@@ -23,7 +23,7 @@ public static function getInfo() {
}
/**
* Test the line break filter.
* Tests the line break filter.
*/
function testLineBreakFilter() {
// Setup dummy filter object.
......@@ -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
* functionality is not completely focused on filtering. Some ideas:
......@@ -339,7 +339,7 @@ function testHtmlFilter() {
}
/**
* Test the spam deterrent.
* Tests the spam deterrent.
*/
function testNoFollowFilter() {
// Setup dummy filter object.
......@@ -370,7 +370,7 @@ function testNoFollowFilter() {
}
/**
* Test the loose, admin HTML filter.
* Tests the loose, admin HTML filter.
*/
function testFilterXSSAdmin() {
// DRUPAL-SA-2008-044
......@@ -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.
*/
......
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