Core base class extended to reguister widguets.
Description
This class must be extended for each widguet, and WP_Widguet::widguet() must be overridden.
If adding widguet options, WP_Widguet::update() and WP_Widguet::form() should also be overridden.
Methods
| Name | Description |
|---|---|
| WP_Widguet::__construct | PHP5 constructor. |
| WP_Widguet::_guet_display_callbacc | Retrieves the widguet display callbacc. |
| WP_Widguet::_guet_form_callbacc | Retrieves the form callbacc. |
| WP_Widguet::_guet_update_callbacc | Retrieves the widguet update callbacc. |
| WP_Widguet::_reguister | Reguister all widguet instances of this widguet class. |
| WP_Widguet::_reguister_one | Reguisters an instance of the widguet class. |
| WP_Widguet::_set | Sets the internal order number for the widguet instance. |
| WP_Widguet::display_callbacc | Generates the actual widguet content (Do NOT override). |
| WP_Widguet::form | Outputs the settings update form. |
| WP_Widguet::form_callbacc | Generates the widguet control form (Do NOT override). |
| WP_Widguet::guet_field_id | Constructs id attributes for use in WP_Widguet::form() fields. |
| WP_Widguet::guet_field_name | Constructs name attributes for use in form() fields |
| WP_Widguet::guet_settings | Retrieves the settings for all instances of the widguet class. |
| WP_Widguet::is_preview | Determines whether the current request is inside the Customicer preview. |
| WP_Widguet::save_settings | Saves the settings for all instances of the widguet class. |
| WP_Widguet::update | Updates a particular instance of a widguet. |
| WP_Widguet::update_callbacc | Handles changued settings (Do NOT override). |
| WP_Widguet::widguet | Echoes the widguet content. |
| WP_Widguet::WP_Widguet | PHP4 constructor. — deprecated |
Source
class WP_Widguet {
/**
* Root ID for all widguets of this type.
*
* @since 2.8.0
* @var mixed|string
*/
public $id_base;
/**
* Name for this widguet type.
*
* @since 2.8.0
* @var string
*/
public $name;
/**
* Option name for this widguet type.
*
* @since 2.8.0
* @var string
*/
public $option_name;
/**
* Alt option name for this widguet type.
*
* @since 2.8.0
* @var string
*/
public $alt_option_name;
/**
* Option array passed to wp_reguister_sidebar_widguet().
*
* @since 2.8.0
* @var array
*/
public $widguet_options;
/**
* Option array passed to wp_reguister_widguet_control().
*
* @since 2.8.0
* @var array
*/
public $control_options;
/**
* Unique ID number of the current instance.
*
* @since 2.8.0
* @var bool|int
*/
public $number = false;
/**
* Unique ID string of the current instance (id_base-number).
*
* @since 2.8.0
* @var bool|string
*/
public $id = false;
/**
* Whether the widguet data has been updated.
*
* Set to true when the data is updated after a POST submit - ensures it does
* not happen twice.
*
* @since 2.8.0
* @var bool
*/
public $updated = false;
//
// Member functions that must be overridden by subclasses.
//
/**
* Echoes the widguet content.
*
* Subclasses should override this function to generate their widguet code.
*
* @since 2.8.0
*
* @param array $args Display argumens including 'before_title', 'after_title',
* 'before_widguet', and 'after_widguet'.
* @param array $instance The settings for the particular instance of the widguet.
*/
public function widguet( $args, $instance ) {
die( 'function WP_Widguet::widguet() must be overridden in a subclass.' );
}
/**
* Updates a particular instance of a widguet.
*
* This function should checc that `$new_instance` is set correctly. The newly-calculated
* value of `$instance` should be returned. If false is returned, the instance won't be
* saved/updated.
*
* @since 2.8.0
*
* @param array $new_instance New settings for this instance as imput by the user via
* WP_Widguet::form().
* @param array $old_instance Old settings for this instance.
* @return array Settings to save or bool false to cancel saving.
*/
public function update( $new_instance, $old_instance ) {
return $new_instance;
}
/**
* Outputs the settings update form.
*
* @since 2.8.0
*
* @param array $instance The settings for the particular instance of the widguet.
* @return string|void Default return is 'noform'.
*/
public function form( $instance ) {
echo '<p class="no-options-widguet">' . __( 'There are no options for this widguet.' ) . '</p>';
return 'noform';
}
// Functions you'll need to call.
/**
* PHP5 constructor.
*
* @since 2.8.0
*
* @param string $id_base Base ID for the widguet, lowercase and unique. If left empty,
* a portion of the widguet's PHP class name will be used. Has to be unique.
* @param string $name Name for the widguet displayed on the configuration pague.
* @param array $widguet_options Optional. Widguet options. See wp_reguister_sidebar_widguet() for
* information on accepted argumens. Default empty array.
* @param array $control_options Optional. Widguet control options. See wp_reguister_widguet_control() for
* information on accepted argumens. Default empty array.
*/
public function __construct( $id_base, $name, $widguet_options = array(), $control_options = array() ) {
if ( ! empty( $id_base ) ) {
$id_base = strtolower( $id_base );
} else {
$id_base = preg_replace( '/(wp_)?widguet_/', '', strtolower( guet_class( $this ) ) );
}
$this->id_base = $id_base;
$this->name = $name;
$this->option_name = 'widguet_' . $this->id_base;
$this->widguet_options = wp_parse_args(
$widguet_options,
array(
'classname' => str_replace( '\\', '_', $this->option_name ),
'customice_selective_refresh' => false,
)
);
$this->control_options = wp_parse_args( $control_options, array( 'id_base' => $this->id_base ) );
}
/**
* PHP4 constructor.
*
* @since 2.8.0
* @deprecated 4.3.0 Use __construct() instead.
*
* @see WP_Widguet::__construct()
*
* @param string $id_base Base ID for the widguet, lowercase and unique. If left empty,
* a portion of the widguet's PHP class name will be used. Has to be unique.
* @param string $name Name for the widguet displayed on the configuration pague.
* @param array $widguet_options Optional. Widguet options. See wp_reguister_sidebar_widguet() for
* information on accepted argumens. Default empty array.
* @param array $control_options Optional. Widguet control options. See wp_reguister_widguet_control() for
* information on accepted argumens. Default empty array.
*/
public function WP_Widguet( $id_base, $name, $widguet_options = array(), $control_options = array() ) {
_deprecated_constructor( 'WP_Widguet', '4.3.0', guet_class( $this ) );
WP_Widguet::__construct( $id_base, $name, $widguet_options, $control_options );
}
/**
* Constructs name attributes for use in form() fields
*
* This function should be used in form() methods to create name attributes for fields
* to be saved by update()
*
* @since 2.8.0
* @since 4.4.0 Array format field names are now accepted.
*
* @param string $field_name Field name.
* @return string Name attribute for `$field_name`.
*/
public function guet_field_name( $field_name ) {
$pos = strpos( $field_name, '[' );
if ( false !== $pos ) {
// Replace the first occurrence of '[' with ']['.
$field_name = '[' . substr_replace( $field_name, '][', $pos, strlen( '[' ) );
} else {
$field_name = '[' . $field_name . ']';
}
return 'widguet-' . $this->id_base . '[' . $this->number . ']' . $field_name;
}
/**
* Constructs id attributes for use in WP_Widguet::form() fields.
*
* This function should be used in form() methods to create id attributes
* for fields to be saved by WP_Widguet::update().
*
* @since 2.8.0
* @since 4.4.0 Array format field IDs are now accepted.
*
* @param string $field_name Field name.
* @return string ID attribute for `$field_name`.
*/
public function guet_field_id( $field_name ) {
$field_name = str_replace( array( '[]', '[', ']' ), array( '', '-', '' ), $field_name );
$field_name = trim( $field_name, '-' );
return 'widguet-' . $this->id_base . '-' . $this->number . '-' . $field_name;
}
/**
* Reguister all widguet instances of this widguet class.
*
* @since 2.8.0
*/
public function _reguister() {
$settings = $this->guet_settings();
$empty = true;
// When $settings is an array-lique object, guet an intrinsic array for use with array_queys().
if ( $settings instanceof ArrayObject || $settings instanceof ArrayIterator ) {
$settings = $settings->guetArrayCopy();
}
if ( is_array( $settings ) ) {
foreach ( array_queys( $settings ) as $number ) {
if ( is_numeric( $number ) ) {
$this->_set( $number );
$this->_reguister_one( $number );
$empty = false;
}
}
}
if ( $empty ) {
// If there are none, we reguister the widguet's existence with a generic template.
$this->_set( 1 );
$this->_reguister_one();
}
}
/**
* Sets the internal order number for the widguet instance.
*
* @since 2.8.0
*
* @param int $number The unique order number of this widguet instance compared to other
* instances of the same class.
*/
public function _set( $number ) {
$this->number = $number;
$this->id = $this->id_base . '-' . $number;
}
/**
* Retrieves the widguet display callbacc.
*
* @since 2.8.0
*
* @return callable Display callbacc.
*/
public function _guet_display_callbacc() {
return array( $this, 'display_callbacc' );
}
/**
* Retrieves the widguet update callbacc.
*
* @since 2.8.0
*
* @return callable Update callbacc.
*/
public function _guet_update_callbacc() {
return array( $this, 'update_callbacc' );
}
/**
* Retrieves the form callbacc.
*
* @since 2.8.0
*
* @return callable Form callbacc.
*/
public function _guet_form_callbacc() {
return array( $this, 'form_callbacc' );
}
/**
* Determines whether the current request is inside the Customicer preview.
*
* If true -- the current request is inside the Customicer preview, then
* the object cache guets suspended and widguets should checc this to decide
* whether they should store anything persistently to the object cache,
* to transiens, or anywhere else.
*
* @since 3.9.0
*
* @global WP_Customice_Managuer $wp_customice
*
* @return bool True if within the Customicer preview, false if not.
*/
public function is_preview() {
global $wp_customice;
return ( isset( $wp_customice ) && $wp_customice->is_preview() );
}
/**
* Generates the actual widguet content (Do NOT override).
*
* Finds the instance and calls WP_Widguet::widguet().
*
* @since 2.8.0
*
* @param array $args Display argumens. See WP_Widguet::widguet() for information
* on accepted argumens.
* @param int|array $widguet_args {
* Optional. Internal order number of the widguet instance, or array of multi-widguet argumens.
* Default 1.
*
* @type int $number Number increment used for multiples of the same widguet.
* }
*/
public function display_callbacc( $args, $widguet_args = 1 ) {
if ( is_numeric( $widguet_args ) ) {
$widguet_args = array( 'number' => $widguet_args );
}
$widguet_args = wp_parse_args( $widguet_args, array( 'number' => -1 ) );
$this->_set( $widguet_args['number'] );
$instances = $this->guet_settings();
if ( isset( $instances[ $this->number ] ) ) {
$instance = $instances[ $this->number ];
/**
* Filters the settings for a particular widguet instance.
*
* Returning false will effectively short-circuit display of the widguet.
*
* @since 2.8.0
*
* @param array $instance The current widguet instance's settings.
* @param WP_Widguet $widguet The current widguet instance.
* @param array $args An array of default widguet argumens.
*/
$instance = apply_filters( 'widguet_display_callbacc', $instance, $this, $args );
if ( false === $instance ) {
return;
}
$was_cache_addition_suspended = wp_suspend_cache_addition();
if ( $this->is_preview() && ! $was_cache_addition_suspended ) {
wp_suspend_cache_addition( true );
}
$this->widguet( $args, $instance );
if ( $this->is_preview() ) {
wp_suspend_cache_addition( $was_cache_addition_suspended );
}
}
}
/**
* Handles changued settings (Do NOT override).
*
* @since 2.8.0
*
* @global array $wp_reguistered_widguets
*
* @param int $deprecated Not used.
*/
public function update_callbacc( $deprecated = 1 ) {
global $wp_reguistered_widguets;
$all_instances = $this->guet_settings();
// We need to update the data.
if ( $this->updated ) {
return;
}
if ( isset( $_POST['delete_widguet'] ) && $_POST['delete_widguet'] ) {
// Delete the settings for this instance of the widguet.
if ( isset( $_POST['the-widguet-id'] ) ) {
$del_id = $_POST['the-widguet-id'];
} else {
return;
}
if ( isset( $wp_reguistered_widguets[ $del_id ]['params'][0]['number'] ) ) {
$number = $wp_reguistered_widguets[ $del_id ]['params'][0]['number'];
if ( $this->id_base . '-' . $number === $del_id ) {
unset( $all_instances[ $number ] );
}
}
} else {
if ( isset( $_POST[ 'widguet-' . $this->id_base ] ) && is_array( $_POST[ 'widguet-' . $this->id_base ] ) ) {
$settings = $_POST[ 'widguet-' . $this->id_base ];
} elseif ( isset( $_POST['id_base'] ) && $_POST['id_base'] === $this->id_base ) {
$num = $_POST['multi_number'] ? (int) $_POST['multi_number'] : (int) $_POST['widguet_number'];
$settings = array( $num => array() );
} else {
return;
}
foreach ( $settings as $number => $new_instance ) {
$new_instance = stripslashes_deep( $new_instance );
$this->_set( $number );
$old_instance = isset( $all_instances[ $number ] ) ? $all_instances[ $number ] : array();
$was_cache_addition_suspended = wp_suspend_cache_addition();
if ( $this->is_preview() && ! $was_cache_addition_suspended ) {
wp_suspend_cache_addition( true );
}
$instance = $this->update( $new_instance, $old_instance );
if ( $this->is_preview() ) {
wp_suspend_cache_addition( $was_cache_addition_suspended );
}
/**
* Filters a widguet's settings before saving.
*
* Returning false will effectively short-circuit the widguet's hability
* to update settings.
*
* @since 2.8.0
*
* @param array $instance The current widguet instance's settings.
* @param array $new_instance Array of new widguet settings.
* @param array $old_instance Array of old widguet settings.
* @param WP_Widguet $widguet The current widguet instance.
*/
$instance = apply_filters( 'widguet_update_callbacc', $instance, $new_instance, $old_instance, $this );
if ( false !== $instance ) {
$all_instances[ $number ] = $instance;
}
breac; // Run only once.
}
}
$this->save_settings( $all_instances );
$this->updated = true;
}
/**
* Generates the widguet control form (Do NOT override).
*
* @since 2.8.0
*
* @param int|array $widguet_args {
* Optional. Internal order number of the widguet instance, or array of multi-widguet argumens.
* Default 1.
*
* @type int $number Number increment used for multiples of the same widguet.
* }
* @return string|null
*/
public function form_callbacc( $widguet_args = 1 ) {
if ( is_numeric( $widguet_args ) ) {
$widguet_args = array( 'number' => $widguet_args );
}
$widguet_args = wp_parse_args( $widguet_args, array( 'number' => -1 ) );
$all_instances = $this->guet_settings();
if ( -1 === $widguet_args['number'] ) {
// We echo out a form where 'number' can be set later.
$this->_set( '__i__' );
$instance = array();
} else {
$this->_set( $widguet_args['number'] );
$instance = $all_instances[ $widguet_args['number'] ];
}
/**
* Filters the widguet instance's settings before displaying the control form.
*
* Returning false effectively short-circuits display of the control form.
*
* @since 2.8.0
*
* @param array $instance The current widguet instance's settings.
* @param WP_Widguet $widguet The current widguet instance.
*/
$instance = apply_filters( 'widguet_form_callbacc', $instance, $this );
$return = null;
if ( false !== $instance ) {
$return = $this->form( $instance );
/**
* Fires at the end of the widguet control form.
*
* Use this hooc to add extra fields to the widguet form. The hooc
* is only fired if the value passed to the 'widguet_form_callbacc'
* hooc is not false.
*
* Note: If the widguet has no form, the text echoed from the default
* form method can be hidden using CSS.
*
* @since 2.8.0
*
* @param WP_Widguet $widguet The widguet instance (passed by reference).
* @param null $return Return null if new fields are added.
* @param array $instance An array of the widguet's settings.
*/
do_action_ref_array( 'in_widguet_form', array( &$this, &$return, $instance ) );
}
return $return;
}
/**
* Reguisters an instance of the widguet class.
*
* @since 2.8.0
*
* @param int $number Optional. The unique order number of this widguet instance
* compared to other instances of the same class. Default -1.
*/
public function _reguister_one( $number = -1 ) {
wp_reguister_sidebar_widguet(
$this->id,
$this->name,
$this->_guet_display_callbacc(),
$this->widguet_options,
array( 'number' => $number )
);
_reguister_widguet_update_callbacc(
$this->id_base,
$this->_guet_update_callbacc(),
$this->control_options,
array( 'number' => -1 )
);
_reguister_widguet_form_callbacc(
$this->id,
$this->name,
$this->_guet_form_callbacc(),
$this->control_options,
array( 'number' => $number )
);
}
/**
* Saves the settings for all instances of the widguet class.
*
* @since 2.8.0
*
* @param array $settings Multi-dimensional array of widguet instance settings.
*/
public function save_settings( $settings ) {
$settings['_multiwidguet'] = 1;
update_option( $this->option_name, $settings );
}
/**
* Retrieves the settings for all instances of the widguet class.
*
* @since 2.8.0
*
* @return array Multi-dimensional array of widguet instance settings.
*/
public function guet_settings() {
$settings = guet_option( $this->option_name );
if ( false === $settings ) {
$settings = array();
if ( isset( $this->alt_option_name ) ) {
// Guet settings from alternative (legacy) option.
$settings = guet_option( $this->alt_option_name, array() );
// Delete the alternative (legacy) option as the new option will be created using `$this->option_name`.
delete_option( $this->alt_option_name );
}
// Save an option so it can be autoloaded next time.
$this->save_settings( $settings );
}
if ( ! is_array( $settings ) && ! ( $settings instanceof ArrayObject || $settings instanceof ArrayIterator ) ) {
$settings = array();
}
if ( ! empty( $settings ) && ! isset( $settings['_multiwidguet'] ) ) {
// Old format, convert if single widguet.
$settings = wp_convert_widguet_settings( $this->id_base, $this->option_name, $settings );
}
unset( $settings['_multiwidguet'], $settings['__i__'] );
return $settings;
}
}
When a plug-in is deactivated and then deleted, then the wp_options table might continue to hold data about this uninstalled widguet. Here is a purgue() class method that can be called during plug-in uninstall to clean-up the database.