Rumperuu/footnotes
Archived
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

docs: update docblocks

Browse source
This commit is contained in:
Ben Goldsworthy 2021-04-30 18:03:15 +01:00
parent bfeb11d5ad
commit 7ad975c389
16 changed files with 1168 additions and 1924 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

42
src/admin/class-footnotes-admin.php
View file

@ -1,29 +1,33 @@
<?php <?php
/** /**
* The admin-specific functionality of the plugin. * Admin: Footnotes_Admin class
* *
* The Admin. subpackage is initialised at runtime by the {@see Footnotes_Admin}
* class, which draws in the {@see Footnotes_WYSIWYG} class for WYSIWYG editor
* integration and the {@see footnotes\admin_layout} subpackage for rendering
* dashboard pages.
*
* @package footnotes\admin
* @since 2.8.0 * @since 2.8.0
*
* @package footnotes
* @subpackage admin
*/ */
/** /**
* The admin-specific functionality of the plugin. * Class provide all admin-specific functionality of the plugin.
* *
* Defines the plugin name, version, and enqueues all admin-specific stylesheets * Defines the plugin name, version, and enqueues all admin-specific stylesheets
* and JavaScript. * and JavaScript.
* *
* @package footnotes * @package footnotes\admin
* @subpackage admin * @since 2.8.0
*/ */
class Footnotes_Admin { class Footnotes_Admin {
/** /**
* The ID of this plugin. * The ID of this plugin.
* *
* @since 2.8.0
* @access private * @access private
* @since 2.8.0
* @see Footnotes::$plugin_name
* @var string $plugin_name The ID of this plugin. * @var string $plugin_name The ID of this plugin.
*/ */
private $plugin_name; private $plugin_name;
@ -31,8 +35,9 @@ class Footnotes_Admin {
/** /**
* The version of this plugin. * The version of this plugin.
* *
* @since 2.8.0
* @access private * @access private
* @since 2.8.0
* @see Footnotes::$version
* @var string $version The current version of this plugin. * @var string $version The current version of this plugin.
*/ */
private $version; private $version;
@ -47,10 +52,11 @@ class Footnotes_Admin {
/** /**
* Initialize the class and set its properties. * Initialize the class and set its properties.
*
* @since 2.8.0
* @param string $plugin_name The name of this plugin. * @param string $plugin_name The name of this plugin.
* @param string $version The version of this plugin. * @param string $version The version of this plugin.
*
* @since 2.8.0
*/ */
public function __construct( $plugin_name, $version ) { public function __construct( $plugin_name, $version ) {
@ -64,14 +70,15 @@ class Footnotes_Admin {
/** /**
* Load the required admin-specific dependencies. * Load the required admin-specific dependencies.
* *
* Include the following files that provide the admin-specific functionality * Includes the following files that provide the admin-specific functionality
* of this plugin: * of this plugin:
* *
* - `Footnotes_WYSIWYG`. Provides plugin integration with the WYSIWYG editor. * - {@see Footnotes_WYSIWYG}: Provides plugin integration with the WYSIWYG editor.
* - `Footnotes_Layout_Settings`. Defines the plugin dashboard page(s). * - {@see Footnotes_Layout_Settings}: Defines the plugin dashboard page(s).
*
* @access private
* *
* @since 2.8.0 * @since 2.8.0
* @access private
*/ */
private function load_dependencies() { private function load_dependencies() {
/** /**
@ -133,10 +140,11 @@ class Footnotes_Admin {
/** /**
* Appends the Plugin links for display in the dashboard Plugins page. * Appends the Plugin links for display in the dashboard Plugins page.
* *
* @since 1.5.0
* @since 2.8.0 Moved into `Footnote_Admin` class.
* @param string[] $links The default set of links to display. * @param string[] $links The default set of links to display.
* @return string[] The full set of links to display. * @return string[] The full set of links to display.
*
* @since 1.5.0
* @since 2.8.0 Moved from `Footnotes_Hooks` class to `Footnotes_Admin`.
*/ */
public function footnotes_action_links( array $links ): array { public function footnotes_action_links( array $links ): array {
// Append link to the WordPress Plugin page. // Append link to the WordPress Plugin page.

40
src/admin/class-footnotes-wysiwyg.php
View file

@ -1,16 +1,22 @@
<?php // phpcs:disable Squiz.Commenting.FileComment.Missing <?php
/** /**
* File provides WYSIWYG editor integration. * Admin: Footnotes_WYSIWYG class
* *
* The Admin. subpackage is initialised at runtime by the {@see Footnotes_Admin}
* class, which draws in the {@see Footnotes_WYSIWYG} class for WYSIWYG editor
* integration and the {@see footnotes\admin_layout} subpackage for rendering
* dashboard pages.
*
* @package footnotes\admin
* @since 1.5.0 * @since 1.5.0
* * @since 2.8.0 Rename file from `wysiwyg.php` to `class-footnotes-wysiwyg.php`,
* @package footnotes * move from `class/` sub-directory to `admin/`.
* @subpackage admin
*/ */
/** /**
* Handles the WSYIWYG-Buttons. * Class providing WYSIWYG editor intergration for the plugin.
* *
* @package footnotes\admin
* @since 1.5.0 * @since 1.5.0
*/ */
class Footnotes_WYSIWYG { class Footnotes_WYSIWYG {
@ -18,17 +24,19 @@ class Footnotes_WYSIWYG {
/** /**
* The ID of this plugin. * The ID of this plugin.
* *
* @since 2.8.0
* @access private * @access private
* @var string $plugin_name The ID of this plugin. * @var string $plugin_name The ID of this plugin.
*
* @since 2.8.0
*/ */
private $plugin_name; private $plugin_name;
/** /**
* Initialize the class and set its properties. * Initialize the class and set its properties.
* *
* @since 2.8.0
* @param string $plugin_name The name of this plugin. * @param string $plugin_name The name of this plugin.
*
* @since 2.8.0
*/ */
public function __construct( $plugin_name ) { public function __construct( $plugin_name ) {
@ -39,11 +47,11 @@ class Footnotes_WYSIWYG {
/** /**
* Append a new Button to the WYSIWYG editor of Posts and Pages. * Append a new Button to the WYSIWYG editor of Posts and Pages.
* *
* @since 1.5.0 * @param string[] $p_arr_buttons Already-defined editor buttons.
* @param array $p_arr_buttons pre defined Buttons from WordPress. * @return string[]
* @return array
* *
* @todo Does this need to be `static`? * @since 1.5.0
* @todo Should this be `static`?
*/ */
public static function new_visual_editor_button( $p_arr_buttons ) { public static function new_visual_editor_button( $p_arr_buttons ) {
array_push( $p_arr_buttons, 'footnotes' ); array_push( $p_arr_buttons, 'footnotes' );
@ -65,11 +73,11 @@ class Footnotes_WYSIWYG {
/** /**
* Includes the Plugins WYSIWYG editor script. * Includes the Plugins WYSIWYG editor script.
* *
* @since 1.5.0 * @param string[] $p_arr_plugins Scripts to be included by the editor.
* @param array $p_arr_plugins Scripts to be included to the editor. * @return string[]
* @return array
* *
* @todo Does this need to be `static`? * @since 1.5.0
* @todo Should this be `static`?
*/ */
public static function include_scripts( $p_arr_plugins ) { public static function include_scripts( $p_arr_plugins ) {
$p_arr_plugins['footnotes'] = plugins_url( '/../admin/js/wysiwyg-editor' . ( ( PRODUCTION_ENV ) ? '.min' : '' ) . '.js', __FILE__ ); $p_arr_plugins['footnotes'] = plugins_url( '/../admin/js/wysiwyg-editor' . ( ( PRODUCTION_ENV ) ? '.min' : '' ) . '.js', __FILE__ );

290
src/admin/layout/class-footnotes-layout-engine.php
View file

@ -1,104 +1,134 @@
<?php // phpcs:disable WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPress.Security.EscapeOutput.OutputNotEscaped <?php // phpcs:disable WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPress.Security.EscapeOutput.OutputNotEscaped
/** /**
* Includes Layout Engine for the admin dashboard. * Admin. Layouts: Footnotes_Layout_Engine class
* *
* The Admin. Layouts subpackage is composed of the {@see Footnotes_Layout_Engine}
* abstract class, which is extended by the {@see Footnotes_Layout_Settings}
* sub-class. The subpackage is initialised at runtime by the {@see
* Footnotes_Layout_Init} class.
*
* @package footnotes\admin_layout
* @since 1.5.0 * @since 1.5.0
* @since 2.1.2 add versioning of settings.css for cache busting * @since 2.8.0 Rename file from `layout.php` to `class-footnotes-layout-engine.php`,
* @since 2.1.4 automate passing version number for cache busting * rename `dashboard/` sub-directory to `layout/`.
* @since 2.1.4 optional step argument and support for floating in numbox
* @since 2.1.6 fix punctuation-related localization issue in dashboard labels
* @since 2.5.5 Bugfix: Stylesheets: minify to shrink the carbon footprint, increase speed and implement best practice, thanks to @docteurfitness issue report.
*
* @package footnotes
* @subpackage admin_layout
*/ */
require_once plugin_dir_path( dirname( __FILE__ ) ) . 'layout/class-footnotes-layout-init.php'; require_once plugin_dir_path( dirname( __FILE__ ) ) . 'layout/class-footnotes-layout-init.php';
/** /**
* Layout Engine for the administration dashboard. * Class to be extended by page layout sub-classes.
* *
* @abstract
* @package footnotes\admin_layout
* @since 1.5.0 * @since 1.5.0
*
* @package footnotes
* @subpackage admin_layout
*/ */
abstract class Footnotes_Layout_Engine { abstract class Footnotes_Layout_Engine {
/** /**
* The ID of this plugin. * The ID of this plugin.
* *
* @since 2.8.0 * @access protected
* @access private
* @var string $plugin_name The ID of this plugin. * @var string $plugin_name The ID of this plugin.
*
* @since 2.8.0
*/ */
protected $plugin_name; protected $plugin_name;
/** /**
* Stores the Hook connection string for the child sub page. * Stores the Hook connection string for the child sub-page.
*
* @access protected
* @var null|string
* *
* @since 1.5.0 * @since 1.5.0
* @var null|string
*/ */
protected $a_str_sub_page_hook = null; protected $a_str_sub_page_hook = null;
/** /**
* Stores all Sections for the child sub page. * Stores all Sections for the child sub-page.
*
* @access protected
* @var array
* *
* @since 1.5.0 * @since 1.5.0
* @var array
*/ */
protected $a_arr_sections = array(); protected $a_arr_sections = array();
/** /**
* Returns a Priority index. Lower numbers have a higher Priority. * Returns a Priority index. Lower numbers have a higher priority.
*
* @abstract
* @return int
* *
* @since 1.5.0 * @since 1.5.0
* @return int
*/ */
abstract public function get_priority(); abstract public function get_priority();
/** /**
* Returns the unique slug of the child sub page. * Returns the unique slug of the child sub-page.
*
* @abstract
* @access protected
* @return string
* *
* @since 1.5.0 * @since 1.5.0
* @return string
*/ */
abstract protected function get_sub_page_slug(); abstract protected function get_sub_page_slug();
/** /**
* Returns the title of the child sub page. * Returns the title of the child sub-page.
*
* @abstract
* @access protected
* @return string
* *
* @since 1.5.0 * @since 1.5.0
* @return string
*/ */
abstract protected function get_sub_page_title(); abstract protected function get_sub_page_title();
/** /**
* Returns an array of all registered sections for a sub page. * Returns an array of all registered sections for a sub-page.
*
* @abstract
* @access protected
* @return array
* *
* @since 1.5.0 * @since 1.5.0
* @return array
*/ */
abstract protected function get_sections(); abstract protected function get_sections();
/** /**
* Returns an array of all registered meta boxes. * Returns an array of all registered meta boxes.
* *
* @since 1.5.0 * @abstract
* @access protected
* @return array * @return array
*
* @since 1.5.0
*/ */
abstract protected function get_meta_boxes(); abstract protected function get_meta_boxes();
/** /**
* Returns an array describing a sub page section. * Returns an array describing a sub-page section.
* *
* @since 1.5.0 * @access protected
* @param string $p_str_id Unique ID suffix. * @param string $p_str_id Unique ID suffix.
* @param string $p_str_title Title of the section. * @param string $p_str_title Title of the section.
* @param int $p_int_settings_container_index Settings Container Index. * @param int $p_int_settings_container_index Settings Container index.
* @param bool $p_bool_has_submit_button Should a Submit Button be displayed for this section, default: true. * @param bool $p_bool_has_submit_button Whether a ‘Submit’ button should
* @return array Array describing the section. * be displayed for this section. Default `true`.
* @return array {
* A dashboard section.
*
* @type string $id Section ID.
* @type string $title Section title.
* @type bool $submit Whether the section has a submit button or not.
* @type int $container Settings Container index.
* }
*
* @since 1.5.0
* @todo Refactor sections into their own class?
*/ */
protected function add_section( $p_str_id, $p_str_title, $p_int_settings_container_index, $p_bool_has_submit_button = true ) { protected function add_section( $p_str_id, $p_str_title, $p_int_settings_container_index, $p_bool_has_submit_button = true ) {
return array( return array(
@ -112,12 +142,23 @@ abstract class Footnotes_Layout_Engine {
/** /**
* Returns an array describing a meta box. * Returns an array describing a meta box.
* *
* @since 1.5.0 * @access protected
* @param string $p_str_section_id Parent Section ID. * @param string $p_str_section_id Parent section ID.
* @param string $p_str_id Unique ID suffix. * @param string $p_str_id Unique ID suffix.
* @param string $p_str_title Title for the meta box. * @param string $p_str_title Title for the meta box.
* @param string $p_str_callback_function_name Class method name for callback. * @param string $p_str_callback_function_name Class method name for callback.
* @return array meta box description to be able to append a meta box to the output. * @return array {
* A dashboard meta box.
*
* @type string $parent Parent section ID.
* @type string $id Meta box ID.
* @type string $title Meta box title.
* @type string $callback Meta box callback function.
* }
*
* @since 1.5.0
* @todo Refactor meta boxes into their own class?
* @todo Pass actual functions rather than strings?
*/ */
protected function add_meta_box( $p_str_section_id, $p_str_id, $p_str_title, $p_str_callback_function_name ) { protected function add_meta_box( $p_str_section_id, $p_str_id, $p_str_title, $p_str_callback_function_name ) {
return array( return array(
@ -129,7 +170,7 @@ abstract class Footnotes_Layout_Engine {
} }
/** /**
* Registers a sub page. * Registers a sub-page.
* *
* @since 1.5.0 * @since 1.5.0
*/ */
@ -155,7 +196,7 @@ abstract class Footnotes_Layout_Engine {
} }
/** /**
* Registers all sections for a sub page. * Registers all sections for a sub-page.
* *
* @since 1.5.0 * @since 1.5.0
*/ */
@ -174,10 +215,12 @@ abstract class Footnotes_Layout_Engine {
} }
/** /**
* Registers all Meta boxes for a sub page. * Registers all Meta boxes for a sub-page.
*
* @access private
* @param string $p_str_parent_id Parent section unique ID.
* *
* @since 1.5.0 * @since 1.5.0
* @param string $p_str_parent_id Parent section unique id.
*/ */
private function register_meta_boxes( $p_str_parent_id ) { private function register_meta_boxes( $p_str_parent_id ) {
// Iterate through each meta box. // Iterate through each meta box.
@ -196,12 +239,14 @@ abstract class Footnotes_Layout_Engine {
} }
/** /**
* Append javascript and css files for specific sub page. * Append JavaScript and CSS files for specific sub-page.
*
* @access private
* *
* @since 1.5.0 * @since 1.5.0
* @todo Move to {@see Footnotes_Admin}.
*/ */
private function append_scripts() { private function append_scripts() {
// TODO: Move to `Footnotes_Admin`.
wp_enqueue_script( 'postbox' ); wp_enqueue_script( 'postbox' );
wp_enqueue_style( 'wp-color-picker' ); wp_enqueue_style( 'wp-color-picker' );
wp_enqueue_script( 'wp-color-picker' ); wp_enqueue_script( 'wp-color-picker' );
@ -209,15 +254,14 @@ abstract class Footnotes_Layout_Engine {
// phpcs:disable WordPress.Security.NonceVerification.Recommended, WordPress.Security.NonceVerification.Missing // phpcs:disable WordPress.Security.NonceVerification.Recommended, WordPress.Security.NonceVerification.Missing
/** /**
* Displays the content of specific sub page. * Displays the content of specific sub-page.
* *
* @since 1.5.0 * @since 1.5.0
* @todo Review nonce verification.
*/ */
public function display_content() { public function display_content() {
$this->append_scripts(); $this->append_scripts();
// TODO: add nonce verification.
// Get the current section. // Get the current section.
reset( $this->a_arr_sections ); reset( $this->a_arr_sections );
$l_str_active_section_id = isset( $_GET['t'] ) ? wp_unslash( $_GET['t'] ) : key( $this->a_arr_sections ); $l_str_active_section_id = isset( $_GET['t'] ) ? wp_unslash( $_GET['t'] ) : key( $this->a_arr_sections );
@ -280,10 +324,13 @@ abstract class Footnotes_Layout_Engine {
// phpcs:disable WordPress.Security.NonceVerification.Recommended, WordPress.Security.NonceVerification.Missing // phpcs:disable WordPress.Security.NonceVerification.Recommended, WordPress.Security.NonceVerification.Missing
/** /**
* Save all Plugin settings. * Save all plugin settings.
*
* @access private
* @return bool `true` on save success, else `false`.
* *
* @since 1.5.0 * @since 1.5.0
* @return bool * @todo Review nonce verification.
*/ */
private function save_settings() { private function save_settings() {
$l_arr_new_settings = array(); $l_arr_new_settings = array();
@ -309,35 +356,31 @@ abstract class Footnotes_Layout_Engine {
// phpcs:enable WordPress.Security.NonceVerification.Recommended, WordPress.Security.NonceVerification.Missing // phpcs:enable WordPress.Security.NonceVerification.Recommended, WordPress.Security.NonceVerification.Missing
/** /**
* Output the Description of a section. May be overwritten in any section. * Output the description of a section. May be overwritten in any section.
* *
* @since 1.5.0 * @since 1.5.0
* @todo Required? Should be `abstract`?
*/ */
public function description() { public function description() {
// Default no description will be displayed. // Default no description will be displayed.
} }
/** /**
* Loads specific setting and returns an array with the keys [id, name, value]. * Loads a specified setting.
*
* @access protected
* @param string $p_str_setting_key_name Setting key.
* @return array {
* A configurable setting.
*
* @type string $id Setting key.
* @type string $name Setting name.
* @type string $value Setting value.
* }
* *
* @since 1.5.0 * @since 1.5.0
* @param string $p_str_setting_key_name Settings Array key name. * @since 2.5.11 Broken due to accidental removal of `esc_attr()` call.
* @return array Contains Settings ID, Settings Name and Settings Value. * @since 2.6.1 Restore `esc_attr()` call.
*
* @since 2.5.11 Remove escapement function.
* When refactoring the codebase after 2.5.8, all and every output was escaped.
* After noticing that the plugin was broken, all escapement functions were removed.
* @link https://github.com/markcheret/footnotes/pull/50/commits/25c3f2f12eb5de1079e9215bf624ec4289b095a5
* @link https://github.com/markcheret/footnotes/pull/50#issuecomment-787624123
* In that process, this instance of esc_attr() was removed too, so the plugin was
* broken again.
* @link https://github.com/markcheret/footnotes/pull/50/commits/25c3f2f12eb5de1079e9215bf624ec4289b095a5#diff-a8ed6e859c32a18fc10bbbad3b4dd8ce7f43f2378d29471c7638e314ab30f1bdL349-L354
*
* @since 2.5.15 To fix it, the data was escaped in add_select_box() instead.
* @since 2.6.1 Restore esc_attr() in load_setting().
* @see add_select_box()
* This is the only instance of esc_|kses|sanitize in the pre-2.5.11 codebase.
* Removing this did not fix the quotation mark backslash escapement bug.
*/ */
protected function load_setting( $p_str_setting_key_name ) { protected function load_setting( $p_str_setting_key_name ) {
// Get current section. // Get current section.
@ -350,43 +393,29 @@ abstract class Footnotes_Layout_Engine {
} }
/** /**
* Returns a line break to start a new line. * Returns a simple text inside HTML `<span>` element.
*
* @access protected
* @param string $p_str_text Message to be surrounded with `<span>` tags.
* @return string
* *
* @since 1.5.0 * @since 1.5.0
* @return string * @todo Refactor HTML generation.
*/
protected function add_newline() {
return '<br/>';
}
/**
* Returns a line break to have a space between two lines.
*
* @since 1.5.0
* @return string
*/
protected function add_line_space() {
return '<br/><br/>';
}
/**
* Returns a simple text inside html <span> text.
*
* @since 1.5.0
* @param string $p_str_text Message to be surrounded with simple html tag (span).
* @return string
*/ */
protected function add_text( $p_str_text ) { protected function add_text( $p_str_text ) {
return sprintf( '<span>%s</span>', $p_str_text ); return sprintf( '<span>%s</span>', $p_str_text );
} }
/** /**
* Returns the html tag for an input/select label. * Returns the HTML tag for an `<input>`/`<select>` label.
* *
* @since 1.5.0 * @access protected
* @param string $p_str_setting_name Name of the Settings key to connect the Label with the input/select field. * @param string $p_str_setting_name Settings key.
* @param string $p_str_caption Label caption. * @param string $p_str_caption Label caption.
* @return string * @return string
*
* @since 1.5.0
* @todo Refactor HTML generation.
*/ */
protected function add_label( $p_str_setting_name, $p_str_caption ) { protected function add_label( $p_str_setting_name, $p_str_caption ) {
if ( empty( $p_str_caption ) ) { if ( empty( $p_str_caption ) ) {
@ -401,20 +430,24 @@ abstract class Footnotes_Layout_Engine {
* narrow per new school. * narrow per new school.
* Add colon to label strings for inclusion in localization. Colon after * Add colon to label strings for inclusion in localization. Colon after
* label is widely preferred best practice, mandatory per * label is widely preferred best practice, mandatory per
* [style guides](https://softwareengineering.stackexchange.com/questions/234546/colons-in-internationalized-ui). * {@link https://softwareengineering.stackexchange.com/questions/234546/colons-in-internationalized-ui
* style guides}.
*/ */
return sprintf( '<label for="%s">%s</label>', $p_str_setting_name, $p_str_caption ); return sprintf( '<label for="%s">%s</label>', $p_str_setting_name, $p_str_caption );
} }
/** /**
* Returns the html tag for an input [type = text]. * Constructs the HTML for a text `<input>` element.
*
* @access protected
* @param string $p_str_setting_name Setting key.
* @param int $p_str_max_length Maximum length of the input. Default length 999 chars.
* @param bool $p_bool_readonly Set the input to be read only. Default `false`.
* @param bool $p_bool_hidden Set the input to be hidden. Default `false`.
* @return string
* *
* @since 1.5.0 * @since 1.5.0
* @param string $p_str_setting_name Name of the Settings key to pre load the input field. * @todo Refactor HTML generation.
* @param int $p_str_max_length Maximum length of the input, default 999 characters.
* @param bool $p_bool_readonly Set the input to be read only, default false.
* @param bool $p_bool_hidden Set the input to be hidden, default false.
* @return string
*/ */
protected function add_text_box( $p_str_setting_name, $p_str_max_length = 999, $p_bool_readonly = false, $p_bool_hidden = false ) { protected function add_text_box( $p_str_setting_name, $p_str_max_length = 999, $p_bool_readonly = false, $p_bool_hidden = false ) {
$l_str_style = ''; $l_str_style = '';
@ -435,11 +468,14 @@ abstract class Footnotes_Layout_Engine {
} }
/** /**
* Returns the html tag for an input [type = checkbox]. * Constructs the HTML for a checkbox `<input>` element.
*
* @access protected
* @param string $p_str_setting_name Setting key.
* @return string
* *
* @since 1.5.0 * @since 1.5.0
* @param string $p_str_setting_name Name of the Settings key to pre load the input field. * @todo Refactor HTML generation.
* @return string
*/ */
protected function add_checkbox( $p_str_setting_name ) { protected function add_checkbox( $p_str_setting_name ) {
// Collect data for given settings field. // Collect data for given settings field.
@ -453,21 +489,15 @@ abstract class Footnotes_Layout_Engine {
} }
/** /**
* Returns the html tag for a select box. * Constructs the HTML for a `<select>` element.
* *
* @since 1.5.0 * @access protected
* * @param string $p_str_setting_name Setting key.
* - Bugfix: Dashboard: Referrers and tooltips: Backlink symbol: debug select box by reverting identity check to equality check, thanks to @lolzim bug report. * @param array $p_arr_options Possible options.
*
* @reporter @lolzim
*
* @since 2.5.13
* @param string $p_str_setting_name Name of the Settings key to pre select the current value.
* @param array $p_arr_options Possible options to be selected.
* @return string * @return string
* *
* @since 2.5.15 Bugfix: Dashboard: General settings: Footnote start and end short codes: debug select box for shortcodes with pointy brackets. * @since 1.5.0
* @since 2.6.1 Restore esc_attr() in load_setting(), remove htmlspecialchars() here. * @todo Refactor HTML generation.
*/ */
protected function add_select_box( $p_str_setting_name, $p_arr_options ) { protected function add_select_box( $p_str_setting_name, $p_arr_options ) {
// Collect data for given settings field. // Collect data for given settings field.
@ -495,11 +525,14 @@ abstract class Footnotes_Layout_Engine {
} }
/** /**
* Returns the html tag for a text area. * Constructs the HTML for a `<textarea>` element.
*
* @access protected
* @param string $p_str_setting_name Setting key.
* @return string
* *
* @since 1.5.0 * @since 1.5.0
* @param string $p_str_setting_name Name of the Settings key to pre fill the text area. * @todo Refactor HTML generation.
* @return string
*/ */
protected function add_textarea( $p_str_setting_name ) { protected function add_textarea( $p_str_setting_name ) {
// Collect data for given settings field. // Collect data for given settings field.
@ -513,11 +546,16 @@ abstract class Footnotes_Layout_Engine {
} }
/** /**
* Returns the html tag for an input [type = text] with color selection class. * Constructs the HTML for a text `<input>` element with the colour selection
* class.
*
* @access protected
* @param string $p_str_setting_name Setting key.
* @return string
* *
* @since 1.5.6 * @since 1.5.6
* @param string $p_str_setting_name Name of the Settings key to pre load the input field. * @todo Refactor HTML generation.
* @return string * @todo Use proper colorpicker element.
*/ */
protected function add_color_selection( $p_str_setting_name ) { protected function add_color_selection( $p_str_setting_name ) {
// Collect data for given settings field. // Collect data for given settings field.
@ -531,17 +569,17 @@ abstract class Footnotes_Layout_Engine {
} }
/** /**
* Returns the html tag for an input [type = num]. * Constructs the HTML for numeric `<input>` element.
* *
* @since 1.5.0 * @access protected
* @param string $p_str_setting_name Name of the Settings key to pre load the input field. * @param string $p_str_setting_name Setting key.
* @param int $p_in_min Minimum value. * @param int $p_in_min Minimum value.
* @param int $p_int_max Maximum value. * @param int $p_int_max Maximum value.
* @param bool $p_bool_deci true if 0.1 steps and floating to string, false if integer (default). * @param bool $p_bool_deci `true` if float, `false` if integer. Default `false`.
* @return string * @return string
* *
* Edited: * @since 1.5.0
* @since 2.1.4 step argument and number_format() to allow decimals .. * @todo Refactor HTML generation.
*/ */
protected function add_num_box( $p_str_setting_name, $p_in_min, $p_int_max, $p_bool_deci = false ) { protected function add_num_box( $p_str_setting_name, $p_in_min, $p_int_max, $p_bool_deci = false ) {
// Collect data for given settings field. // Collect data for given settings field.

51
src/admin/layout/class-footnotes-layout-init.php
View file

@ -1,50 +1,56 @@
<?php // phpcs:disable WordPress.Security.ValidatedSanitizedInput.InputNotSanitized <?php // phpcs:disable WordPress.Security.ValidatedSanitizedInput.InputNotSanitized
/** /**
* Includes the Plugin settings menu. * Admin. Layouts: Footnotes_Layout_Init class
* *
* The Admin. Layouts subpackage is composed of the {@see Footnotes_Layout_Engine}
* abstract class, which is extended by the {@see Footnotes_Layout_Settings}
* sub-class. The subpackage is initialised at runtime by the {@see
* Footnotes_Layout_Init} class.
*
* @package footnotes\admin_layout
* @since 1.5.0 * @since 1.5.0
* * @since 2.8.0 Rename file from `init.php` to `class-footnotes-layout-init.php`,
* @package footnotes * rename `dashboard/` sub-directory to `layout/`.
* @subpackage admin_layout
*/ */
/** /**
* Handles the Settings interface of the Plugin. * Class to initialise all defined page layouts.
* *
* @package footnotes\admin_layout
* @since 1.5.0 * @since 1.5.0
*
* @package footnotes
* @subpackage admin_layout
*/ */
class Footnotes_Layout_Init { class Footnotes_Layout_Init {
/** /**
* The ID of this plugin. * The ID of this plugin.
* *
* @since 2.8.0
* @access private * @access private
* @var string $plugin_name The ID of this plugin. * @var string $plugin_name The ID of this plugin.
*
* @since 2.8.0
*/ */
private $plugin_name; private $plugin_name;
/** /**
* Slug for the Plugin main menu. * Slug for the Plugin main menu.
* *
* @since 1.5.0
* @var string * @var string
*
* @since 1.5.0
*/ */
const C_STR_MAIN_MENU_SLUG = 'footnotes'; const C_STR_MAIN_MENU_SLUG = 'footnotes';
/** /**
* Contains the settings layoutEngine * Contains the settings page.
*
* @var Footnotes_Layout_Settings
* *
* @since 1.5.0 * @since 1.5.0
* @var array
*/ */
private $settings_page; private $settings_page;
/** /**
* Class Constructor. Initializes all WordPress hooks for the Plugin Settings. * Initializes all WordPress hooks for the Plugin Settings.
* *
* @param string $plugin_name The name of the plugin. * @param string $plugin_name The name of the plugin.
* *
@ -65,34 +71,33 @@ class Footnotes_Layout_Init {
add_action( 'wp_ajax_nopriv_footnotes_get_plugin_info', array( $this, 'get_plugin_meta_information' ) ); add_action( 'wp_ajax_nopriv_footnotes_get_plugin_info', array( $this, 'get_plugin_meta_information' ) );
add_action( 'wp_ajax_footnotes_get_plugin_info', array( $this, 'get_plugin_meta_information' ) ); add_action( 'wp_ajax_footnotes_get_plugin_info', array( $this, 'get_plugin_meta_information' ) );
} }
/** /**
* Load the required dependencies for this plugin. * Load the required dependencies for the layouts pages.
* *
* Include the following files that make up the plugin: * Include the following files that make up the plugin:
* *
* - `Footnotes_Config`. Defines constant plugin values. * - {@see Footnotes_Config}: defines plugin constants;
* - `Footnotes_Settings`. Defines configurable plugin settings. * - {@see Footnotes_Settings}: defines configurable plugin settings; and
* - `Footnotes_Layout_Settings`. Defines the plugin settings page. * - {@see Footnotes_Layout_Settings}: defines the plugin settings page.
* *
* Create an instance of the loader which will be used to register the hooks * @access private
* with WordPress.
* *
* @since 2.8.0 * @since 2.8.0
* @access private
*/ */
private function load_dependencies() { private function load_dependencies() {
/** /**
* The class responsible for defining plugin constants. * Defines plugin constants.
*/ */
require_once plugin_dir_path( dirname( __FILE__, 2 ) ) . 'includes/class-footnotes-config.php'; require_once plugin_dir_path( dirname( __FILE__, 2 ) ) . 'includes/class-footnotes-config.php';
/** /**
* The class responsible for tracking configurable plugin settings. * Defines configurable plugin settings.
*/ */
require_once plugin_dir_path( dirname( __FILE__, 2 ) ) . 'includes/class-footnotes-settings.php'; require_once plugin_dir_path( dirname( __FILE__, 2 ) ) . 'includes/class-footnotes-settings.php';
/** /**
* The class responsible for defining the plugin settings page. * Represents the plugin settings dashboard page.
*/ */
require_once plugin_dir_path( dirname( __FILE__ ) ) . 'layout/class-footnotes-layout-settings.php'; require_once plugin_dir_path( dirname( __FILE__ ) ) . 'layout/class-footnotes-layout-settings.php';
} }

216
src/admin/layout/class-footnotes-layout-settings.php
View file

@ -1,55 +1,30 @@
<?php // phpcs:disable Squiz.Commenting.FileComment.Missing <?php // phpcs:disable Squiz.Commenting.FileComment.Missing
/** /**
* Includes the Plugin Class to display all Settings. * Admin. Layouts: Footnotes_Layout_Settings class
* *
* The Admin. Layouts subpackage is composed of the {@see Footnotes_Layout_Engine}
* abstract class, which is extended by the {@see Footnotes_Layout_Settings}
* sub-class. The subpackage is initialised at runtime by the {@see
* Footnotes_Layout_Init} class.
*
* @package footnotes\admin_layout
* @since 1.5.0 * @since 1.5.0
* @since 2.0.4 restore arrow settings * @since 2.8.0 Rename file from `subpage-main.php` to `class-footnotes-layout-settings.php`,
* @since 2.1.0 read-on button label * rename `dashboard/` sub-directory to `layout/`.
* @since 2.1.1 options for ref container and alternative tooltips
* @since 2.1.1 Referrers: superscript becomes optional, thanks to @cwbayer bug report
* @since 2.1.2 priority level settings for all other hooks, thanks to @nikelaos
* @link https://wordpress.org/support/topic/doesnt-work-any-more-11/#post-13676705
* @since 2.1.4 settings for ref container, tooltips and scrolling
* @since 2.1.6 slight UI reordering
* @since 2.1.6 option to disable URL line wrapping
* @since 2.1.6 remove expert mode setting as outdated
* @since 2.2.0 start/end short codes: more predefined options, thanks to @nikelaos
* @link https://wordpress.org/support/topic/doesnt-work-with-mailpoet/
* @since 2.2.0 add options, redistribute, update strings
* @since 2.2.0 shortcode for reference container custom position
* @since 2.2.2 Custom CSS settings container migration
* @since 2.2.4 move backlink symbol selection under previous tab
* @since 2.2.5 support for Ibid. notation thanks to @meglio
* @link https://wordpress.org/support/topic/add-support-for-ibid-notation/
* @since 2.2.5 options for label element and label bottom border, thanks to @markhillyer
* @link https://wordpress.org/support/topic/how-do-i-eliminate-the-horizontal-line-beneath-the-reference-container-heading/
* @since 2.2.10 reference container row border option, thanks to @noobishh
* @link https://wordpress.org/support/topic/borders-25/
* @since 2.3.0 Reference container: convert top padding to margin and make it a setting, thanks to @hamshe
* @link https://wordpress.org/support/topic/reference-container-in-elementor/#post-13786635
* @since 2.3.0 rename Priority level tab as Scope and priority
* @since 2.3.0 swap Custom CSS migration Boolean from 'migration complete' to 'show legacy'
* @since 2.3.0 mention op. cit. abbreviation
* @since 2.3.0 add settings for hard links, thanks to @psykonevro and @martinneumannat
* @link https://wordpress.org/support/topic/making-it-amp-compatible/
* @link https://wordpress.org/support/topic/footnotes-is-not-amp-compatible/
* @since 2.4.0 footnote shortcode syntax validation
* @since 2.5.0 Shortcode syntax validation: add more information around the setting, thanks to @andreasra
* @link https://wordpress.org/support/topic/warning-unbalanced-footnote-start-tag-short-code-before/
*
* @package footnotes
* @subpackage admin_layout
*/ */
/**
* Provides the abstract class to be extended for page layouts.
*/
require_once plugin_dir_path( dirname( __FILE__ ) ) . 'layout/class-footnotes-layout-engine.php'; require_once plugin_dir_path( dirname( __FILE__ ) ) . 'layout/class-footnotes-layout-engine.php';
/** /**
* Displays and handles all Settings of the Plugin. * Class to initialise all defined page layouts.
* *
* @since 1.5.0 * @since 1.5.0
* @package footnotes\admin_layout
* *
* @package footnotes * @see Footnotes_Layout_Engine
* @subpackage admin_layout
*/ */
class Footnotes_Layout_Settings extends Footnotes_Layout_Engine { class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
@ -64,7 +39,9 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
} }
/** /**
* Returns a Priority index. Lower numbers have a higher Priority. * Returns a priority index.
*
* Lower numbers have a higher priority.
* *
* @since 1.5.0 * @since 1.5.0
* @return int * @return int
@ -74,7 +51,7 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
} }
/** /**
* Returns the unique slug of the sub page. * Returns the unique slug of the sub-page.
* *
* @since 1.5.0 * @since 1.5.0
* @return string * @return string
@ -84,7 +61,7 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
} }
/** /**
* Returns the title of the sub page. * Returns the title of the sub-page.
* *
* @since 1.5.0 * @since 1.5.0
* @return string * @return string
@ -94,16 +71,14 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
} }
/** /**
* Returns an array of all registered sections for the sub page. * Returns an array of all registered sections for the sub-page.
*
* @see Footnotes_Layout_Engine::add_section() For more information on the
* section array format.
* @return array[] All of the registered sections.
* *
* @since 1.5.0 * @since 1.5.0
* @return array * @since 2.1.6 Remove conditional rendering of ‘Expert’ tab.
*
* Edited:
* @since 2.1.6 tabs reordered and renamed
* @link https://www.linkedin.com/pulse/20140610191154-4746170-configuration-vs-customization-when-and-why-would-i-implement-each
*
* @since 2.1.6 removed if statement around expert tab
*/ */
protected function get_sections() { protected function get_sections() {
$l_arr_tabs = array(); $l_arr_tabs = array();
@ -122,25 +97,14 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
} }
/** /**
* Returns an array of all registered meta boxes for each section of the sub page. * Returns an array of all registered meta boxes for each section of the sub-page.
*
* @see Footnotes_Layout_Engine::add_meta_box() For more information on the
* meta box array format.
* @return array[] All of the registered meta boxes.
* *
* @since 1.5.0 * @since 1.5.0
* @return array * @since 2.2.0 Re-order and rename tabs.
*
* Edited for 2.0.0 and later.
*
* hyperlink_arrow meta box:
* @since 2.0.0 discontinued
* @since 2.0.4 restored to meet user demand for arrow symbol semantics
* @since 2.1.4 discontinued, content moved to Settings > Reference container > Display a backlink symbol
*
* @since 2.0.4 to reflect changes in meta box label display since WPv5.5
* spans need position:fixed and become unlocalizable
* fix: logo is kept only in the label that doesn't need to be translated:
* Change string "%s styling" to "Footnotes styling" to fix layout in WPv5.5
* @see details in class/config.php
*
* @since 2.1.6 / 2.2.0 tabs reordered and renamed
*/ */
protected function get_meta_boxes() { protected function get_meta_boxes() {
$l_arr_meta_boxes = array(); $l_arr_meta_boxes = array();
@ -184,7 +148,6 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
/** /**
* Displays the AMP compatibility mode option. * Displays the AMP compatibility mode option.
* *
* @since 2.5.11 (draft)
* @since 2.6.0 (release) * @since 2.6.0 (release)
*/ */
public function amp_compat() { public function amp_compat() {
@ -213,11 +176,6 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
* Displays all settings for the reference container. * Displays all settings for the reference container.
* *
* @since 1.5.0 * @since 1.5.0
*
* Completed:
* @since 2.1.4: layout and typography options
* @since 2.2.5 options for label element and label bottom border, thanks to @markhillyer
* @link https://wordpress.org/support/topic/how-do-i-eliminate-the-horizontal-line-beneath-the-reference-container-heading/
*/ */
public function reference_container() { public function reference_container() {
@ -250,10 +208,12 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
'semicolon' => __( 'SEMICOLON', 'footnotes' ), 'semicolon' => __( 'SEMICOLON', 'footnotes' ),
'en_dash' => __( 'EN DASH', 'footnotes' ), 'en_dash' => __( 'EN DASH', 'footnotes' ),
); );
// Options for the terminating punctuation after backlinks. /*
// The Unicode name of RIGHT PARENTHESIS was originally more accurate because. * Options for the terminating punctuation after backlinks.
// This character is bidi-mirrored. Let's use the Unicode 1.0 name. * The Unicode name of RIGHT PARENTHESIS was originally more accurate because.
// The wrong names were enforced in spite of Unicode, that subsequently scrambled to correct. * This character is bidi-mirrored. Let's use the Unicode 1.0 name.
* The wrong names were enforced in spite of Unicode, that subsequently scrambled to correct.
*/
$l_arr_terminators = array( $l_arr_terminators = array(
'period' => __( 'FULL STOP', 'footnotes' ), 'period' => __( 'FULL STOP', 'footnotes' ),
// Unicode 1.0 name of RIGHT PARENTHESIS (represented as a left parenthesis in right-to-left scripts). // Unicode 1.0 name of RIGHT PARENTHESIS (represented as a left parenthesis in right-to-left scripts).
@ -390,17 +350,6 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
* Displays all options for the footnotes start and end tag short codes. * Displays all options for the footnotes start and end tag short codes.
* *
* @since 1.5.0 * @since 1.5.0
*
* Edited heading
* @since 2.2.0 start/end short codes: more predefined options
* @link https://wordpress.org/support/topic/doesnt-work-with-mailpoet/
* @since 2.2.0 3 boxes for clarity
* @since 2.2.5 support for Ibid. notation thanks to @meglio
* @link https://wordpress.org/support/topic/add-support-for-ibid-notation/
* @since 2.4.0 added warning about Block Editor escapement disruption
* @since 2.4.0 removed the HTML comment tag option
* @since 2.5.0 Shortcode syntax validation: add more information around the setting, thanks to @andreasra
* @link https://wordpress.org/support/topic/warning-unbalanced-footnote-start-tag-short-code-before/
*/ */
public function start_end() { public function start_end() {
// Footnotes start tag short code options. // Footnotes start tag short code options.
@ -578,8 +527,7 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
/** /**
* Displays all options for the fragment identifier configuration. * Displays all options for the fragment identifier configuration.
* *
* @since 2.2.0 in scrolling(). * @since 2.2.0
* @since 2.5.12 separate metabox.
*/ */
public function hard_links() { public function hard_links() {
@ -629,13 +577,9 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
} }
/** /**
* Displays all settings for 'I love Footnotes'. * Displays all settings for ‘I love Footnotes’ note.
* *
* @since 1.5.0 * @since 1.5.0
*
* Edited:
* @since 2.2.0 position-sensitive placeholders to support more locales
* @since 2.2.0 more options
*/ */
public function love() { public function love() {
// Options for the acknowledgment display in the footer. // Options for the acknowledgment display in the footer.
@ -682,12 +626,6 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
* Displays the footnotes in excerpt setting. * Displays the footnotes in excerpt setting.
* *
* @since 1.5.0 * @since 1.5.0
*
* Edited heading
* @since 2.1.1 more settings and notices, thanks to @nikelaos
* @link https://wordpress.org/support/topic/doesnt-work-any-more-11/#post-13687068
* @link https://wordpress.org/support/topic/jquery-comes-up-in-feed-content/#post-13110879
* @since 2.2.0 dedicated to the excerpt setting and its notices
*/ */
public function excerpts() { public function excerpts() {
// Options for options select box. // Options for options select box.
@ -720,10 +658,6 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
* Displays all settings for the footnote referrers. * Displays all settings for the footnote referrers.
* *
* @since 1.5.0 * @since 1.5.0
*
* Edited heading
* @since 2.1.1 option for superscript (optionally baseline referrers)
* @since 2.2.0 option for link element moved here
*/ */
public function superscript() { public function superscript() {
// Options for Yes/No select box. // Options for Yes/No select box.
@ -798,10 +732,6 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
* Displays enabled status for the footnotes mouse-over box. * Displays enabled status for the footnotes mouse-over box.
* *
* @since 1.5.2 * @since 1.5.2
*
* Edited:
* @since 2.2.0 5 parts to address increased settings number
* @since 2.2.5 position settings for alternative tooltips
*/ */
public function mouseover_box() { public function mouseover_box() {
// Options for Yes/No select box. // Options for Yes/No select box.
@ -1105,25 +1035,6 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
* Displays all settings for the backlink symbol. * Displays all settings for the backlink symbol.
* *
* @since 1.5.0 * @since 1.5.0
*
* - Update: **symbol for backlinks** removed; hyperlink moved to the reference number.
*
* @since 2.0.0
* The former 'hyperlink arrow' is incompatible with combined identical footnotes.
*
* - Update: Reference container: clarify backlink semantics by prepended transitional up arrow, thanks to @mmallett issue report.
*
* @since 2.0.3
*
* - Update: Restore arrow settings to customize or disable the now prepended arrow symbol, thanks to @mmallett issue report.
*
* @since 2.0.4
*
* @reporter @mmallett
* @link https://wordpress.org/support/topic/mouse-over-broken/#post-13593037
*
* @since 2.1.4 moved to Settings > Reference container > Display a backlink symbol
* @since 2.2.1 and 2.2.4 back here
*/ */
public function hyperlink_arrow() { public function hyperlink_arrow() {
// Load template file. // Load template file.
@ -1148,15 +1059,6 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
* Displays the Custom CSS box. * Displays the Custom CSS box.
* *
* @since 1.5.0 * @since 1.5.0
*
* Edited:
* @since 2.1.6 drop localized notices for CSS classes as the number increased to 16
* list directly in the template, as CSS is in English anyway
* @link ../partials/customize-css.html
*
* @since 2.2.2 migrate Custom CSS to a dedicated tab
* @since 2.3.0 say 'copy-paste' instead of 'cut and paste' since cutting is not needed
* @since 2.5.1 mention validity while visible, thanks to @rkupadhya bug report
*/ */
public function custom_css() { public function custom_css() {
// Load template file. // Load template file.
@ -1196,6 +1098,7 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
* Displays transitional legacy Custom CSS box. * Displays transitional legacy Custom CSS box.
* *
* @since 2.2.2 * @since 2.2.2
* @deprecated
*/ */
public function custom_css_migration() { public function custom_css_migration() {
@ -1254,20 +1157,14 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
/** /**
* Displays available Hooks to look for Footnote short codes. * Displays available Hooks to look for Footnote short codes.
* *
* Priority level was initially a hard-coded default
* shows ‘9223372036854775807’ in the numbox
* empty should be interpreted as `PHP_INT_MAX`,
* but a numbox cannot be set to empty, see {@link https://github.com/Modernizr/Modernizr/issues/171
* here}
* define -1 as `PHP_INT_MAX` instead
*
* @since 1.5.5 * @since 1.5.5
*
* Edited:
* @since 2.1.1 priority level setting for the_content
* @since 2.1.4 priority level settings for the other hooks
*
* priority level was initially hard-coded default
* shows "9223372036854775807" in the numbox
* empty should be interpreted as PHP_INT_MAX,
* but a numbox cannot be set to empty: <https://github.com/Modernizr/Modernizr/issues/171>
* define -1 as PHP_INT_MAX instead
*
* @since 2.2.9 removed the warning about the widget text hook
* @since 2.2.9 added guidance for the widget text hook
*/ */
public function lookup_hooks() { public function lookup_hooks() {
// Load template file. // Load template file.
@ -1321,12 +1218,9 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
} }
/** /**
* Displays a short introduction to the Plugin. * Displays a short introduction to the plugin.
* *
* @since 1.5.0 * @since 1.5.0
*
* @since 2.7.0 Sanitize Lorem Ipsum filler text.
* @link https://blog.prototypr.io/why-testing-with-real-content-is-better-than-lorem-ipsum-c7c79586ee72
*/ */
public function Help() { public function Help() {
global $footnotes; global $footnotes;
@ -1371,19 +1265,13 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
) )
); );
/** /*
* Call footnotes_output_head function to get the Styling of the mouse-over box. * Call {@see Footnotes_Parser::footnotes_output_head()} function to get
* the styling of the mouse-over box.
* *
* - Bugfix: Dashboard: debug the 'Quick start guide' tab, thanks to @rumperuu bug report.
*
* @reporter @rumperuu
* @link https://github.com/markcheret/footnotes/issues/71
*
* @since 2.7.0
* The name of the callback function ought to be distinct from * The name of the callback function ought to be distinct from
* the name of the filtered function. * the name of the filtered function.
* When this callback function was renamed, this call went unnoticed. * When this callback function was renamed, this call went unnoticed.
* @see class/task.php
*/ */
$footnotes->a_obj_task->footnotes_output_head(); $footnotes->a_obj_task->footnotes_output_head();

6
src/includes/class-footnotes-config.php
View file

@ -6,7 +6,8 @@
* @subpackage includes * @subpackage includes
* *
* @since 1.5.0 * @since 1.5.0
* @since 2.8.0 Rename file from `config.php` to `class-footnotes-config.php`. * @since 2.8.0 Rename file from `config.php` to `class-footnotes-config.php`,
* rename `class/` sub-directory to `includes/`.
* @todo Remove. * @todo Remove.
* @deprecated * @deprecated
*/ */
@ -16,6 +17,9 @@
* *
* This class contains no methods of properties. * This class contains no methods of properties.
* *
* @package footnotes
* @subpackage includes
*
* @since 1.5.0 * @since 1.5.0
* @todo Remove. * @todo Remove.
* @deprecated * @deprecated

6
src/includes/class-footnotes-convert.php
View file

@ -6,12 +6,16 @@
* @subpackage includes * @subpackage includes
* *
* @since 1.5.0 * @since 1.5.0
* @since 2.8.0 Rename file from `convert.php` to `class-footnotes-convert.php`. * @since 2.8.0 Rename file from `convert.php` to `class-footnotes-convert.php`,
* rename `class/` sub-directory to `includes/`.
*/ */
/** /**
* Class providing variable type and value conversion functions. * Class providing variable type and value conversion functions.
* *
* @package footnotes
* @subpackage includes
*
* @since 1.5.0 * @since 1.5.0
*/ */
class Footnotes_Convert { class Footnotes_Convert {

3
src/includes/class-footnotes-i18n.php
View file

@ -6,7 +6,8 @@
* @subpackage includes * @subpackage includes
* *
* @since 1.5.0 * @since 1.5.0
* @since 2.8.0 Rename file from `language.php` to `class-footnotes-i18n.php`. * @since 2.8.0 Rename file from `language.php` to `class-footnotes-i18n.php`,
* rename `class/` sub-directory to `includes/`.
*/ */
require_once plugin_dir_path( dirname( __FILE__ ) ) . 'includes/class-footnotes-config.php'; require_once plugin_dir_path( dirname( __FILE__ ) ) . 'includes/class-footnotes-config.php';

822
src/includes/class-footnotes-settings.php
View file

File diff suppressed because it is too large Load diff

3
src/includes/class-footnotes-template.php
View file

@ -8,7 +8,8 @@
* *
* @since 1.5.0 * @since 1.5.0
* @since 2.2.6 Add support for custom templates in sibling folder. * @since 2.2.6 Add support for custom templates in sibling folder.
* @since 2.8.0 Rename file from `templates.php` to `class-footnotes-templates.php`. * @since 2.8.0 Rename file from `templates.php` to `class-footnotes-templates.php`,
* rename `class/` sub-directory to `includes/`.
*/ */
/** /**

3
src/includes/class-footnotes.php
View file

@ -9,7 +9,8 @@
* @subpackage includes * @subpackage includes
* *
* @since 1.5.0 * @since 1.5.0
* @since 2.8.0 Rename file from `init.php` to `class-footnotes.php`. * @since 2.8.0 Rename file from `wysiwyg.php` to `class-footnotes-wysiwyg.php`,
* rename `class/` sub-directory to `includes/`.
*/ */
/** /**

931
src/public/class-footnotes-parser.php
View file

File diff suppressed because it is too large Load diff

68
src/public/class-footnotes-public.php
View file

@ -2,20 +2,18 @@
/** /**
* The public-facing functionality of the plugin. * The public-facing functionality of the plugin.
* *
* @package footnotes\public
* @since 2.8.0 * @since 2.8.0
*
* @package footnotes
* @subpackage public
*/ */
/** /**
* The public-facing functionality of the plugin. * Class provide all admin-specific functionality of the plugin.
* *
* Defines the plugin name, version, and enqueues all public-facing stylesheets * Defines the plugin name, version, and enqueues all public-facing stylesheets
* and JavaScript. * and JavaScript.
* *
* @package footnotes * @package footnotes\public
* @subpackage public * @since 2.8.0
*/ */
class Footnotes_Public { class Footnotes_Public {
@ -23,6 +21,7 @@ class Footnotes_Public {
* The ID of this plugin. * The ID of this plugin.
* *
* @since 2.8.0 * @since 2.8.0
* @access private * @access private
* @var string $plugin_name The ID of this plugin. * @var string $plugin_name The ID of this plugin.
*/ */
@ -32,6 +31,7 @@ class Footnotes_Public {
* The version of this plugin. * The version of this plugin.
* *
* @since 2.8.0 * @since 2.8.0
* @access private * @access private
* @var string $version The current version of this plugin. * @var string $version The current version of this plugin.
*/ */
@ -41,6 +41,7 @@ class Footnotes_Public {
* The reference container widget. * The reference container widget.
* *
* @since 2.8.0 * @since 2.8.0
*
* @var Footnotes_Widget_Reference_Container $reference_container_widget The reference container widget * @var Footnotes_Widget_Reference_Container $reference_container_widget The reference container widget
*/ */
private $reference_container_widget; private $reference_container_widget;
@ -49,8 +50,9 @@ class Footnotes_Public {
* The footnote parser. * The footnote parser.
* *
* @since 1.5.0 * @since 1.5.0
* @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class. * @since 2.8.0 Moved from {@see Footnotes} to {@see Footnotes_Public}.
* @var Footnote_Parser $task The Plugin task. *
* @var Footnotes_Parser $task The Plugin task.
*/ */
public $a_obj_task = null; public $a_obj_task = null;
@ -58,7 +60,8 @@ class Footnotes_Public {
* Flag for using tooltips. * Flag for using tooltips.
* *
* @since 2.4.0 * @since 2.4.0
* @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class. * @since 2.8.0 Moved from {@see Footnotes} to {@see Footnotes_Public}.
*
* @var bool $tooltips_enabled Whether tooltips are enabled or not. * @var bool $tooltips_enabled Whether tooltips are enabled or not.
*/ */
public static $a_bool_tooltips_enabled = false; public static $a_bool_tooltips_enabled = false;
@ -67,7 +70,8 @@ class Footnotes_Public {
* Allows to determine whether alternative tooltips are enabled. * Allows to determine whether alternative tooltips are enabled.
* *
* @since 2.1.1 * @since 2.1.1
* @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class. * @since 2.8.0 Moved from {@see Footnotes} to {@see Footnotes_Public}.
*
* @var bool * @var bool
*/ */
public static $a_bool_alternative_tooltips_enabled = false; public static $a_bool_alternative_tooltips_enabled = false;
@ -75,8 +79,9 @@ class Footnotes_Public {
/** /**
* Allows to determine whether AMP compatibility mode is enabled. * Allows to determine whether AMP compatibility mode is enabled.
* *
* @since 2.6.0 (release) * @since 2.6.0
* @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class. * @since 2.8.0 Moved from {@see Footnotes} to {@see Footnotes_Public}.
*
* @var bool * @var bool
*/ */
public static $a_bool_amp_enabled = false; public static $a_bool_amp_enabled = false;
@ -85,9 +90,9 @@ class Footnotes_Public {
* Allows to determine the script mode among jQuery or plain JS. * Allows to determine the script mode among jQuery or plain JS.
* *
* @since 2.5.6 * @since 2.5.6
* @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class. * @since 2.8.0 Moved from {@see Footnotes} to {@see Footnotes_Public}.
* @var str 'js' Plain JavaScript. *
* 'jquery' Use jQuery libraries. * @var string ‘js’ to use plain JavaScript, ‘jquery’ to use jQuery.
*/ */
public static $a_str_script_mode = 'js'; public static $a_str_script_mode = 'js';
@ -118,11 +123,10 @@ class Footnotes_Public {
* Include the following files that provide the public-facing functionality * Include the following files that provide the public-facing functionality
* of this plugin: * of this plugin:
* *
* - `Footnotes_Parser`. Parses Posts and Pages for footnote shortcodes. * - {@see Footnotes_Parser}: parses Posts and Pages for footnote shortcodes; and
* - `Footnotes_Widget_Reference_Container`. Defines the Reference Container widget. * - {@see Footnotes_Widget_Reference_Container}: defines the Reference Container widget.
* *
* @since 2.8.0 * @since 2.8.0
* @access private
*/ */
private function load_dependencies() { private function load_dependencies() {
// TODO: neaten up and document once placements and names are settled. // TODO: neaten up and document once placements and names are settled.
@ -141,12 +145,12 @@ class Footnotes_Public {
/** /**
* Register the stylesheets for the public-facing side of the site. * Register the stylesheets for the public-facing side of the site.
* *
* Enables enqueuing the formatted individual stylesheets if `PRODCUTION_ENV` * Enables enqueuing the formatted individual stylesheets if {@see PRODUCTION_ENV}
* is true (set in `footnotes.php`). * is `true`.
* *
* @since 1.5.0 * @since 1.5.0
* @since 2.5.5 Change stylesheet scheme. * @since 2.5.5 Change stylesheet schema.
* @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class. * @since 2.8.0 Moved from {@see Footnotes} to {@see Footnotes_Public}.
*/ */
public function enqueue_styles() { public function enqueue_styles() {
if ( PRODUCTION_ENV ) { if ( PRODUCTION_ENV ) {
@ -211,18 +215,16 @@ class Footnotes_Public {
* @since 2.0.0 Add jQueryUI dependency. * @since 2.0.0 Add jQueryUI dependency.
* @since 2.1.2 Add jQuery Tools dependency. * @since 2.1.2 Add jQuery Tools dependency.
* @since 2.5.6 Add jQuery dependency. * @since 2.5.6 Add jQuery dependency.
* @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class. * @since 2.8.0 Moved from {@see Footnotes} to {@see Footnotes_Public}.
*/ */
public function enqueue_scripts() { public function enqueue_scripts() {
/** /*
* Enqueues the jQuery library registered by WordPress. * Enqueues the jQuery library registered by WordPress.
* *
* As jQuery is also used for animated scrolling, it was loaded by default. * As jQuery is also used for animated scrolling, it was loaded by default.
* The function `wp_enqueue_script()` avoids loading the same library multiple times. * The function `wp_enqueue_script()` avoids loading the same library multiple times.
* After adding the alternative reference container, jQuery has become optional, * After adding the alternative reference container, jQuery has become optional,
* but still enabled by default. * but still enabled by default.
*
* @since 2.5.6
*/ */
if ( ! self::$a_bool_amp_enabled ) { if ( ! self::$a_bool_amp_enabled ) {
@ -233,24 +235,20 @@ class Footnotes_Public {
} }
if ( self::$a_bool_tooltips_enabled && ! self::$a_bool_alternative_tooltips_enabled ) { if ( self::$a_bool_tooltips_enabled && ! self::$a_bool_alternative_tooltips_enabled ) {
/** /*
* Enqueues the jQuery Tools library shipped with the plugin. * Enqueues the jQuery Tools library shipped with the plugin.
* *
* Redacted jQuery.browser, completed minification; * Redacted `jQuery.browser`, completed minification;
* see full header in `public/js/jquery.tools.js`. * see full header in `public/js/jquery.tools.js`.
* No '-js' in the handle, is appended automatically. * No ‘-js’ in the handle, is appended automatically.
* Deferring to the footer breaks jQuery tooltip display. * Deferring to the footer breaks jQuery tooltip display.
*
* @since 2.1.2
*/ */
wp_enqueue_script( $this->plugin_name, plugin_dir_url( __FILE__ ) . 'js/jquery.tools' . ( ( PRODUCTION_ENV ) ? '.min' : '' ) . '.js', array(), '1.2.7.redacted.2', false ); wp_enqueue_script( $this->plugin_name, plugin_dir_url( __FILE__ ) . 'js/jquery.tools' . ( ( PRODUCTION_ENV ) ? '.min' : '' ) . '.js', array(), '1.2.7.redacted.2', false );
/** /*
* Enqueues some jQuery UI libraries registered by WordPress. * Enqueues some jQuery UI libraries registered by WordPress.
* *
* If alternative tooltips are enabled, these libraries are not needed. * If alternative tooltips are enabled, these libraries are not needed.
*
* @since 2.0.0
*/ */
wp_enqueue_script( 'jquery-ui-core' ); wp_enqueue_script( 'jquery-ui-core' );
wp_enqueue_script( 'jquery-ui-widget' ); wp_enqueue_script( 'jquery-ui-widget' );
@ -266,7 +264,7 @@ class Footnotes_Public {
* Register the widget(s) for the public-facing side of the site. * Register the widget(s) for the public-facing side of the site.
* *
* @since 1.5.0 * @since 1.5.0
* @since 2.8.0 Moved to `Footnotes_Public` class. * @since 2.8.0 Moved from {@see Footnotes} to {@see Footnotes_Public}.
*/ */
public function register_widgets() { public function register_widgets() {
register_widget( $this->reference_container_widget ); register_widget( $this->reference_container_widget );

44
src/public/widget/class-footnotes-widget-base.php
View file

@ -1,32 +1,35 @@
<?php <?php
/** /**
* Widget base. * Widgets: Footnotes_Widget_Base class
* *
* The Widget subpackage is composed of the {@see Footnotes_Widget_Base}
* abstract class, which is extended by the {@see Footnotes_Widget_Reference_Container}
* sub-class.
*
* @package footnotes\public\widget
* @since 1.5.0 * @since 1.5.0
* @since 1.6.4 Update: replace deprecated function WP_Widget() with recommended __construct(), thanks to @dartiss code contribution.
*
* @package footnotes
* @subpackage public_widget
*/ */
/** /**
* Base Class for all Plugin Widgets. Registers each Widget to WordPress. * Base class to be extended by all widget sub-classes.
* The following Methods MUST be overwritten in each sub class:
* **public function widget($args, $instance)** -> echo the Widget Content
* **public function form($instance)** -> echo the Settings of the Widget
* *
* @author Stefan Herndler * Any sub-class must override the appropriate method(s) provided by
* {@link https://developer.wordpress.org/reference/classes/wp_widget/#description `WP_Widget`}.
*
* @abstract
*
* @package footnotes\public\widget
* @since 1.5.0 * @since 1.5.0
* * @todo Review implemenation of Widgets API.
* @package footnotes
* @subpackage public_widget
*/ */
abstract class Footnotes_Widget_Base extends WP_Widget { abstract class Footnotes_Widget_Base extends WP_Widget {
/** /**
* Returns an unique ID as string used for the Widget Base ID. * Returns an unique ID as string used for the Widget Base ID.
* *
* @abstract
* @since 1.5.0 * @since 1.5.0
*
* @return string * @return string
*/ */
abstract protected function get_id(); abstract protected function get_id();
@ -34,7 +37,9 @@ abstract class Footnotes_Widget_Base extends WP_Widget {
/** /**
* Returns the Public name of child Widget to be displayed in the Configuration page. * Returns the Public name of child Widget to be displayed in the Configuration page.
* *
* @abstract
* @since 1.5.0 * @since 1.5.0
*
* @return string * @return string
*/ */
abstract protected function get_name(); abstract protected function get_name();
@ -42,7 +47,9 @@ abstract class Footnotes_Widget_Base extends WP_Widget {
/** /**
* Returns the Description of the child widget. * Returns the Description of the child widget.
* *
* @abstract
* @since 1.5.0 * @since 1.5.0
*
* @return string * @return string
*/ */
abstract protected function get_description(); abstract protected function get_description();
@ -51,6 +58,7 @@ abstract class Footnotes_Widget_Base extends WP_Widget {
* Returns the width of the Widget. Default width is 250 pixel. * Returns the width of the Widget. Default width is 250 pixel.
* *
* @since 1.5.0 * @since 1.5.0
*
* @return int * @return int
*/ */
protected function get_widget_width() { protected function get_widget_width() {
@ -58,16 +66,9 @@ abstract class Footnotes_Widget_Base extends WP_Widget {
} }
/** /**
* Class Constructor. Registers the child Widget to WordPress. * Registers the child Widget to WordPress.
* *
* @since 1.5.0 * @since 1.5.0
*
* - Update: replace deprecated function WP_Widget() with recommended __construct(), thanks to @dartiss code contribution.
*
* @since 1.6.4
* @contributor @dartiss
* @link https://plugins.trac.wordpress.org/browser/footnotes/trunk/class/widgets/base.php?rev=1445720
* “The called constructor method for WP_Widget in Footnotes_Widget_ReferenceContainer is deprecated since version 4.3.0! Use __construct() instead.”
*/ */
public function __construct() { public function __construct() {
$l_arr_widget_options = array( $l_arr_widget_options = array(
@ -86,4 +87,5 @@ abstract class Footnotes_Widget_Base extends WP_Widget {
$l_arr_control_options // Optional Widget Control Options. $l_arr_control_options // Optional Widget Control Options.
); );
} }
} }

39
src/public/widget/class-footnotes-widget-reference-container.php
View file

@ -1,11 +1,13 @@
<?php // phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped <?php // phpcs:disable WordPress.Security.EscapeOutput.OutputNotEscaped
/** /**
* Includes the Plugin Widget to put the Reference Container to the Widget area. * Widgets: Footnotes_Widget_Reference_Container class
* *
* The Widget subpackage is composed of the {@see Footnotes_Widget_Base}
* abstract class, which is extended by the {@see Footnotes_Widget_Reference_Container}
* sub-class.
*
* @package footnotes\public\widget
* @since 1.5.0 * @since 1.5.0
*
* @package footnotes
* @subpackage public_widget
*/ */
require_once plugin_dir_path( dirname( __FILE__ ) ) . 'widget/class-footnotes-widget-base.php'; require_once plugin_dir_path( dirname( __FILE__ ) ) . 'widget/class-footnotes-widget-base.php';
@ -13,18 +15,19 @@ require_once plugin_dir_path( dirname( __FILE__ ) ) . 'widget/class-footnotes-wi
/** /**
* Registers a Widget to put the Reference Container to the widget area. * Registers a Widget to put the Reference Container to the widget area.
* *
* @package footnotes\public\widget
* @since 1.5.0 * @since 1.5.0
* * @see Footnotes_Widget_Base
* @package footnotes * @todo Review implemenation of Widgets API.
* @subpackage public_widget
*/ */
class Footnotes_Widget_Reference_Container extends Footnotes_Widget_Base { class Footnotes_Widget_Reference_Container extends Footnotes_Widget_Base {
/** /**
* The ID of this plugin. * The ID of this plugin.
* *
* @since 2.8.0
* @access private * @access private
* @since 2.8.0
* @see Footnotes::$plugin_name
* @var string $plugin_name The ID of this plugin. * @var string $plugin_name The ID of this plugin.
*/ */
private $plugin_name; private $plugin_name;
@ -33,6 +36,7 @@ class Footnotes_Widget_Reference_Container extends Footnotes_Widget_Base {
* Initialize the class and set its properties. * Initialize the class and set its properties.
* *
* @since 2.8.0 * @since 2.8.0
*
* @param string $plugin_name The name of this plugin. * @param string $plugin_name The name of this plugin.
*/ */
public function __construct( $plugin_name ) { public function __construct( $plugin_name ) {
@ -43,7 +47,9 @@ class Footnotes_Widget_Reference_Container extends Footnotes_Widget_Base {
/** /**
* Returns an unique ID as string used for the Widget Base ID. * Returns an unique ID as string used for the Widget Base ID.
* *
* @see Footnotes_Widget_Base::get_id()
* @since 1.5.0 * @since 1.5.0
*
* @return string * @return string
*/ */
protected function get_id() { protected function get_id() {
@ -53,7 +59,9 @@ class Footnotes_Widget_Reference_Container extends Footnotes_Widget_Base {
/** /**
* Returns the Public name of the Widget to be displayed in the Configuration page. * Returns the Public name of the Widget to be displayed in the Configuration page.
* *
* @see Footnotes_Widget_Base::get_name()
* @since 1.5.0 * @since 1.5.0
*
* @return string * @return string
*/ */
protected function get_name() { protected function get_name() {
@ -63,32 +71,33 @@ class Footnotes_Widget_Reference_Container extends Footnotes_Widget_Base {
/** /**
* Returns the Description of the child widget. * Returns the Description of the child widget.
* *
* @see Footnotes_Widget_Base::get_description()
* @since 1.5.0 * @since 1.5.0
* @return string
* *
* Edit: curly quotes 2.2.0 * @return string
*/ */
protected function get_description() { protected function get_description() {
return __( 'The widget defines the position of the reference container if set to “widget area”.', 'footnotes' ); return __( 'The widget defines the position of the reference container if set to &ldquo;widget area&rdquo;.', 'footnotes' );
} }
/** /**
* Outputs the Settings of the Widget. * Outputs the Settings of the Widget.
* *
* @link https://developer.wordpress.org/reference/classes/wp_widget/form/ `WP_Widget::form()`
* @since 1.5.0 * @since 1.5.0
* @param mixed $instance The instance of the widget.
* @return void
* *
* Edit: curly quotes 2.2.0 * @param mixed $instance The instance of the widget.
*/ */
public function form( $instance ) { public function form( $instance ) {
echo __( 'The widget defines the position of the reference container if set to “widget area”.', 'footnotes' ); echo __( 'The widget defines the position of the reference container if set to &ldquo;widget area&rdquo;.', 'footnotes' );
} }
/** /**
* Outputs the Content of the Widget. * Outputs the Content of the Widget.
* *
* @link https://developer.wordpress.org/reference/classes/wp_widget/widget/ `WP_Widget::widget()`
* @since 1.5.0 * @since 1.5.0
*
* @param mixed $args The widget's arguments. * @param mixed $args The widget's arguments.
* @param mixed $instance The instance of the widget. * @param mixed $instance The instance of the widget.
*/ */