class-gv-widget.php

Go to the documentation of this file.

<?php
namespace GV;

/** If this file is called directly, abort. */
if ( ! defined( 'GRAVITYVIEW_DIR' ) ) {
 die();
}

/**
 * The \GV\Widget class.
 *
 * An interface that most GravityView widgets would want to adhere to and inherit from.
 */
abstract class Widget {

 /**
 * Widget admin label
 * @var string
 */
 protected $widget_label = '';

 /**
 * Widget description, shown on the "+ Add Widget" picker
 * @var string
 */
 protected $widget_description = '';

 /**
 * Widget details, shown in the widget modal
 * @since 1.8
 * @var string
 */
 protected $widget_subtitle = '';

 /**
 * Widget admin ID
 * @var string
 */
 protected $widget_id = '';

 /**
 * Default configuration for header and footer
 * @var array
 */
 protected $defaults = array();

 /**
 * Widget admin advanced settings
 * @var array
 */
 protected $settings = array();

 /**
 * Allow class to automatically add widget_text filter for you in shortcode
 * @var string
 */
 protected $shortcode_name;

 /**
 * Hold the widget options.
 * @var array()
 */
 private $widget_options = array();

 /**
 * The position of the widget.
 * @api
 * @since 2.0
 * @var string
 */
 public $position = '';

 /**
 * A unique ID for this widget.
 * @api
 * @since 2.0
 * @var string
 */
 public $UID = '';

 /**
 * The actual configuration for this widget instance.
 *
 * @api
 * @since 2.0
 * @var \GV\Settings
 */
 public $configuration;

 /**
 * @var string An icon that represents the widget type in the widget picker.
 *
 * Supports these icon formats:
 * - Gravity Forms icon class: The string starts with "gform-icon". Note: the site must be running GF 2.5+. No need to also pass "gform-icon".
 * - Dashicons: The string starts with "dashicons". No need to also pass "dashicons".
 * - Inline SVG: Starts with "data:". Note: No single quotes are allowed!
 * - If not matching those formats, the value will be used as a CSS class in a `<i>` element.
 *
 * @see GravityView_Admin_View_Item::getOutput
 */
 public $icon;

 /**
 * Constructor.
 *
 * @param string $label The Widget label as shown in the admin.
 * @param string $id The Widget ID, make this something unique.
 * @param array $defaults Default footer/header Widget configuration.
 * @param array $settings Advanced Widget settings.
 *
 * @return \GV\Widget
 */
 public function __construct( $label, $id, $defaults = array(), $settings = array() ) {
 /**
 * The shortcode name is set to the lowercase name of the widget class, unless overridden by the class specifying a different value for $shortcode_name
 * @var string
 */
 $this->shortcode_name = empty( $this->shortcode_name ) ? strtolower( get_called_class() ) : $this->shortcode_name;

 if ( $id ) {
 $this->widget_id = $id;
 }

 $this->widget_label = $label;
 $this->defaults = array_merge( array( 'header' => 0, 'footer' => 0 ), $defaults );

 // Make sure every widget has a title, even if empty
 $this->settings = wp_parse_args( $settings, $this->get_default_settings() );

 // Hook once per unique ID
 if ( $this->is_registered() ) {
 return;
 }

 // widget options
 add_filter( 'gravityview_template_widget_options', array( $this, 'assign_widget_options' ), 10, 3 );

 // frontend logic
 add_action( sprintf( 'gravityview/widgets/%s/render', $this->get_widget_id() ), array( $this, 'render_frontend' ), 10, 3 );

 // register shortcodes
 add_action( 'wp', array( $this, 'add_shortcode' ) );

 // Use shortcodes in text widgets.
 add_filter( 'widget_text', array( $this, 'maybe_do_shortcode' ) );

 // register widgets to be listed in the View Configuration
 // Important: this has to be the last filter/action added in the constructor.
 add_filter( 'gravityview/widgets/register', array( $this, 'register_widget' ) );
 }

 /**
 * Define general widget settings
 * @since 1.5.4
 * @return array $settings Default settings
 */
 protected function get_default_settings() {
 $settings = array();

 /**
 * @filter `gravityview/widget/enable_custom_class` Enable custom CSS class settings for widgets
 * @param boolean $enable_custom_class False by default. Return true if you want to enable.
 * @param \GV\Widget $this Current instance of \GV\Widget.
 */
 $enable_custom_class = apply_filters( 'gravityview/widget/enable_custom_class', false, $this );

 if ( $enable_custom_class ) {
 $settings['custom_class'] = array(
 'type' => 'text',
 'label' => __( 'Custom CSS Class:', 'gk-gravityview' ),
 'desc' => __( 'This class will be added to the widget container', 'gk-gravityview' ),
 'value' => '',
 'merge_tags' => true,
 'class' => 'widefat code',
 );
 }

 return $settings;
 }

