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-29 20:57:30 +01:00
parent 418abc253b
commit bfeb11d5ad
11 changed files with 363 additions and 306 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -1152,7 +1152,7 @@ class Footnotes_Layout_Settings extends Footnotes_Layout_Engine {
* 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
* @see admin/partials/customize-css.html
* @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

39
src/footnotes.php
View file

@ -7,11 +7,11 @@
* registers the activation and deactivation functions, and defines a function
* that starts the plugin.
*
* @author Mark Cheret
* @since 1.0.0
* @package footnotes
* @copyright 2021 Mark Cheret (email: mark@cheret.de)
* @license GPL-3.0-only
* @package footnotes
* @license GPL-3.0-only
* @copyright 2021 Mark Cheret (email: mark@cheret.de)
*
* @since 1.0.0
*
* @wordpress-plugin
* Plugin Name: footnotes
@ -34,24 +34,33 @@ if ( ! defined( 'WPINC' ) ) {
}
/**
* Current plugin version.
* The current plugin version.
*
* @link https://github.com/markcheret/footnotes/wiki/Versioning Versioning Guide
*
* @global string PLUGIN_VERSION
*
* @since 2.1.4
*/
define( 'PLUGIN_VERSION', '2.8.0d' );
/**
* Defines the current environment ('development' or 'production').
* The current environment ('development' or 'production').
*
* This primarily affects whether minified or unminified files are requested.
*
* @global bool PRODUCTION_ENV
*
* @since 2.5.5
*/
define( 'PRODUCTION_ENV', false );
/**
* The code that runs during plugin activation.
* This action is documented in includes/class-plugin-name-activator.php
* Triggers during plugin activation.
*
* @uses Footnotes_Activator::activate() Method called on plugin activation.
*
* @since 2.8.0
*/
function activate_footnotes() {
require_once plugin_dir_path( __FILE__ ) . 'includes/class-footnotes-activator.php';
@ -59,8 +68,11 @@ function activate_footnotes() {
}
/**
* The code that runs during plugin deactivation.
* This action is documented in includes/class-plugin-name-deactivator.php
* Triggers during plugin deactivation.
*
* @uses Footnotes_Deactivator::deactivate() Method called on plugin deactivation.
*
* @since 2.8.0
*/
function deactivate_plugin_name() {
require_once plugin_dir_path( __FILE__ ) . 'includes/class-footnotes-deactivator.php';
@ -79,9 +91,8 @@ require plugin_dir_path( __FILE__ ) . 'includes/class-footnotes.php';
/**
* Begins execution of the plugin.
*
* Since everything within the plugin is registered via hooks,
* then kicking off the plugin from this point in the file does
* not affect the page life cycle.
* Since everything within the plugin is registered via hooks, then kicking off
* the plugin from this point in the file does not affect the page life cycle.
*
* @since 2.8.0
*/

21
src/includes/class-footnotes-activator.php
View file

@ -1,30 +1,31 @@
<?php
/**
* Fired during plugin activation
* File providing `Footnotes_Activator` class.
*
* @since 2.8.0
* @package footnotes
* @subpackage includes
*
* @package footnotes
* @subpackage includes
* @since 2.8.0
*/
/**
* Fired during plugin activation.
* Class providing action(s) on plugin activation.
*
* This class defines all code necessary to run during the plugin's activation.
*
* @since 2.8.0
* @package footnotes
* @subpackage includes
* @package footnotes
* @subpackage includes
*
* @since 2.8.0
*/
class Footnotes_Activator {
/**
* Runs when the Plugin is deactivated.
* Runs when the plugin is deactivated.
*
* Currently NOP.
*
* @since 2.8.0
* @since 2.8.0
*/
public static function activate() {
// Nothing yet.

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

@ -1,65 +1,84 @@
<?php
/**
* Includes the Plugin Constants class to load all Plugin constant vars like Plugin name, etc.
* File providing the `Footnotes_Config` class.
*
* @since 1.5.0
* @since 2.0.4 add Public Plugin name for dashboard heading
* @package footnotes
* @subpackage includes
*
* @package footnotes
* @subpackage includes
* @since 1.5.0
* @since 2.8.0 Rename file from `config.php` to `class-footnotes-config.php`.
* @todo Remove.
* @deprecated
*/
/**
* Contains all Plugin Constants. Contains no Method or Property.
* Class defining plugin constants.
*
* @since 1.5.0
* This class contains no methods of properties.
*
* @since 1.5.0
* @todo Remove.
* @deprecated
*/
class Footnotes_Config {
/**
* Public Plugin name.
* Public plugin name.
*
* @since 1.5.0
* @var string
*
* edited classes for v2.0.4
* @since 1.5.0
* @todo Remove.
* @deprecated
*/
const C_STR_PLUGIN_PUBLIC_NAME = '<span class="footnotes_logo footnotes_logo_part1">foot</span><span class="footnotes_logo footnotes_logo_part2">notes</span>';
/**
* Public Plugin name for dashboard heading
* Public plugin name for use as a dashboard heading.
*
* After properly displaying in dashboard headings until WPv5.4, the above started
* in WPv5.5 being torn apart as if the headline was text-align:justify and not
* the last line. That ugly display bug badly affected the plugin’s communication.
* The only working solution found so far is using position:fixed in one heading
* that isn’t translated, and dropping the logo in another, translatable heading.
* in WP 5.5 being torn apart as if the headline was `text-align:justify` and not
* the last line. That ugly display bug badly affected the plugin's communication.
* The only working solution found so far is using `position:fixed` in one heading
* that isn't translated, and dropping the logo in another, translatable heading.
*
* @since 2.0.4
* @var string
* @var string
*
* @since 2.0.4
* @todo Remove.
* @deprecated
*/
const C_STR_PLUGIN_HEADING_NAME = '<span class="footnotes_logo_heading footnotes_logo_part1_heading">foot</span><span class="footnotes_logo_heading footnotes_logo_part2_heading">notes</span>';
/**
* Html tag for the LOVE symbol.
* HTML element for the ‘love’ symbol.
*
* @since 1.5.0
* @var string
* @var string
*
* @since 1.5.0
* @todo Remove.
* @deprecated
*/
const C_STR_LOVE_SYMBOL = '<span style="color:#ff6d3b; font-weight:bold;">&hearts;</span>';
/**
* HTML code for the 'love' symbol used in dashboard heading
* HTML element for the ‘love’ symbol used in dashboard heading
*
* @since 2.0.4
* @var string
* @var string
*
* @since 2.0.4
* @todo Remove.
* @deprecated
*/
const C_STR_LOVE_SYMBOL_HEADING = '<span class="footnotes_heart_heading">&hearts;</span>';
/**
* Short code to DON'T display the 'LOVE ME' slug on certain pages.
* Shortcode to NOT display the ‘LOVE ME’ slug on certain pages.
*
* @since 1.5.0
* @var string
* @var string
*
* @since 1.5.0
* @todo Remove.
* @deprecated
*/
const C_STR_NO_LOVE_SLUG = '[[no footnotes: love]]';
}

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

@ -1,31 +1,29 @@
<?php
/**
* Includes the Convert Class.
* File providing core `Footnotes_Convert` class.
*
* @since 1.5.0
* @since 2.2.0 add lowercase Roman
* @package footnotes
* @subpackage includes
*
* @package footnotes
* @subpackage includes
* @since 1.5.0
* @since 2.8.0 Rename file from `convert.php` to `class-footnotes-convert.php`.
*/
/**
* Converts data types and Footnotes specific values.
* Class providing variable type and value conversion functions.
*
* @since 1.5.0
*/
class Footnotes_Convert {
/**
* Converts a integer into the user-defined counter style for the footnotes.
* Converts an integer into the user-defined counter style for the footnotes.
*
* @since 1.5.0
* @param int $p_int_index Index to be converted.
* @param string $p_str_convert_style Style of the new/converted Index.
* @return string Converted Index as string in the defined counter style.
* @param int $p_int_index Index to be converted.
* @param string $p_str_convert_style Counter style to use.
* @return string Converted Index converted to the defined counter style.
*
* Edited:
* @since 2.2.0 lowercase Roman numerals supported
* @since 1.5.0
*/
public static function index( $p_int_index, $p_str_convert_style = 'arabic_plain' ) {
switch ( $p_str_convert_style ) {
@ -46,13 +44,17 @@ class Footnotes_Convert {
}
/**
* Converts an integer into latin ascii characters, either lower or upper-case.
* Function available from A to ZZ ( means 676 footnotes at 1 page possible).
* Converts an integer into Latin ASCII characters, either lower or upper-case.
*
* @since 1.0-gamma
* @param int $p_int_value Value/Index to be converted.
* @param bool $p_bool_upper_case True to convert the value to upper case letter, otherwise to lower case.
* @return string
* This function works from values A–ZZ (meaning there is a limit of 676
* gootnotes per Page).
*
* @param int $p_int_value Value to be converted.
* @param bool $p_bool_upper_case Whether to convert the value to upper-case.
* @return string
*
* @since 1.0-gamma
* @todo Replace with built-in char casting.
*/
private static function to_latin( $p_int_value, $p_bool_upper_case ) {
// Output string.
@ -80,9 +82,11 @@ class Footnotes_Convert {
/**
* Converts an integer to a leading-0 integer.
*
* @since 1.0-gamma
* @param int $p_int_value Value/Index to be converted.
* @return string Value with a leading zero.
* @param int $p_int_value Value to be converted.
* @return string Value with a leading zero.
*
* @since 1.0-gamma
* @todo Replace with built-in string formatting.
*/
private static function to_arabic_leading( $p_int_value ) {
// Add a leading 0 if number lower then 10.
@ -93,15 +97,13 @@ class Footnotes_Convert {
}
/**
* Converts an integer to a romanic letter.
* Converts an integer to a Roman numeral.
*
* @since 1.0-gamma
* @param int $p_int_value Value/Index to be converted.
* @param bool $p_bool_upper_case Whether to uppercase.
* @return string
* @param int $p_int_value Value to be converted.
* @param bool $p_bool_upper_case Whether to convert the value to upper-case.
* @return string
*
* Edited:
* @since 2.2.0 optionally lowercase (code from Latin)
* @since 1.0-gamma
*/
private static function to_romanic( $p_int_value, $p_bool_upper_case ) {
// Table containing all necessary romanic letters.
@ -142,9 +144,11 @@ class Footnotes_Convert {
/**
* Converts a string depending on its value to a boolean.
*
* @since 1.0-beta
* @param string $p_str_value String to be converted to boolean.
* @return bool Boolean representing the string.
* @param string $p_str_value String to be converted to boolean.
* @return bool Boolean value represented by the string.
*
* @since 1.0-beta
* @todo Replace with built-in type casting.
*/
public static function to_bool( $p_str_value ) {
// Convert string to lower-case to make it easier.
@ -163,11 +167,13 @@ class Footnotes_Convert {
}
/**
* Get a html Array short code depending on Arrow-Array key index.
* Get an HTML array short code depending on Arrow-Array key index.
*
* @since 1.3.2
* @param int $p_int_index Index representing the Arrow. If empty all Arrows are specified.
* @return array|string Array of all Arrows if Index is empty otherwise html tag of a specific arrow.
* @param int $p_int_index Index representing the arrow. If empty, all arrows are specified.
* @return array|string Array of all arrows if index is empty, otherwise HTML tag of a specific arrow.
*
* @since 1.3.2
* @todo Review.
*/
public static function get_arrow( $p_int_index = -1 ) {
// Define all possible arrows.
@ -184,14 +190,14 @@ class Footnotes_Convert {
return $l_arr_arrows[ $p_int_index ];
}
// phpcs:disable WordPress.PHP.DevelopmentFunctions.error_log_var_dump
// phpcs:disable WordPress.PHP.DevelopmentFunctions.error_log_print_r
// phpcs:disable WordPress.PHP.DevelopmentFunctions.error_log_var_dump, WordPress.PHP.DevelopmentFunctions.error_log_print_r
/**
* Displays a Variable.
* Displays a variable.
*
* @since 1.5.0
* @param mixed $p_mixed_value The variable to display.
* @return void
* @param mixed $p_mixed_value The variable to display.
*
* @since 1.5.0
* @todo Replace with proper logging/debug functions.
*/
public static function debug( $p_mixed_value ) {
if ( empty( $p_mixed_value ) ) {
@ -218,5 +224,5 @@ class Footnotes_Convert {
}
echo '<br/>';
}
// phpcs:disable
// phpcs:enable WordPress.PHP.DevelopmentFunctions.error_log_var_dump, WordPress.PHP.DevelopmentFunctions.error_log_print_r
}

21
src/includes/class-footnotes-deactivator.php
View file

@ -1,30 +1,31 @@
<?php
/**
* Fired during plugin deactivation.
* File providing `Footnotes_Deactivator` class.
*
* @since 2.8.0
*
* @package footnotes
* @package footnotes
* @subpackage includes
*
* @since 2.8.0
*/
/**
* Fired during plugin deactivation.
* Class providing action(s) on plugin deactivation.
*
* This class defines all code necessary to run during the plugin's deactivation.
*
* @since 2.8.0
* @package footnotes
* @subpackage includes
* @package footnotes
* @subpackage includes
*
* @since 2.8.0
*/
class Footnotes_Deactivator {
/**
* Runs when the Plugin is deactivated.
* Runs when the plugin is deactivated.
*
* Currently NOP.
*
* @since 2.8.0
* @since 2.8.0
*/
public static function deactivate() {
// Nothing yet.

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

@ -1,37 +1,37 @@
<?php // phpcs:disable PEAR.NamingConventions.ValidClassName.Invalid
/**
* Define the internationalization functionality
* File providing core `Footnotes_i18n` class.
*
* Loads and defines the internationalization files for this plugin
* so that it is ready for translation.
* @package footnotes
* @subpackage includes
*
* @since 1.5.0
* @since 2.8.0 Renamed class to `Footnotes_i18n`.
*
* @package footnotes
* @subpackage includes
* @since 1.5.0
* @since 2.8.0 Rename file from `language.php` to `class-footnotes-i18n.php`.
*/
require_once plugin_dir_path( dirname( __FILE__ ) ) . 'includes/class-footnotes-config.php';
/**
* Define the internationalization functionality.
* Class providing internationalization functionality.
*
* Loads and defines the internationalization files for this plugin
* so that it is ready for translation.
* Loads and defines the internationalization files for this plugin so that it
* is ready for translation.
*
* @since 1.5.0
* @since 2.8.0 Renamed class to `Footnotes_i18n`.
* @package footnotes
* @subpackage includes
* @link https://translate.wordpress.org/projects/wp-plugins/footnotes/ GlotPress listing
*
* @package footnotes
* @subpackage includes
*
* @since 1.5.0
* @since 2.8.0 Rename class from `Footnotes_Language` to `Footnotes_i18n`.
*/
class Footnotes_i18n {
/**
* Load the plugin text domain for translation.
*
* @since 1.5.1
* @since 2.8.0 Rename from `load()` to `load_plugin_textdomain()`. Remove unused `$p_str_language_code` parameter.
* @since 1.5.1
* @since 2.8.0 Rename from `load()` to `load_plugin_textdomain()`. Remove unused `$p_str_language_code` parameter.
*/
public function load_plugin_textdomain() {
load_plugin_textdomain(

87
src/includes/class-footnotes-loader.php
View file

@ -1,46 +1,50 @@
<?php
/**
* Register all actions and filters for the plugin.
* File providing the `Footnotes_Loader` class.
*
* @since 2.8.0
* @package footnotes
* @subpackage includes
*
* @package footnotes
* @subpackage includes
* @since 2.8.0
*/
/**
* Register all actions and filters for the plugin.
* Class defining action/filter registration for the plugin.
*
* Maintain a list of all hooks that are registered throughout
* the plugin, and register them with the WordPress API. Call the
* run function to execute the list of actions and filters.
* Maintain a list of all hooks that are registered throughout the plugin, and
* register them with the WordPress API. Call the run function to execute the
* list of actions and filters.
*
* @package footnotes
* @subpackage includes
* @package footnotes
* @subpackage includes
*
* @since 2.8.0
*/
class Footnotes_Loader {
/**
* The array of actions registered with WordPress.
*
* @since 2.8.0
* @access protected
* @var array $actions The actions registered with WordPress to fire when the plugin loads.
* @access protected
* @var array $actions The actions registered with WordPress to fire when the plugin loads.
*
* @since 2.8.0
*/
protected $actions;
/**
* The array of filters registered with WordPress.
*
* @since 2.8.0
* @access protected
* @var array $filters The filters registered with WordPress to fire when the plugin loads.
* @access protected
* @var array $filters The filters registered with WordPress to fire when the plugin loads.
*
* @since 2.8.0
*/
protected $filters;
/**
* Initialize the collections used to maintain the actions and filters.
*
* @since 2.8.0
* @since 2.8.0
*/
public function __construct() {
@ -52,12 +56,13 @@ class Footnotes_Loader {
/**
* Add a new action to the collection to be registered with WordPress.
*
* @since 2.8.0
* @param string $hook The name of the WordPress action that is being registered.
* @param object $component A reference to the instance of the object on which the action is defined.
* @param string $callback The name of the function definition on the $component.
* @param int $priority Optional. The priority at which the function should be fired. Default is 10.
* @param int $accepted_args Optional. The number of arguments that should be passed to the $callback. Default is 1.
* @param string $hook The name of the WordPress action that is being registered.
* @param object $component A reference to the instance of the object on which the action is defined.
* @param string $callback The name of the function definition on the `$component`.
* @param int $priority (optional) The priority at which the function should be fired. Default is 10.
* @param int $accepted_args (optional) The number of arguments that should be passed to the $callback. Default is 1.
*
* @since 2.8.0
*/
public function add_action( $hook, $component, $callback, $priority = 10, $accepted_args = 1 ) {
$this->actions = $this->add( $this->actions, $hook, $component, $callback, $priority, $accepted_args );
@ -66,12 +71,13 @@ class Footnotes_Loader {
/**
* Add a new filter to the collection to be registered with WordPress.
*
* @since 2.8.0
* @param string $hook The name of the WordPress filter that is being registered.
* @param object $component A reference to the instance of the object on which the filter is defined.
* @param string $callback The name of the function definition on the $component.
* @param int $priority Optional. The priority at which the function should be fired. Default is 10.
* @param int $accepted_args Optional. The number of arguments that should be passed to the $callback. Default is 1.
* @param string $hook The name of the WordPress filter that is being registered.
* @param object $component A reference to the instance of the object on which the filter is defined.
* @param string $callback The name of the function definition on the `$component`.
* @param int $priority (optional) The priority at which the function should be fired. Default is 10.
* @param int $accepted_args (optional) The number of arguments that should be passed to the $callback. Default is 1.
*
* @since 2.8.0
*/
public function add_filter( $hook, $component, $callback, $priority = 10, $accepted_args = 1 ) {
$this->filters = $this->add( $this->filters, $hook, $component, $callback, $priority, $accepted_args );
@ -81,15 +87,16 @@ class Footnotes_Loader {
* A utility function that is used to register the actions and hooks into a single
* collection.
*
* @since 2.8.0
* @access private
* @param array $hooks The collection of hooks that is being registered (that is, actions or filters).
* @param string $hook The name of the WordPress filter that is being registered.
* @param object $component A reference to the instance of the object on which the filter is defined.
* @param string $callback The name of the function definition on the $component.
* @param int $priority The priority at which the function should be fired.
* @param int $accepted_args The number of arguments that should be passed to the $callback.
* @return array The collection of actions and filters registered with WordPress.
* @access private
* @param array $hooks The collection of hooks that is being registered (that is, actions or filters).
* @param string $hook The name of the WordPress filter that is being registered.
* @param object $component A reference to the instance of the object on which the filter is defined.
* @param string $callback The name of the function definition on the `$component`.
* @param int $priority The priority at which the function should be fired.
* @param int $accepted_args The number of arguments that should be passed to the `$callback`.
* @return array The collection of actions and filters registered with WordPress.
*
* @since 2.8.0
*/
private function add( $hooks, $hook, $component, $callback, $priority, $accepted_args ) {
@ -106,9 +113,9 @@ class Footnotes_Loader {
}
/**
* Register the filters and actions with WordPress.
* Registers the filters and actions with WordPress.
*
* @since 2.8.0
* @since 2.8.0
*/
public function run() {

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

@ -4,96 +4,103 @@
*
* The constants are ordered by ascending version so their docblocks can replace most of this list.
*
* @since 1.5.0
* @since 2.0.0 Update: **symbol for backlinks** removed; hyperlink moved to the reference number.
* @since 2.0.4 Update: Restore arrow settings to customize or disable the now prepended arrow symbol, thanks to @mmallett issue report.
* @since 2.0.7 BUGFIX: Hooks: Default-disable 'the_post', thanks to @spaceling @markcheret @nyamachi @whichgodsaves @spiralofhope2 @mmallett @andreasra @widecast @ymorin007 @tashi1es bug reports.
* @since 2.1.3 Bugfix: Hooks: disable the_excerpt hook by default to fix issues, thanks to @nikelaos bug report.
* @package footnotes
* @subpackage includes
*
* @package footnotes
* @subpackage includes
* @since 1.5.0
* @since 2.8.0 Rename file from `settings.php` to `class-footnotes-settings.php`.
*/
require_once plugin_dir_path( dirname( __FILE__ ) ) . 'includes/class-footnotes-convert.php';
/**
* Loads the settings values, sets to default values if undefined.
* Class defining configurable plugin settings.
*
* @since 1.5.0
* @since 1.5.0
*/
class Footnotes_Settings {
/**
* Settings container key for the label of the reference container.
*
* @since 1.5.0
* @var str
* @var str
*
* @since 1.5.0
*/
const C_STR_REFERENCE_CONTAINER_NAME = 'footnote_inputfield_references_label';
/**
* Settings container key to collapse the reference container by default.
*
* @since 1.5.0
* @var str
* The string is converted to Boolean false if 'no', true if 'yes'.
* @see Footnotes_Convert::to_bool()
*
* @var str
*
* @since 1.5.0
* @todo Refactor to use sane typing.
*/
const C_STR_REFERENCE_CONTAINER_COLLAPSE = 'footnote_inputfield_collapse_references';
/**
* Settings container key for the position of the reference container.
*
* @since 1.5.0
* @var str
* @var str
*
* @since 1.5.0
*/
const C_STR_REFERENCE_CONTAINER_POSITION = 'footnote_inputfield_reference_container_place';
/**
* Settings container key for combining identical footnotes.
*
* @since 1.5.0
* @var str
* @var str
*
* @since 1.5.0
*/
const C_STR_COMBINE_IDENTICAL_FOOTNOTES = 'footnote_inputfield_combine_identical';
/**
* Settings container key for the short code of the footnote’s start.
* Settings container key for the short code of the footnote's start.
*
* @since 1.5.0
* @var str
* @var str
*
* @since 1.5.0
*/
const C_STR_FOOTNOTES_SHORT_CODE_START = 'footnote_inputfield_placeholder_start';
/**
* Settings container key for the short code of the footnote’s end.
* Settings container key for the short code of the footnote's end.
*
* @since 1.5.0
* @var str
* @var str
*
* @since 1.5.0
*/
const C_STR_FOOTNOTES_SHORT_CODE_END = 'footnote_inputfield_placeholder_end';
/**
* Settings container key for the user-defined short code of the footnotes start.
*
* @since 1.5.0
* @var str
* @var str
*
* @since 1.5.0
*/
const C_STR_FOOTNOTES_SHORT_CODE_START_USER_DEFINED = 'footnote_inputfield_placeholder_start_user_defined';
/**
* Settings container key for the user-defined short code of the footnotes end.
*
* @since 1.5.0
* @var str
* @var str
*
* @since 1.5.0
*/
const C_STR_FOOTNOTES_SHORT_CODE_END_USER_DEFINED = 'footnote_inputfield_placeholder_end_user_defined';
/**
* Settings container key for the counter style of the footnotes.
*
* @since 1.5.0
* @var str
* @var str
*
* @since 1.5.0
*/
const C_STR_FOOTNOTES_COUNTER_STYLE = 'footnote_inputfield_counter_style';

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

@ -1,78 +1,84 @@
<?php
/**
* Includes the Template Engine to load and handle all Template files of the Plugin.
* File providing the `Footnotes_Template` class.
*
* @since 1.5.0
* @since 2.2.6 Adding: Templates: support for custom templates in sibling folder, thanks to @misfist issue report.
* @since 2.5.0 Adding: Templates: Enable template location stack, thanks to @misfist issue report and code contribution.
*
* @package footnotes
* @subpackage includes
* @package footnotes
* @subpackage includes
*
* @since 1.5.0
* @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`.
*/
/**
* Handles each Template file for the Plugin Frontend (e.g. Settings Dashboard, Public pages, ...).
* Loads a template file, replaces all Placeholders and returns the replaced file content.
* Class defining template rendering.
*
* @since 1.5.0
* Loads a template file, replaces all Placeholders and returns the replaced
* file content.
* @package footnotes
* @subpackage includes
*
* @since 1.5.0
* @todo Refactor templating.
*/
class Footnotes_Template {
/**
* Directory name for dashboard partials.
*
* @since 1.5.0
* @var string
*
* @since 1.5.0
*/
const C_STR_DASHBOARD = 'admin/partials';
/**
* Directory name for public partials.
*
* @since 1.5.0
* @var string
*
* @since 1.5.0
*/
const C_STR_PUBLIC = 'public/partials';
/**
* Contains the content of the template after initialize.
*
* @since 1.5.0
* @var string
*
* @since 1.5.0
*/
private $a_str_original_content = '';
/**
* Contains the content of the template after initialize with replaced place holders.
*
* @since 1.5.0
* @var string
*
* @since 1.5.0
*/
private $a_str_replaced_content = '';
/**
* Plugin Directory
*
* @since 2.4.0d3
* @var string
*
* @var string
* @since 2.4.0d3
*/
public $plugin_directory;
/**
* Class Constructor. Reads and loads the template file without replace any placeholder.
*
* @since 1.5.0
* @param string $p_str_file_type Template file type (take a look on the Class constants).
* @param string $p_str_file_name Template file name inside the Template directory without the file extension.
* @param string $p_str_extension Optional Template file extension (default: html).
* @param string $p_str_file_type Template file type.
* @param string $p_str_file_name Template file name inside the `partials/` directory, without the file extension.
* @param string $p_str_extension (optional) Template file extension (default: 'html').
*
* - Adding: Templates: support for custom templates in sibling folder, thanks to @misfist issue report.
*
* @since 2.2.6
*
* @reporter @misfist
* @link https://wordpress.org/support/topic/template-override-filter/
* @since 1.5.0
* @todo Refactor templating.
*/
public function __construct( $p_str_file_type, $p_str_file_name, $p_str_extension = 'html' ) {
// No template file type and/or file name set.
@ -80,18 +86,8 @@ class Footnotes_Template {
return;
}
/**
* Define plugin root path.
*
* @since 2.4.0d3
*/
$this->plugin_directory = plugin_dir_path( dirname( __FILE__ ) );
/**
* Modularize functions.
*
* @since 2.4.0d3
*/
$template = $this->get_template( $p_str_file_type, $p_str_file_name, $p_str_extension );
if ( $template ) {
$this->process_template( $template );
@ -104,9 +100,11 @@ class Footnotes_Template {
/**
* Replace all placeholders specified in array.
*
* @param array $p_arr_placeholders Placeholders (key = placeholder, value = value).
* @return bool `true` on Success, `false` if placeholders invalid.
*
* @since 1.5.0
* @param array $p_arr_placeholders Placeholders (key = placeholder, value = value).
* @return bool True on Success, False if Placeholders invalid.
* @todo Refactor templating.
*/
public function replace( $p_arr_placeholders ) {
// No placeholders set.
@ -129,6 +127,7 @@ class Footnotes_Template {
* Reloads the original content of the template file.
*
* @since 1.5.0
* @todo Refactor templating.
*/
public function reload() {
$this->a_str_replaced_content = $this->a_str_original_content;
@ -137,8 +136,10 @@ class Footnotes_Template {
/**
* Returns the content of the template file with replaced placeholders.
*
* @return string Template content with replaced placeholders.
*
* @since 1.5.0
* @return string Template content with replaced placeholders.
* @todo Refactor templating.
*/
public function get_content() {
return $this->a_str_replaced_content;
@ -147,16 +148,11 @@ class Footnotes_Template {
/**
* Process template file.
*
* @since 2.4.0d3
* @param string $template The template to be processed.
* @return void
*
* @param string $template The template to be processed.
* @return void
*
* @since 2.0.3 Replace tab with a space.
* @since 2.0.3 Replace 2 spaces with 1.
* @since 2.0.4 Collapse multiple spaces.
* @since 2.2.6 Delete a space before a closing pointy bracket.
* @since 2.5.4 Collapse HTML comments and PHP/JS docblocks (only).
* @since 2.4.0d3
* @todo Refactor templating.
*/
public function process_template( $template ) {
// phpcs:disable WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents
@ -174,18 +170,13 @@ class Footnotes_Template {
/**
* Get the template.
*
* - Adding: Templates: Enable template location stack, thanks to @misfist issue report and code contribution.
* @param string $p_str_file_type The file type of the template.
* @param string $p_str_file_name The file name of the template.
* @param string $p_str_extension The file extension of the template.
* @return mixed `false` or the template path
*
* @since 2.4.0d3 Contribution.
* @since 2.5.0 Release.
*
* @contributor @misfist
* @link https://wordpress.org/support/topic/template-override-filter/#post-13864301
*
* @param string $p_str_file_type The file type of the template.
* @param string $p_str_file_name The file name of the template.
* @param string $p_str_extension The file extension of the template.
* @return mixed false | template path
* @since 2.5.0
* @todo Refactor templating.
*/
public function get_template( $p_str_file_type, $p_str_file_name, $p_str_extension = 'html' ) {
$located = false;
@ -197,6 +188,8 @@ class Footnotes_Template {
* add_filter( 'footnotes_template_directory', function( $directory ) {
* return 'template_parts/footnotes/';
* } );
*
* @todo Review.
*/
$template_directory = apply_filters( '', 'footnotes/' );
$custom_directory = apply_filters( 'footnotes_custom_template_directory', 'footnotes-custom/' );

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

@ -1,66 +1,69 @@
<?php // phpcs:disable PEAR.Commenting.FileComment.Missing
/**
* The file that defines the core plugin class
* File providing core `Footnotes` class.
*
* A class definition that includes attributes and functions used across both the
* public-facing side of the site and the admin area.
*
* @since 1.5.0
*
* @package footnotes
* @package footnotes
* @subpackage includes
*
* @since 1.5.0
* @since 2.8.0 Rename file from `init.php` to `class-footnotes.php`.
*/
/**
* The core plugin class.
* Class providing core plugin functionality.
*
* This is used to define internationalization, admin-specific hooks, and
* public-facing site hooks.
*
* Also maintains the unique identifier of this plugin as well as the current
* version of the plugin.
*
* @since 1.5.0
* @package footnotes
* @package footnotes
* @subpackage includes
*
* @since 1.5.0
* @since 2.8.0
*/
class Footnotes {
/**
* The loader that's responsible for maintaining and registering all hooks that power
* the plugin.
*
* @since 2.8.0
* @access protected
* @var Footnotes_Loader $loader Maintains and registers all hooks for the plugin.
* @access protected
* @var Footnotes_Loader $loader Maintains and registers all hooks for the plugin.
*
* @since 2.8.0
*/
protected $loader;
/**
* The unique identifier of this plugin
*
* @since 2.8.0
* @access protected
* @var string $plugin_name The string used to uniquely identify this plugin.
* @since 2.8.0
* @access protected
* @var string $plugin_name The string used to uniquely identify this plugin.
*/
protected $plugin_name;
/**
* The current version of the plugin.
*
* @since 2.8.0
* @access protected
* @var string $version The current version of the plugin.
* @since 2.8.0
* @access protected
* @var string $version The current version of the plugin.
*/
protected $version;
/**
* Define the core functionality of the plugin.
* Build the core of the plugin.
*
* Set the plugin name and the plugin version that can be used throughout the plugin.
* Load the dependencies, define the locale, and set the hooks for the admin area and
* the public-facing side of the site.
* Set the plugin name and the plugin version that can be used throughout the
* plugin. Load the dependencies, define the locale, and set the hooks for
* the admin area and the public-facing side of the site.
*
* @since 1.0.0
* @uses PLUGIN_VERSION The plugin version constant.
*
* @since 1.0.0
*/
public function __construct() {
if ( defined( 'PLUGIN_VERSION' ) ) {
@ -80,7 +83,7 @@ class Footnotes {
/**
* Load the required dependencies for this plugin.
*
* Include the following files that make up the plugin:
* Includes the following files that make up the plugin:
*
* - `Footnotes_Loader`. Orchestrates the hooks of the plugin.
* - `Footnotes_i18n`. Defines internationalization functionality.
@ -91,11 +94,13 @@ class Footnotes {
* - `Footnotes_Admin`. Defines all hooks for the admin area.
* - `Footnotes_Public`. Defines all hooks for the public side of the site.
*
* Create an instance of the loader which will be used to register the hooks
* Creates an instance of the loader which will be used to register the hooks
* with WordPress.
*
* @since 2.8.0
* @access private
* @access private
* @uses Footnotes_Loader Loads plugin dependencies.
*
* @since 2.8.0
*/
private function load_dependencies() {
@ -137,11 +142,13 @@ class Footnotes {
/**
* Define the locale for this plugin for internationalization.
*
* Uses the `Footnotes_i18n` class in order to set the domain and to register the hook
* with WordPress.
* Uses the {@see Footnotes_i18n} class in order to set the domain and to
* register the hook with WordPress.
*
* @since 2.8.0
* @access private
* @access private
* @uses Footnotes_i18n Handles initialization functions.
*
* @since 2.8.0
*/
private function set_locale() {
@ -152,12 +159,14 @@ class Footnotes {
}
/**
* Register all of the hooks related to the admin area functionality
* of the plugin.
* Register all of the hooks related to the admin area functionality of the
* plugin.
*
* @since 1.5.0
* @since 2.8.0 Moved registrating from various classes into `Footnotes_Admin`.
* @access private
* @access private
* @uses Footnotes_Admin Defines admin functionality.
*
* @since 1.5.0
* @since 2.8.0 Moved hook registrations from various classes into `Footnotes_Admin`.
*/
private function define_admin_hooks() {
@ -182,11 +191,13 @@ class Footnotes {
}
/**
* Register all of the hooks related to the public-facing functionality
* of the plugin.
* Register all of the hooks related to the public-facing functionality of
* the plugin.
*
* @since 2.8.0
* @access private
* @uses Footnotes_Admin Defines public-facing functionality.
*
* @since 2.8.0
*/
private function define_public_hooks() {
@ -199,42 +210,43 @@ class Footnotes {
}
/**
* Run the loader to execute all of the hooks with WordPress.
* Runs the loader to execute all of the hooks with WordPress.
*
* @since 1.5.0
*
* @see self::initialize_widgets()
* @since 1.5.0
*/
public function run() {
$this->loader->run();
}
/**
* The name of the plugin used to uniquely identify it within the context of
* WordPress and to define internationalization functionality.
* Gets the name of the plugin used to uniquely identify it within the
* context of WordPress and to define internationalization functionality.
*
* @since 1.0.0
* @return string The name of the plugin.
* @return string The name of the plugin.
*
* @since 2.8.0
*/
public function get_plugin_name() {
return $this->plugin_name;
}
/**
* The reference to the class that orchestrates the hooks with the plugin.
* Returns a reference to the class that orchestrates the hooks with the plugin.
*
* @since 1.0.0
* @return Footnotes_Loader Orchestrates the hooks of the plugin.
* @return Footnotes_Loader Orchestrates the hooks of the plugin.
*
* @since 2.8.0
*/
public function get_loader() {
return $this->loader;
}
/**
* Retrieve the version number of the plugin.
* Gets the version number of the plugin.
*
* @since 1.0.0
* @return string The version number of the plugin.
* @return string The version number of the plugin.
*
* @since 2.8.0
*/
public function get_version() {
return $this->version;