/**
* @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.
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'])) {
}
/**
- * 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)) {
}
/**
- * 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());
}
/**
- * 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']);
}
/**
- * 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.
}
/**
- * 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;
}
/**
- * Process filter disable form submission.
+ * Form submission handler for filter_admin_disable().
*/
function filter_admin_disable_submit($form, &$form_state) {
$format = $form['#format'];
$form_state['redirect'] = 'admin/config/content/formats';
}
-
* 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
*
* 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
* - 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
* 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
/**
* @file
- * Framework for handling filtering of content.
+ * Framework for handling the filtering of content.
*/
/**
* Implements hook_element_info().
*
* @see filter_process_format()
+ * @see text_format_wrapper()
*/
function filter_element_info() {
$type['text_format'] = array(
}
/**
- * Access callback for deleting text formats.
+ * Access callback: Checks access for disabling text formats.
*
* @param $format
* A text format object.
+ *
* @return
* TRUE if the text format can be disabled by the current user, FALSE
* otherwise.
+ *
+ * @see filter_menu()
*/
function _filter_disable_format_access($format) {
// The fallback format can never be disabled.
}
/**
- * Load a text format object from the database.
+ * Loads a text format object from the database.
*
* @param $format_id
* The format ID.
}
/**
- * Save a text format object to the database.
+ * Saves a text format object to the database.
*
* @param $format
- * A format object using the properties:
- * - 'format': A machine-readable name representing the ID of the text 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.
- * - 'status': (optional) An integer indicating whether the text format is
+ * - name: The title of the text format.
+ * - 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
+ * - weight: (optional) The weight of the text format, which controls its
* placement in text format lists. If omitted, the weight is set to 0.
- * - 'filters': (optional) An associative, multi-dimensional array of filters
+ * - filters: (optional) An associative, multi-dimensional array of filters
* assigned to the text format, keyed by the name of each filter and using
* the properties:
- * - 'weight': (optional) The weight of the filter in the text format. If
+ * - weight: (optional) The weight of the filter in the text format. If
* omitted, either the currently stored weight is retained (if there is
* one), or the filter is assigned a weight of 10, which will usually
* put it at the bottom of the list.
- * - 'status': (optional) A boolean indicating whether the filter is
+ * - status: (optional) A Boolean indicating whether the filter is
* enabled in the text format. If omitted, the filter will be disabled.
- * - 'settings': (optional) An array of configured settings for the filter.
+ * - settings: (optional) An array of configured settings for the filter.
* See hook_filter_info() for details.
+ *
+ * @return
+ * SAVED_NEW or SAVED_UPDATED.
*/
function filter_format_save($format) {
$format->name = trim($format->name);
}
/**
- * Disable a text format.
+ * Disables a text format.
*
* There is no core facility to re-enable a disabled format. It is not deleted
* to keep information for contrib and to make sure the format ID is never
}
/**
- * Display a text format form title.
+ * Displays a text format form title.
+ *
+ * @see filter_menu()
*/
function filter_admin_format_title($format) {
return $format->name;
*
* @param $format
* An object representing a text format.
+ *
* @return
* The machine-readable permission name, or FALSE if the provided text format
* is malformed or is the fallback format (which is available to all users).
}
/**
- * Retrieve a list of text formats, ordered by weight.
+ * Retrieves a list of text formats, ordered by weight.
*
* @param $account
* (optional) If provided, only those formats that are allowed for this user
* account will be returned. All formats will be returned otherwise.
+ *
* @return
* An array of text format objects, keyed by the format ID and ordered by
* weight.
}
/**
- * Resets text format caches.
+ * Resets the text format caches.
*
* @see filter_formats()
*/
*
* @param $format
* An object representing the text format.
+ *
* @return
* An array of role names, keyed by role ID.
*/
*
* @param $rid
* The user role ID to retrieve text formats for.
+ *
* @return
* An array of text format objects that are allowed for the role, keyed by
* the text format ID and ordered by weight.
* @param $account
* (optional) The user account to check. Defaults to the currently logged-in
* user.
+ *
* @return
* The ID of the user's default text format.
*
* Any modules implementing a format deletion functionality must not delete
* this format.
*
+ * @return
+ * The ID of the fallback text format.
+ *
* @see hook_filter_format_disable()
* @see filter_default_format()
*/
}
/**
- * Return a list of all filters provided by modules.
+ * Returns a list of all filters provided by modules.
*/
function filter_get_filters() {
$filters = &drupal_static(__FUNCTION__, array());
}
/**
- * Helper function for sorting the filter list by filter name.
+ * Sorts an array of filters by filter name.
+ *
+ * Callback for uasort() within filter_get_filters().
*/
function _filter_list_cmp($a, $b) {
return strcmp($a['title'], $b['title']);
}
/**
- * Check if text in a certain text format is allowed to be cached.
+ * Checks if the text in a certain text format is allowed to be cached.
*
* This function can be used to check whether the result of the filtering
* process can be cached. A text format may allow caching depending on the
*
* @param $format_id
* The text format ID to check.
+ *
* @return
* TRUE if the given text format allows caching, FALSE otherwise.
*/
}
/**
- * Helper function to determine whether the output of a given text format can be cached.
+ * Determines whether the output of a given text format can be cached.
*
* The output of a given text format can be cached when all enabled filters in
* the text format allow caching.
*
* @param $format
* The text format object to check.
+ *
* @return
* TRUE if all the filters enabled in the given text format allow caching,
* FALSE otherwise.
}
/**
- * Retrieve a list of filters for a given text format.
+ * Retrieves a list of filters for a given text format.
*
* Note that this function returns all associated filters regardless of whether
* they are enabled or disabled. All functions working with the filter
}
/**
- * Run all the enabled filters on a piece of text.
+ * Runs all the enabled filters on a piece of text.
*
* Note: Because filters can inject JavaScript or execute PHP code, security is
* vital here. When a user supplies a text format, you should validate it using
* filter_access() before accepting/using it. This is normally done in the
- * validation stage of the Form API. You should for example never make a preview
- * of content in a disallowed format.
+ * validation stage of the Form API. You should for example never make a
+ * preview of content in a disallowed format.
*
* @param $text
* The text to be filtered.
* @param $format_id
- * The format id of the text to be filtered. If no format is assigned, the
+ * The format ID of the text to be filtered. If no format is assigned, the
* fallback format will be used.
* @param $langcode
* Optional: the language code of the text to be filtered, e.g. 'en' for
* The caller may set this to FALSE when the output is already cached
* elsewhere to avoid duplicate cache lookups and storage.
*
+ * @return
+ * The filtered text.
+ *
* @ingroup sanitization
*/
function check_markup($text, $format_id = NULL, $langcode = '', $cache = FALSE) {
* Expands an element into a base element with text format selector attached.
*
* The form element will be expanded into two separate form elements, one
- * holding the original element, and the other holding the text format selector:
- * - value: Holds the original element, having its #type changed to the value of
- * #base_type or 'textarea' by default.
- * - format: Holds the text format fieldset and the text format selection, using
- * the text format id specified in #format or the user's default format by
- * default, if NULL.
- *
- * The resulting value for the element will be an array holding the value and the
- * format. For example, the value for the body element will be:
+ * holding the original element, and the other holding the text format
+ * selector:
+ * - value: Holds the original element, having its #type changed to the value
+ * of #base_type or 'textarea' by default.
+ * - format: Holds the text format fieldset and the text format selection,
+ * using the text format ID specified in #format or the user's default format
+ * by default, if NULL.
+ *
+ * The resulting value for the element will be an array holding the value and
+ * the format. For example, the value for the body element will be:
* @code
* $form_state['values']['body']['value'] = 'foo';
* $form_state['values']['body']['format'] = 'foo';
* The form element to process. Properties used:
* - #base_type: The form element #type to use for the 'value' element.
* 'textarea' by default.
- * - #format: (optional) The text format id to preselect. If NULL or not set,
+ * - #format: (optional) The text format ID to preselect. If NULL or not set,
* the default format for the current user will be used.
*
* @return
}
/**
- * #pre_render callback for #type 'text_format' to hide field value from prying eyes.
+ * Render API callback: Hides the field value of 'text_format' elements.
*
- * To not break form processing and previews if a user does not have access to a
- * stored text format, the expanded form elements in filter_process_format() are
- * forced to take over the stored #default_values for 'value' and 'format'.
+ * To not break form processing and previews if a user does not have access to
+ * a stored text format, the expanded form elements in filter_process_format()
+ * are forced to take over the stored #default_values for 'value' and 'format'.
* However, to prevent the unfiltered, original #value from being displayed to
* the user, we replace it with a friendly notice here.
*
}
/**
- * Helper function for fetching filter tips.
+ * Retrieves the filter tips.
+ *
+ * @param $format_id
+ * The ID of the text format for which to retrieve tips, or -1 to return tips
+ * for all formats accessible to the current user.
+ * @param $long
+ * (optional) Boolean indicating whether the long form of tips should be
+ * returned. Defaults to FALSE.
+ *
+ * @return
+ * An associative array of filtering tips, keyed by filter name. Each
+ * filtering tip is an associative array with elements:
+ * - tip: Tip text.
+ * - id: Filter ID.
*/
function _filter_tips($format_id, $long = FALSE) {
global $user;
/**
* Parses an HTML snippet and returns it as a DOM object.
*
- * This function loads the body part of a partial (X)HTML document
- * and returns a full DOMDocument object that represents this document.
- * You can use filter_dom_serialize() to serialize this DOMDocument
- * back to a XHTML snippet.
+ * This function loads the body part of a partial (X)HTML document and returns
+ * a full DOMDocument object that represents this document. You can use
+ * filter_dom_serialize() to serialize this DOMDocument back to a XHTML
+ * snippet.
*
* @param $text
- * The partial (X)HTML snippet to load. Invalid mark-up
- * will be corrected on import.
+ * The partial (X)HTML snippet to load. Invalid markup will be corrected on
+ * import.
+ *
* @return
* A DOMDocument that represents the loaded (X)HTML snippet.
*/
/**
* Converts a DOM object back to an HTML snippet.
*
- * The function serializes the body part of a DOMDocument
- * back to an XHTML snippet.
- *
- * The resulting XHTML snippet will be properly formatted
- * to be compatible with HTML user agents.
+ * The function serializes the body part of a DOMDocument back to an XHTML
+ * snippet. The resulting XHTML snippet will be properly formatted to be
+ * compatible with HTML user agents.
*
* @param $dom_document
* A DOMDocument object to serialize, only the tags below
* the first <body> node will be converted.
+ *
* @return
* A valid (X)HTML snippet, as a string.
*/
/**
* @defgroup standard_filters Standard filters
* @{
- * Filters implemented by the filter.module.
+ * Filters implemented by the Filter module.
*/
/**
}
/**
- * Settings callback for the HTML filter.
+ * Filter settings callback for the HTML content filter.
+ *
+ * See hook_filter_FILTER_settings() for documentation of parameters and return
+ * value.
*/
function _filter_html_settings($form, &$form_state, $filter, $format, $defaults) {
$filter->settings += $defaults;
}
/**
- * HTML filter. Provides filtering of input into accepted HTML.
+ * Provides filtering of input into accepted HTML.
*/
function _filter_html($text, $filter) {
$allowed_tags = preg_split('/\s+|<|>/', $filter->settings['allowed_html'], -1, PREG_SPLIT_NO_EMPTY);
}
/**
- * Filter tips callback for HTML filter.
+ * Filter tips callback: Provides help for the HTML filter.
+ *
+ * @see filter_filter_info()
*/
function _filter_html_tips($filter, $format, $long = FALSE) {
global $base_url;
}
/**
- * Settings callback for URL filter.
+ * Filter URL settings callback: Provides settings for the URL filter.
+ *
+ * @see filter_filter_info()
*/
function _filter_url_settings($form, &$form_state, $filter, $format, $defaults) {
$filter->settings += $defaults;
}
/**
- * URL filter. Automatically converts text into hyperlinks.
+ * Converts text into hyperlinks automatically.
*
* This filter identifies and makes clickable three types of "links".
* - URLs like http://example.com.
* - E-mail addresses like name@example.com.
- * - Web addresses without the "http://" protocol defined, like www.example.com.
+ * - Web addresses without the "http://" protocol defined, like
+ * www.example.com.
* Each type must be processed separately, as there is no one regular
* expression that could possibly match all of the cases in one pass.
*/
}
/**
- * preg_replace callback to make links out of absolute URLs.
+ * Makes links out of absolute URLs.
+ *
+ * Callback for preg_replace_callback() within _filter_url().
*/
function _filter_url_parse_full_links($match) {
// The $i:th parenthesis in the regexp contains the URL.
}
/**
- * preg_replace callback to make links out of e-mail addresses.
+ * Makes links out of e-mail addresses.
+ *
+ * Callback for preg_replace_callback() within _filter_url().
*/
function _filter_url_parse_email_links($match) {
// The $i:th parenthesis in the regexp contains the URL.
}
/**
- * preg_replace callback to make links out of domain names starting with "www."
+ * Makes links out of domain names starting with "www."
+ *
+ * Callback for preg_replace_callback() within _filter_url().
*/
function _filter_url_parse_partial_links($match) {
// The $i:th parenthesis in the regexp contains the URL.
}
/**
- * preg_replace callback to escape contents of HTML comments
+ * Escapes the contents of HTML comments.
+ *
+ * Callback for preg_replace_callback() within _filter_url().
*
* @param $match
* An array containing matches to replace from preg_replace_callback(),
}
/**
- * Filter tips callback for URL filter.
+ * Filter tips callback: Provides help for the URL filter.
+ *
+ * @see filter_filter_info()
*/
function _filter_url_tips($filter, $format, $long = FALSE) {
return t('Web page addresses and e-mail addresses turn into links automatically.');
}
/**
- * Scan input and make sure that all HTML tags are properly closed and nested.
+ * Scans the input and makes sure that HTML tags are properly closed.
*/
function _filter_htmlcorrector($text) {
return filter_dom_serialize(filter_dom_load($text));
}
/**
- * Convert line breaks into <p> and <br> in an intelligent fashion.
+ * Converts line breaks into <p> and <br> in an intelligent fashion.
+ *
* Based on: http://photomatt.net/scripts/autop
*/
function _filter_autop($text) {
}
/**
- * Filter tips callback for auto-paragraph filter.
+ * Filter tips callback: Provides help for the auto-paragraph filter.
+ *
+ * @see filter_filter_info()
*/
function _filter_autop_tips($filter, $format, $long = FALSE) {
if ($long) {
}
/**
- * Filter tips callback for HTML escaping filter.
+ * Filter tips callback: Provides help for the HTML escaping filter.
+ *
+ * @see filter_filter_info()
*/
function _filter_html_escape_tips($filter, $format, $long = FALSE) {
return t('No HTML tags allowed.');
projects / project/drupal.git / commitdiff