 /**
 * Get the Widget ID.
 *
 * @return string The Widget ID.
 */
 public function get_widget_id() {
 return $this->widget_id;
 }

 /**
 * Get the widget settings
 *
 * @return array|null Settings array; NULL if not set for some reason.
 */
 public function get_settings() {
 return empty( $this->settings ) ? null : $this->settings;
 }

 /**
 * Get a setting by the setting key.
 *
 * @param string $key Key for the setting
 *
 * @todo Use the \GV\Settings class later. For now subclasses may still expect and array instead.
 *
 * @return mixed|null Value of the setting; NULL if not set
 */
 public function get_setting( $key ) {
 return Utils::get( $this->settings, $key, null );
 }

 /**
 * Default widget areas.
 *
 * Usually overridden by the selected template.
 *
 * @return array The default areas where widgets can be rendered.
 */
 public static function get_default_widget_areas() {

 $default_areas = array(
 array(
 '1-1' => array(
 array(
 'areaid' => 'top',
 'title' => __( 'Top', 'gk-gravityview' ) ,
 'subtitle' => ''
 ),
 ),
 ),
 array(
 '1-2' => array(
 array(
 'areaid' => 'left',
 'title' => __( 'Left', 'gk-gravityview' ) ,
 'subtitle' => ''
 ),
 ),
 '2-2' => array(
 array(
 'areaid' => 'right',
 'title' => __( 'Right', 'gk-gravityview' ) ,
 'subtitle' => ''
 ),
 ),
 ),
 );

 /**
 * @filter `gravityview_widget_active_areas` Array of zones available for widgets to be dropped into
 * @deprecated 2.0: Use gravityview/widget/active_areas instead
 * @param array $default_areas Definition for default widget areas
 */
 $default_areas = apply_filters( 'gravityview_widget_active_areas', $default_areas );

 /**
 * @filter `gravityview/widget/active_areas` Array of zones available for widgets to be dropped into
 * @since 2.0
 * @param array $default_areas Definition for default widget areas
 */
 return apply_filters( 'gravityview/widget/active_areas', $default_areas );
 }

 /**
 * Register widget to become available in admin. And for lookup.
 *
 * @param array $widgets Usually just empty. Used to gather them all up.
 *
 * @return array $widgets
 */
 public function register_widget( $widgets ) {
 if ( ! is_array( $widgets ) ) {
 $widgets = array();
 }

 $widgets[ $this->get_widget_id() ] = array(
 'label' => $this->widget_label ,
 'description' => $this->widget_description,
 'subtitle' => $this->widget_subtitle,
 'icon' => $this->icon,
 'class' => get_called_class(),
 );

 return $widgets;
 }

 /**
 * Assign template specific widget options
 *
 * @access protected
 *
 * @param array $options (default: array())
 * @param string $template (default: '')
 *
 * @return array
 */
 public function assign_widget_options( $options = array(), $template = '', $widget = '' ) {
 if ( $this->get_widget_id() === $widget ) {
 if( $settings = $this->get_settings() ) {
 $options = array_merge( $options, $settings );
 }
 }
 return $options;
 }

 /**
 * Do shortcode if the Widget's shortcode exists.
 *
 * @param string $text Widget text to check
 * @param null|\WP_Widget Empty if not called by WP_Widget, or a WP_Widget instance
 *
 * @return string Widget text
 */
 public function maybe_do_shortcode( $text, $widget = null ) {
 if ( ! empty( $this->shortcode_name ) && has_shortcode( $text, $this->shortcode_name ) ) {
 return do_shortcode( $text );
 }
 return $text;
 }

 /**
 * Add $this->shortcode_name shortcode to output self::render_frontend()
 *
 * @return void
 */
 public function add_shortcode() {
 if ( empty( $this->shortcode_name ) ) {
 return;
 }

 if ( ! gravityview()->plugin->is_compatible() ) {
 return;
 }

 if ( gravityview()->request->is_admin() ) {
 return;
 }

 // If the widget shouldn't output on single entries, don't show it
 if ( empty( $this->show_on_single ) && gravityview()->request->is_entry() ) {
 gravityview()->log->debug( 'Skipping; set to not run on single entry.' );
 add_shortcode( $this->shortcode_name, '__return_null' );
 return;
 }

 global $post;

 if ( ! is_object( $post ) || empty( $post->post_content ) || ! Shortcode::parse( $post->post_content ) ) {
 add_shortcode( $this->shortcode_name, '__return_null' );
 return;
 }

 add_shortcode( $this->shortcode_name, array( $this, 'render_shortcode') );
 }

