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
Download patch file Download diff file Expand all files Collapse all files

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

File diff suppressed because it is too large Load diff

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

@ -2,101 +2,106 @@
/**
* The public-facing functionality of the plugin.
*
* @since 2.8.0
*
* @package footnotes
* @subpackage public
* @package footnotes\public
* @since 2.8.0
*/
/**
* 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
* and JavaScript.
*
* @package footnotes
* @subpackage public
* @package footnotes\public
* @since 2.8.0
*/
class Footnotes_Public {
/**
* The ID of this plugin.
*
* @since 2.8.0
* @access private
* @var string $plugin_name The ID of this plugin.
* @since 2.8.0
* @access private
* @var string $plugin_name The ID of this plugin.
*/
private $plugin_name;
/**
* The version of this plugin.
*
* @since 2.8.0
* @access private
* @var string $version The current version of this plugin.
* @since 2.8.0
* @access private
* @var string $version The current version of this plugin.
*/
private $version;
/**
* The reference container widget.
*
* @since 2.8.0
* @var Footnotes_Widget_Reference_Container $reference_container_widget The reference container widget
* @since 2.8.0
*
* @var Footnotes_Widget_Reference_Container $reference_container_widget The reference container widget
*/
private $reference_container_widget;
/**
* The footnote parser.
*
* @since 1.5.0
* @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class.
* @var Footnote_Parser $task The Plugin task.
* @since 1.5.0
* @since 2.8.0 Moved from {@see Footnotes} to {@see Footnotes_Public}.
*
* @var Footnotes_Parser $task The Plugin task.
*/
public $a_obj_task = null;
/**
* Flag for using tooltips.
*
* @since 2.4.0
* @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class.
* @var bool $tooltips_enabled Whether tooltips are enabled or not.
* @since 2.4.0
* @since 2.8.0 Moved from {@see Footnotes} to {@see Footnotes_Public}.
*
* @var bool $tooltips_enabled Whether tooltips are enabled or not.
*/
public static $a_bool_tooltips_enabled = false;
/**
* Allows to determine whether alternative tooltips are enabled.
*
* @since 2.1.1
* @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class.
* @var bool
* @since 2.1.1
* @since 2.8.0 Moved from {@see Footnotes} to {@see Footnotes_Public}.
*
* @var bool
*/
public static $a_bool_alternative_tooltips_enabled = false;
/**
* Allows to determine whether AMP compatibility mode is enabled.
*
* @since 2.6.0 (release)
* @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class.
* @var bool
* @since 2.6.0
* @since 2.8.0 Moved from {@see Footnotes} to {@see Footnotes_Public}.
*
* @var bool
*/
public static $a_bool_amp_enabled = false;
/**
* Allows to determine the script mode among jQuery or plain JS.
*
* @since 2.5.6
* @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class.
* @var str 'js' Plain JavaScript.
* 'jquery' Use jQuery libraries.
* @since 2.5.6
* @since 2.8.0 Moved from {@see Footnotes} to {@see Footnotes_Public}.
*
* @var string ‘js’ to use plain JavaScript, ‘jquery’ to use jQuery.
*/
public static $a_str_script_mode = 'js';
/**
* Initialize the class and set its properties.
*
* @since 2.8.0
* @param string $plugin_name The name of this plugin.
* @param string $version The version of this plugin.
* @since 2.8.0
* @param string $plugin_name The name of this plugin.
* @param string $version The version of this plugin.
*/
public function __construct( $plugin_name, $version ) {
@ -118,11 +123,10 @@ class Footnotes_Public {
* Include the following files that provide the public-facing functionality
* of this plugin:
*
* - `Footnotes_Parser`. Parses Posts and Pages for footnote shortcodes.
* - `Footnotes_Widget_Reference_Container`. Defines the Reference Container widget.
* - {@see Footnotes_Parser}: parses Posts and Pages for footnote shortcodes; and
* - {@see Footnotes_Widget_Reference_Container}: defines the Reference Container widget.
*
* @since 2.8.0
* @access private
* @since 2.8.0
*/
private function load_dependencies() {
// 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.
*
* Enables enqueuing the formatted individual stylesheets if `PRODCUTION_ENV`
* is true (set in `footnotes.php`).
* Enables enqueuing the formatted individual stylesheets if {@see PRODUCTION_ENV}
* is `true`.
*
* @since 1.5.0
* @since 2.5.5 Change stylesheet scheme.
* @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class.
* @since 1.5.0
* @since 2.5.5 Change stylesheet schema.
* @since 2.8.0 Moved from {@see Footnotes} to {@see Footnotes_Public}.
*/
public function enqueue_styles() {
if ( PRODUCTION_ENV ) {
@ -207,22 +211,20 @@ class Footnotes_Public {
/**
* Register the JavaScript for the public-facing side of the site.
*
* @since 1.5.0
* @since 2.0.0 Add jQueryUI dependency.
* @since 2.1.2 Add jQuery Tools dependency.
* @since 2.5.6 Add jQuery dependency.
* @since 2.8.0 Moved from `Footnotes` to `Footnotes_Public` class.
* @since 1.5.0
* @since 2.0.0 Add jQueryUI dependency.
* @since 2.1.2 Add jQuery Tools dependency.
* @since 2.5.6 Add jQuery dependency.
* @since 2.8.0 Moved from {@see Footnotes} to {@see Footnotes_Public}.
*/
public function enqueue_scripts() {
/**
/*
* Enqueues the jQuery library registered by WordPress.
*
* 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.
* After adding the alternative reference container, jQuery has become optional,
* but still enabled by default.
*
* @since 2.5.6
*/
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 ) {
/**
/*
* 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`.
* No '-js' in the handle, is appended automatically.
* No ‘-js’ in the handle, is appended automatically.
* 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 );
/**
/*
* Enqueues some jQuery UI libraries registered by WordPress.
*
* 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-widget' );
@ -265,8 +263,8 @@ class Footnotes_Public {
/**
* Register the widget(s) for the public-facing side of the site.
*
* @since 1.5.0
* @since 2.8.0 Moved to `Footnotes_Public` class.
* @since 1.5.0
* @since 2.8.0 Moved from {@see Footnotes} to {@see Footnotes_Public}.
*/
public function register_widgets() {
register_widget( $this->reference_container_widget );

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

@ -1,73 +1,74 @@
<?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.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.
* 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
* Base class to be extended by all widget sub-classes.
*
* @author Stefan Herndler
* @since 1.5.0
* Any sub-class must override the appropriate method(s) provided by
* {@link https://developer.wordpress.org/reference/classes/wp_widget/#description `WP_Widget`}.
*
* @package footnotes
* @subpackage public_widget
* @abstract
*
* @package footnotes\public\widget
* @since 1.5.0
* @todo Review implemenation of Widgets API.
*/
abstract class Footnotes_Widget_Base extends WP_Widget {
/**
* Returns an unique ID as string used for the Widget Base ID.
*
* @since 1.5.0
* @return string
* @abstract
* @since 1.5.0
*
* @return string
*/
abstract protected function get_id();
/**
* Returns the Public name of child Widget to be displayed in the Configuration page.
*
* @since 1.5.0
* @return string
* @abstract
* @since 1.5.0
*
* @return string
*/
abstract protected function get_name();
/**
* Returns the Description of the child widget.
*
* @since 1.5.0
* @return string
* @abstract
* @since 1.5.0
*
* @return string
*/
abstract protected function get_description();
/**
* Returns the width of the Widget. Default width is 250 pixel.
*
* @since 1.5.0
* @return int
* @since 1.5.0
*
* @return int
*/
protected function get_widget_width() {
return 250;
}
/**
* Class Constructor. Registers the child Widget to WordPress.
* Registers the child Widget to WordPress.
*
* @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.”
* @since 1.5.0
*/
public function __construct() {
$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.
);
}
}

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

@ -1,11 +1,13 @@
<?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
*
* @since 1.5.0
* 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
* @subpackage public_widget
* @package footnotes\public\widget
* @since 1.5.0
*/
require_once plugin_dir_path( dirname( __FILE__ ) ) . 'widget/class-footnotes-widget-base.php';
@ -13,27 +15,29 @@ require_once plugin_dir_path( dirname( __FILE__ ) ) . 'widget/class-footnotes-wi
/**
* Registers a Widget to put the Reference Container to the widget area.
*
* @since 1.5.0
*
* @package footnotes
* @subpackage public_widget
* @package footnotes\public\widget
* @since 1.5.0
* @see Footnotes_Widget_Base
* @todo Review implemenation of Widgets API.
*/
class Footnotes_Widget_Reference_Container extends Footnotes_Widget_Base {
/**
* The ID of this plugin.
*
* @since 2.8.0
* @access private
* @var string $plugin_name The ID of this plugin.
* @access private
* @since 2.8.0
* @see Footnotes::$plugin_name
* @var string $plugin_name The ID of this plugin.
*/
private $plugin_name;
/**
* Initialize the class and set its properties.
*
* @since 2.8.0
* @param string $plugin_name The name of this plugin.
* @since 2.8.0
*
* @param string $plugin_name The name of this plugin.
*/
public function __construct( $plugin_name ) {
parent::__construct();
@ -43,8 +47,10 @@ class Footnotes_Widget_Reference_Container extends Footnotes_Widget_Base {
/**
* Returns an unique ID as string used for the Widget Base ID.
*
* @since 1.5.0
* @return string
* @see Footnotes_Widget_Base::get_id()
* @since 1.5.0
*
* @return string
*/
protected function get_id() {
return 'footnotes_widget';
@ -53,8 +59,10 @@ class Footnotes_Widget_Reference_Container extends Footnotes_Widget_Base {
/**
* Returns the Public name of the Widget to be displayed in the Configuration page.
*
* @since 1.5.0
* @return string
* @see Footnotes_Widget_Base::get_name()
* @since 1.5.0
*
* @return string
*/
protected function get_name() {
return $this->plugin_name;
@ -63,34 +71,35 @@ class Footnotes_Widget_Reference_Container extends Footnotes_Widget_Base {
/**
* Returns the Description of the child widget.
*
* @since 1.5.0
* @return string
* @see Footnotes_Widget_Base::get_description()
* @since 1.5.0
*
* Edit: curly quotes 2.2.0
* @return string
*/
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.
*
* @since 1.5.0
* @param mixed $instance The instance of the widget.
* @return void
* @link https://developer.wordpress.org/reference/classes/wp_widget/form/ `WP_Widget::form()`
* @since 1.5.0
*
* Edit: curly quotes 2.2.0
* @param mixed $instance The instance of the widget.
*/
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.
*
* @since 1.5.0
* @param mixed $args The widget's arguments.
* @param mixed $instance The instance of the widget.
* @link https://developer.wordpress.org/reference/classes/wp_widget/widget/ `WP_Widget::widget()`
* @since 1.5.0
*
* @param mixed $args The widget's arguments.
* @param mixed $instance The instance of the widget.
*/
public function widget( $args, $instance ) {
global $footnotes;