Commit b3a2894b authored by dragonwize's avatar dragonwize
Browse files

Finished code documentation.

Ran through Coder 2.x.
Added more notes to the README.
parent 59ed6416
...@@ -16,10 +16,14 @@ Features ...@@ -16,10 +16,14 @@ Features
------------------------------------------------------------------- -------------------------------------------------------------------
Installation: Installation:
1. Copy the module folder to your server. 1. Copy the module folder to your server.
2. Enable the module via the modules page. 2. Enable the module via the modules page.
Use: -------------------------------------------------------------------
Simple 4-step usage:
1. Go to user permissions (/admin/user/permissions) and set your permissions. 1. Go to user permissions (/admin/user/permissions) and set your permissions.
2. Navigate to Site Configuration > Input formats (/admin/settings/filters) 2. Navigate to Site Configuration > Input formats (/admin/settings/filters)
3. There you will find 2 tabs where you can change your settings. 3. There you will find 2 tabs where you can change your settings.
...@@ -29,9 +33,24 @@ Use: ...@@ -29,9 +33,24 @@ Use:
type admin page to set those settings (example /admin/content/node-type/page). type admin page to set those settings (example /admin/content/node-type/page).
The settings are under the Input format settings fieldset. The settings are under the Input format settings fieldset.
-------------------------------------------------------------------
Extended usage and notes:
* The default format will only be set on NEW nodes and comments. The format
selected when the form is submitted is used for future editing purposes.
* The module is designed to always fall back to default settings when needed.
This means that when you enable the module before you change any settings,
it will use your current Drupal settings. Also when you enable conrol per node
type it will use your global settings until you save the content type with new
settings.
* The permissions "collapse format fieldset by default" and
"collapsible format selection" will only work if "Show format selection" is
also given. This is because those 2 perms only have an effect when there is
a format selection.
The module is designed to always fall back to default settings when needed. * The permission "collapse format fieldset by default" will only work if
This means that when you enable the module before you change any settings, "collapsible format selection" is also given. This is because the
it will use your current Drupal settings. Also when you enable conrol per node fieldset can only be collapsed by default if it is collapsible.
type it will use your global settings until you save the content type with new
settings.
\ No newline at end of file
<?php <?php
// $Id$ // $Id$
/** /**
* @file better-formats-filter-admin-form.tpl.php * @file
* Default theme implementation to configure format manager filter admin page * Default theme implementation to configure format manager filter admin page
* *
* Available variables: * Available variables:
......
...@@ -11,7 +11,7 @@ ...@@ -11,7 +11,7 @@
/** /**
* Implementation of hook_schema() * Implementation of hook_schema().
*/ */
function better_formats_schema() { function better_formats_schema() {
$schema['better_formats_defaults'] = array( $schema['better_formats_defaults'] = array(
...@@ -55,7 +55,7 @@ function better_formats_schema() { ...@@ -55,7 +55,7 @@ function better_formats_schema() {
} }
/** /**
* Implementation of hook_install() * Implementation of hook_install().
*/ */
function better_formats_install() { function better_formats_install() {
// create tables // create tables
...@@ -86,7 +86,7 @@ function better_formats_install() { ...@@ -86,7 +86,7 @@ function better_formats_install() {
} }
/** /**
* Implementation of hook_uninstall() * Implementation of hook_uninstall().
*/ */
function better_formats_uninstall() { function better_formats_uninstall() {
drupal_uninstall_schema('better_formats'); drupal_uninstall_schema('better_formats');
......
...@@ -5,12 +5,12 @@ ...@@ -5,12 +5,12 @@
* @file * @file
* Enhances Drupal's core input format settings. * Enhances Drupal's core input format settings.
* *
* Allows setting of defaults per role and content type, controls format display * Allows setting of defaults per role and content type,
* options, works with CCK fields. * controls format display options, works with CCK fields.
*/ */
/** /**
* Implementation of hook_help() * Implementation of hook_help().
*/ */
function better_formats_help($path, $arg) { function better_formats_help($path, $arg) {
switch ($path) { switch ($path) {
...@@ -24,7 +24,9 @@ function better_formats_help($path, $arg) { ...@@ -24,7 +24,9 @@ function better_formats_help($path, $arg) {
return $output; return $output;
} }
/**
* Implementation of hook_perm().
*/
function better_formats_perm() { function better_formats_perm() {
return array( return array(
'show format selection', 'show format selection',
...@@ -35,8 +37,7 @@ function better_formats_perm() { ...@@ -35,8 +37,7 @@ function better_formats_perm() {
} }
/** /**
* Implementation of hook_menu() * Implementation of hook_menu().
* @return array array of menu items
*/ */
function better_formats_menu() { function better_formats_menu() {
$items = array(); $items = array();
...@@ -66,7 +67,7 @@ function better_formats_menu() { ...@@ -66,7 +67,7 @@ function better_formats_menu() {
} }
/** /**
* Implementation of hook_theme() * Implementation of hook_theme().
*/ */
function better_formats_theme() { function better_formats_theme() {
return array( return array(
...@@ -79,8 +80,8 @@ function better_formats_theme() { ...@@ -79,8 +80,8 @@ function better_formats_theme() {
} }
/** /**
* Implementation of hook_form_alter() * Implementation of hook_form_alter().
*/ */
function better_formats_form_alter(&$form, $form_state, $form_id) { function better_formats_form_alter(&$form, $form_state, $form_id) {
// alter new node and comment forms // alter new node and comment forms
// using $form['#id'] instead of $form_id because $form_id is in the form of // using $form['#id'] instead of $form_id because $form_id is in the form of
...@@ -118,7 +119,12 @@ function better_formats_form_alter(&$form, $form_state, $form_id) { ...@@ -118,7 +119,12 @@ function better_formats_form_alter(&$form, $form_state, $form_id) {
} }
} }
/**
* FAPI form to add to the content type edit form.
*
* @see better_formats_content_type_admin_form_validate()
* @see better_formats_content_type_admin_form_submit()
*/
function better_formats_content_type_admin_form(&$form, $form_state) { function better_formats_content_type_admin_form(&$form, $form_state) {
// add js to enhance form and fix a bug // add js to enhance form and fix a bug
drupal_add_js(drupal_get_path('module', 'better_formats') . '/better_formats_node_type_form.js'); drupal_add_js(drupal_get_path('module', 'better_formats') . '/better_formats_node_type_form.js');
...@@ -131,9 +137,6 @@ function better_formats_content_type_admin_form(&$form, $form_state) { ...@@ -131,9 +137,6 @@ function better_formats_content_type_admin_form(&$form, $form_state) {
$format_boxes[$format->format] = $format->name; $format_boxes[$format->format] = $format->name;
} }
// get formats array for role based defaults
$formats_options = better_formats_get_formats_per_role();
$key = 'better_formats'; $key = 'better_formats';
$form[$key] = array( $form[$key] = array(
'#type' => 'fieldset', '#type' => 'fieldset',
...@@ -171,11 +174,23 @@ function better_formats_content_type_admin_form(&$form, $form_state) { ...@@ -171,11 +174,23 @@ function better_formats_content_type_admin_form(&$form, $form_state) {
array_unshift($form['#submit'], 'better_formats_content_type_admin_form_submit'); array_unshift($form['#submit'], 'better_formats_content_type_admin_form_submit');
} }
/**
* Handles validatation of the addition to the content type edit form.
*
* @see better_formats_content_type_admin_form()
* @see better_formats_content_type_admin_form_submit()
*/
function better_formats_content_type_admin_form_validate($form, &$form_state) { function better_formats_content_type_admin_form_validate($form, &$form_state) {
include(drupal_get_path('module', 'better_formats') . '/better_formats_defaults.admin.inc'); include(drupal_get_path('module', 'better_formats') . '/better_formats_defaults.admin.inc');
better_formats_defaults_admin_form_validate($form, $form_state); better_formats_defaults_admin_form_validate($form, $form_state);
} }
/**
* Handles submition of the addition to the content type edit form.
*
* @see better_formats_content_type_admin_form()
* @see better_formats_content_type_admin_form_validate()
*/
function better_formats_content_type_admin_form_submit($form, &$form_state) { function better_formats_content_type_admin_form_submit($form, &$form_state) {
$node_type = $form['#node_type']->type; $node_type = $form['#node_type']->type;
...@@ -197,11 +212,10 @@ function better_formats_content_type_admin_form_submit($form, &$form_state) { ...@@ -197,11 +212,10 @@ function better_formats_content_type_admin_form_submit($form, &$form_state) {
unset($form_state['values']['better_formats_defaults']); unset($form_state['values']['better_formats_defaults']);
} }
/** /**
* Create default entry * Creates base format default entry for a newly created role.
* @param array $form *
* @param array $form_state by reference * @see better_formats_form_alter()
*/ */
function better_formats_new_role($form, &$form_state) { function better_formats_new_role($form, &$form_state) {
// get the rid for the role just created // get the rid for the role just created
...@@ -218,9 +232,9 @@ function better_formats_new_role($form, &$form_state) { ...@@ -218,9 +232,9 @@ function better_formats_new_role($form, &$form_state) {
} }
/** /**
* Delete default entry * Deletes role format default entries for roles being deleted.
* @param array $form *
* @param array $form_state by reference * @see better_formats_form_alter()
*/ */
function better_formats_delete_role($form, &$form_state) { function better_formats_delete_role($form, &$form_state) {
// delete role from format manager table // delete role from format manager table
...@@ -229,9 +243,8 @@ function better_formats_delete_role($form, &$form_state) { ...@@ -229,9 +243,8 @@ function better_formats_delete_role($form, &$form_state) {
db_query($sql, $form['rid']['#value']); db_query($sql, $form['rid']['#value']);
} }
/** /**
* Implimentation of hook_elements(). * Implementation of hook_elements().
* *
* Adds a process function to CCK's textarea FAPI element * Adds a process function to CCK's textarea FAPI element
*/ */
...@@ -244,16 +257,12 @@ function better_formats_elements() { ...@@ -244,16 +257,12 @@ function better_formats_elements() {
} }
/** /**
* Process an individual element. * Processes a CCK textarea element.
*
* Build the form element. When creating a form using FAPI #process,
* note that $element['#value'] is already set.
*
* The $fields array is in $form['#field_info'][$element['#field_name']].
* *
* Resets the textareas filter area with bettter_formats default. * Resets the textareas filter area with bettter_formats default.
* This function is used to affect CCK textareas not core fields. * This function is used to affect CCK textareas not core fields.
* Most of this was taken from text_textarea_process() *
* @see text_textarea_process()
*/ */
function better_formats_textarea_process($element, $edit, $form_state, $form) { function better_formats_textarea_process($element, $edit, $form_state, $form) {
$field = $form['#field_info'][$element['#field_name']]; $field = $form['#field_info'][$element['#field_name']];
...@@ -278,6 +287,11 @@ function better_formats_textarea_process($element, $edit, $form_state, $form) { ...@@ -278,6 +287,11 @@ function better_formats_textarea_process($element, $edit, $form_state, $form) {
return $element; return $element;
} }
/**
* Processes formats for core node body fields.
*
* @see better_formats_form_alter()
*/
function better_formats_set_node_format(&$form) { function better_formats_set_node_format(&$form) {
// set core body field // set core body field
if (isset($form['body_field'])) { if (isset($form['body_field'])) {
...@@ -294,6 +308,11 @@ function better_formats_set_node_format(&$form) { ...@@ -294,6 +308,11 @@ function better_formats_set_node_format(&$form) {
} }
} }
/**
* Processes formats for core node comment form.
*
* @see better_formats_form_alter()
*/
function better_formats_set_comment_format(&$form) { function better_formats_set_comment_format(&$form) {
if (isset($form['comment_filter']['format'])) { if (isset($form['comment_filter']['format'])) {
$node = node_load($form['nid']['#value']); $node = node_load($form['nid']['#value']);
...@@ -311,6 +330,17 @@ function better_formats_set_comment_format(&$form) { ...@@ -311,6 +330,17 @@ function better_formats_set_comment_format(&$form) {
} }
} }
/**
* Returns the format for an existing node or comment.
*
* @param array $form
* FAPI form array
* @return int
* Format ID
*
* @see better_formats_set_node_format()
* @see better_formats_set_comment_format()
*/
function better_formats_get_current_format($form) { function better_formats_get_current_format($form) {
// default format to site default in case of error // default format to site default in case of error
$format = FILTER_FORMAT_DEFAULT; $format = FILTER_FORMAT_DEFAULT;
...@@ -328,6 +358,18 @@ function better_formats_get_current_format($form) { ...@@ -328,6 +358,18 @@ function better_formats_get_current_format($form) {
return $format; return $format;
} }
/**
* Returns the default format for an new node or comment.
*
* @param string $mode
* 'node' or 'comment'. Describes the top level type of default.
* @return int
* Format ID
*
* @see better_formats_set_node_format()
* @see better_formats_set_comment_format()
* @see better_formats_textarea_process()
*/
function better_formats_get_default_format($mode, $node_type = '') { function better_formats_get_default_format($mode, $node_type = '') {
static $format; static $format;
...@@ -368,11 +410,13 @@ function better_formats_get_default_format($mode, $node_type = '') { ...@@ -368,11 +410,13 @@ function better_formats_get_default_format($mode, $node_type = '') {
/** /**
* Better Formats version of filter_form(). * Better Formats version of filter_form().
* Copied from filter.module with slight modification to handle options for
* hiding filter selection and/or tips.
* *
* @param * Copied from filter.module with slight modification to
* @return array FAPI array for the format of a textarea * handle options for hiding filter selection and/or tips.
* The $node_type param was added to the signature to
* enable condition by content type.
*
* @see filter_form()
*/ */
function better_formats_filter_form($value = FILTER_FORMAT_DEFAULT, $node_type = '', $weight = 1, $parents = array('format')) { function better_formats_filter_form($value = FILTER_FORMAT_DEFAULT, $node_type = '', $weight = 1, $parents = array('format')) {
$value = filter_resolve_format($value); $value = filter_resolve_format($value);
...@@ -432,7 +476,7 @@ function better_formats_filter_form($value = FILTER_FORMAT_DEFAULT, $node_type = ...@@ -432,7 +476,7 @@ function better_formats_filter_form($value = FILTER_FORMAT_DEFAULT, $node_type =
else { else {
// this is to get around an issue with Wysiwyg API popping the last element // this is to get around an issue with Wysiwyg API popping the last element
// should not be needed in D7 // should not be needed in D7
// @see http://drupal.org/node/344169 // see http://drupal.org/node/344169
$form[] = array('#value' => ''); $form[] = array('#value' => '');
} }
} }
...@@ -457,7 +501,7 @@ function better_formats_filter_form($value = FILTER_FORMAT_DEFAULT, $node_type = ...@@ -457,7 +501,7 @@ function better_formats_filter_form($value = FILTER_FORMAT_DEFAULT, $node_type =
else { else {
// this is to get around an issue with Wysiwyg API looking for guidelines // this is to get around an issue with Wysiwyg API looking for guidelines
// should not be needed in D7 // should not be needed in D7
// @see http://drupal.org/node/344169 // see http://drupal.org/node/344169
$form['format']['guidelines'] = array( $form['format']['guidelines'] = array(
'#title' => t('Formatting guidelines'), '#title' => t('Formatting guidelines'),
'#value' => '', '#value' => '',
...@@ -468,9 +512,21 @@ function better_formats_filter_form($value = FILTER_FORMAT_DEFAULT, $node_type = ...@@ -468,9 +512,21 @@ function better_formats_filter_form($value = FILTER_FORMAT_DEFAULT, $node_type =
return $form; return $form;
} }
/**
* Retrieves the formats available to users by role.
*
* Gets all formats then creates an array keyed by role IDs
* that lists the formats available to that role. This is determined
* by Drupal core's format permissions set at
* admin/settings/filters/[filter_id].
*
* @param string $default_title
* Allows configuration of the label of the default seletion
* @return array
* Multi-dim array with role IDs for keys and list of allowed formats.
*
* @see better_formats_get_role_default_fields()
*/
function better_formats_get_formats_per_role($default_title = 'Site') { function better_formats_get_formats_per_role($default_title = 'Site') {
$formats = filter_formats(); $formats = filter_formats();
$roles = user_roles(); $roles = user_roles();
...@@ -504,6 +560,16 @@ function better_formats_get_formats_per_role($default_title = 'Site') { ...@@ -504,6 +560,16 @@ function better_formats_get_formats_per_role($default_title = 'Site') {
return $format_options; return $format_options;
} }
/**
* Builds FAPI form elements for the default format selection.
*
* @param string $mode
* 'node' or 'comment'. Top most level type for requested default.
* @param string $node_type
* Type of node this request is for.
* @return array
* FAPI array for the default select field.
*/
function better_formats_get_role_default_fields($mode, $node_type = '') { function better_formats_get_role_default_fields($mode, $node_type = '') {
$form = array(); $form = array();
$format_options = better_formats_get_formats_per_role(); $format_options = better_formats_get_formats_per_role();
......
...@@ -8,8 +8,13 @@ ...@@ -8,8 +8,13 @@
/** /**
* Builds the form for the filters admin * Builds the form for the filters admin.
* @return array fapi array *
* @return array
* FAPI array
*
* @see better_formats_defaults_admin_form_validate()
* @see better_formats_defaults_admin_form_submit()
*/ */
function better_formats_defaults_admin_form() { function better_formats_defaults_admin_form() {
$form = array( $form = array(
...@@ -29,9 +34,10 @@ function better_formats_defaults_admin_form() { ...@@ -29,9 +34,10 @@ function better_formats_defaults_admin_form() {
} }
/** /**
* Validates better_formats_admin_filter_form * Validates better_formats_admin_filter_form.
* @param array $form *
* @param array $form_state * @see better_formats_defaults_admin_form()
* @see better_formats_defaults_admin_form_submit()
*/ */
function better_formats_defaults_admin_form_validate($form, &$form_state) { function better_formats_defaults_admin_form_validate($form, &$form_state) {
$formats = filter_formats(); $formats = filter_formats();
...@@ -51,9 +57,10 @@ function better_formats_defaults_admin_form_validate($form, &$form_state) { ...@@ -51,9 +57,10 @@ function better_formats_defaults_admin_form_validate($form, &$form_state) {
} }
/** /**
* Updates database from better_formats_admin_filter_form * Updates database from better_formats_admin_filter_form.
* @param array $form *
* @param array $form_state * @see better_formats_defaults_admin_form()
* @see better_formats_defaults_admin_form_validate()
*/ */
function better_formats_defaults_admin_form_submit($form, &$form_state) { function better_formats_defaults_admin_form_submit($form, &$form_state) {
// update DB // update DB
...@@ -72,12 +79,11 @@ function better_formats_defaults_admin_form_submit($form, &$form_state) { ...@@ -72,12 +79,11 @@ function better_formats_defaults_admin_form_submit($form, &$form_state) {
} }
/** /**
* Process variables for better-formats-filter-admin-form.tpl.php. * Process variables for better-defaults-admin-form.tpl.php.
* *
* The $variables array contains the following arguments:
* - $form
*
* @param array $variables * @param array $variables
* The $variables array contains the following arguments:
* - $form
*/ */
function template_preprocess_better_formats_defaults_admin_form(&$variables) { function template_preprocess_better_formats_defaults_admin_form(&$variables) {
foreach (element_children($variables['form']) as $key) { foreach (element_children($variables['form']) as $key) {
......
// $Id$
/**
* @file
* Enhances the default format selection on content type edit forms.
*
* Fixes bug that shows weight field when drag and drop is enabled
* because the field is hidden by default.
* Also hides formats that are not available per the Allowed checkboxes.
*/
function better_formats_toggle_formats(el) { function better_formats_toggle_formats(el) {
$('select.bf-default-formats option').each(function() { $('select.bf-default-formats option').each(function() {
var option = $(this); var option = $(this);
......
<?php <?php
// $Id$
/**
* @file
* Contains FAPI and theme functions for the format settings form.
*/
/**
* FAPI form builder for admin/settings/filters/settings page.
*
* @see better_formats_menu()
*/
function better_formats_settings_admin_form() { function better_formats_settings_admin_form() {
$form = array(); $form = array();
......
Supports Markdown
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