 /**
 * Frontend logic.
 *
 * Override in child class.
 *
 * @param array $widget_args The Widget shortcode args.
 * @param string $content The content.
 * @param string|\GV\Template_Context $context The context, if available.
 *
 * @return void
 */
 public function render_frontend( $widget_args, $content = '', $context = '' ) {
 }

 /**
 * General validations when rendering the widget
 *
 * Always call this from your `render_frontend()` override!
 *
 * @return boolean True: render frontend; False: don't render frontend
 */
 public function pre_render_frontend() {

 /**
 * Assume shown regardless of hide_until_search setting.
 */
 $allowlist = array(
 'custom_content',
 );

 /**
 * @deprecated 2.14 In favor of allowlist.
 */
 $allowlist = apply_filters_deprecated( 'gravityview/widget/hide_until_searched/whitelist', array( $allowlist ), '2.14', 'gravityview/widget/hide_until_searched/allowlist' );

 /**
 * @filter `gravityview/widget/hide_until_searched/allowlist` Some widgets have got to stay shown.
 * @since 2.14
 * @param string[] $allowlist The widget IDs that have to be shown by default.
 */
 $allowlist = apply_filters( 'gravityview/widget/hide_until_searched/allowlist', $allowlist );

 if ( ( $view = gravityview()->views->get() ) && ! in_array( $this->get_widget_id(), $allowlist ) ) {
 $hide_until_searched = $view->settings->get( 'hide_until_searched' );
 } else {
 $hide_until_searched = false;
 }

 /**
 * @filter `gravityview/widget/hide_until_searched` Modify whether to hide content until search
 * @param boolean $hide_until_searched Hide until search?
 * @param \GV\Widget $this Widget instance
 */
 $hide_until_searched = apply_filters( 'gravityview/widget/hide_until_searched', $hide_until_searched, $this );

 if ( $hide_until_searched && ! gravityview()->request->is_search() ) {
 gravityview()->log->debug( 'Hide View data until search is performed' );
 return false;
 }

 return true;
 }

 /**
 * Shortcode.
 *
 * @param array $atts The Widget shortcode args.
 * @param string $content The content.
 * @param string|\GV\Template_Context $context The context, if available.
 *
 * @return string Whatever the widget echoed.
 */
 public function render_shortcode( $atts, $content = '', $context = '' ) {
 ob_start();
 $this->render_frontend( $atts, $content, $context );
 return ob_get_clean();
 }

 /**
 * Create the needed widget from a configuration array.
 *
 * @param array $configuration The configuration array.
 * @see \GV\Widget::as_configuration()
 * @internal
 * @since 2.0
 *
 * @return \GV\Widget|null The widget implementation from configuration or none.
 */
 public static function from_configuration( $configuration ) {
 $registered_widgets = self::registered();

 if ( ! $id = Utils::get( $configuration, 'id' ) ) {
 return null;
 }

 if ( ! $widget = Utils::get( $registered_widgets, $id ) ) {
 return null;
 }

 if ( ! class_exists( $class = Utils::get( $widget, 'class' ) ) ) {
 return null;
 }

 $w = new $class( Utils::get( $widget, 'label' ), $id );
 $w->configuration = new Settings( $configuration );

 return $w;
 }

 /**
 * Return an array of the old format.
 *
 * 'id' => string
 * + whatever else specific fields may have
 *
 * @internal
 * @since 2.0
 *
 * @return array
 */
 public function as_configuration() {
 return array_merge( array(
 'id' => $this->get_widget_id(),
 ), $this->configuration->all() );
 }

 /**
 * Return all registered widgets.
 *
 * @api
 * @since 2.0
 *
 * @return array
 */
 public static function registered() {
 /**
 * @filter `gravityview_register_directory_widgets` Get the list of registered widgets. Each item is used to instantiate a GravityView_Admin_View_Widget object
 * @deprecated Use `gravityview/widgets/register`
 * @param array $registered_widgets Empty array
 */
 $registered_widgets = apply_filters( 'gravityview_register_directory_widgets', array() );

 /**
 * @filter `gravityview/widgets/register` Each item is used to instantiate a GravityView_Admin_View_Widget object
 * @param array $registered_widgets Empty array
 */
 return apply_filters( 'gravityview/widgets/register', $registered_widgets );
 }

 /**
 * Whether this Widget's been registered already or not.
 *
 * @api
 * @since 2.0
 *
 * @return bool
 */
 public function is_registered() {
 if ( ! $widget_id = $this->get_widget_id() ) {
 gravityview()->log->warning( 'Widget ID not set before calling Widget::is_registered', array( 'data' => $this ) );
 return false;
 }
 return in_array( $widget_id, array_keys( self::registered() ), true );
 }
}