home *** CD-ROM | disk | FTP | other *** search
/ HTML Examples / WP.iso / wordpress2 / wp-includes / customize / class-wp-customize-partial.php < prev    next >
Encoding:
PHP Script  |  2017-09-09  |  8.6 KB  |  312 lines
  1. <?php
  2. /**
  3.  * Customize API: WP_Customize_Partial class
  4.  *
  5.  * @package WordPress
  6.  * @subpackage Customize
  7.  * @since 4.5.0
  8.  */
  9.  
  10. /**
  11.  * Core Customizer class for implementing selective refresh partials.
  12.  *
  13.  * Representation of a rendered region in the previewed page that gets
  14.  * selectively refreshed when an associated setting is changed.
  15.  * This class is analogous of WP_Customize_Control.
  16.  *
  17.  * @since 4.5.0
  18.  */
  19. class WP_Customize_Partial {
  20.  
  21.     /**
  22.      * Component.
  23.      *
  24.      * @since 4.5.0
  25.      * @var WP_Customize_Selective_Refresh
  26.      */
  27.     public $component;
  28.  
  29.     /**
  30.      * Unique identifier for the partial.
  31.      *
  32.      * If the partial is used to display a single setting, this would generally
  33.      * be the same as the associated setting's ID.
  34.      *
  35.      * @since 4.5.0
  36.      * @var string
  37.      */
  38.     public $id;
  39.  
  40.     /**
  41.      * Parsed ID.
  42.      *
  43.      * @since 4.5.0
  44.      * @var array {
  45.      *     @type string $base ID base.
  46.      *     @type array  $keys Keys for multidimensional.
  47.      * }
  48.      */
  49.     protected $id_data = array();
  50.  
  51.     /**
  52.      * Type of this partial.
  53.      *
  54.      * @since 4.5.0
  55.      * @var string
  56.      */
  57.     public $type = 'default';
  58.  
  59.     /**
  60.      * The jQuery selector to find the container element for the partial.
  61.      *
  62.      * @since 4.5.0
  63.      * @var string
  64.      */
  65.     public $selector;
  66.  
  67.     /**
  68.      * IDs for settings tied to the partial.
  69.      *
  70.      * @since 4.5.0
  71.      * @var array
  72.      */
  73.     public $settings;
  74.  
  75.     /**
  76.      * The ID for the setting that this partial is primarily responsible for rendering.
  77.      *
  78.      * If not supplied, it will default to the ID of the first setting.
  79.      *
  80.      * @since 4.5.0
  81.      * @var string
  82.      */
  83.     public $primary_setting;
  84.  
  85.     /**
  86.      * Capability required to edit this partial.
  87.      *
  88.      * Normally this is empty and the capability is derived from the capabilities
  89.      * of the associated `$settings`.
  90.      *
  91.      * @since 4.5.0
  92.      * @var string
  93.      */
  94.     public $capability;
  95.  
  96.     /**
  97.      * Render callback.
  98.      *
  99.      * @since 4.5.0
  100.      * @see WP_Customize_Partial::render()
  101.      * @var callable Callback is called with one argument, the instance of
  102.      *                 WP_Customize_Partial. The callback can either echo the
  103.      *                 partial or return the partial as a string, or return false if error.
  104.      */
  105.     public $render_callback;
  106.  
  107.     /**
  108.      * Whether the container element is included in the partial, or if only the contents are rendered.
  109.      *
  110.      * @since 4.5.0
  111.      * @var bool
  112.      */
  113.     public $container_inclusive = false;
  114.  
  115.     /**
  116.      * Whether to refresh the entire preview in case a partial cannot be refreshed.
  117.      *
  118.      * A partial render is considered a failure if the render_callback returns false.
  119.      *
  120.      * @since 4.5.0
  121.      * @var bool
  122.      */
  123.     public $fallback_refresh = true;
  124.  
  125.     /**
  126.      * Constructor.
  127.      *
  128.      * Supplied `$args` override class property defaults.
  129.      *
  130.      * If `$args['settings']` is not defined, use the $id as the setting ID.
  131.      *
  132.      * @since 4.5.0
  133.      *
  134.      * @param WP_Customize_Selective_Refresh $component Customize Partial Refresh plugin instance.
  135.      * @param string                         $id        Control ID.
  136.      * @param array                          $args      {
  137.      *     Optional. Arguments to override class property defaults.
  138.      *
  139.      *     @type array|string $settings All settings IDs tied to the partial. If undefined, `$id` will be used.
  140.      * }
  141.      */
  142.     public function __construct( WP_Customize_Selective_Refresh $component, $id, $args = array() ) {
  143.         $keys = array_keys( get_object_vars( $this ) );
  144.         foreach ( $keys as $key ) {
  145.             if ( isset( $args[ $key ] ) ) {
  146.                 $this->$key = $args[ $key ];
  147.             }
  148.         }
  149.  
  150.         $this->component       = $component;
  151.         $this->id              = $id;
  152.         $this->id_data['keys'] = preg_split( '/\[/', str_replace( ']', '', $this->id ) );
  153.         $this->id_data['base'] = array_shift( $this->id_data['keys'] );
  154.  
  155.         if ( empty( $this->render_callback ) ) {
  156.             $this->render_callback = array( $this, 'render_callback' );
  157.         }
  158.  
  159.         // Process settings.
  160.         if ( ! isset( $this->settings ) ) {
  161.             $this->settings = array( $id );
  162.         } else if ( is_string( $this->settings ) ) {
  163.             $this->settings = array( $this->settings );
  164.         }
  165.  
  166.         if ( empty( $this->primary_setting ) ) {
  167.             $this->primary_setting = current( $this->settings );
  168.         }
  169.     }
  170.  
  171.     /**
  172.      * Retrieves parsed ID data for multidimensional setting.
  173.      *
  174.      * @since 4.5.0
  175.      *
  176.      * @return array {
  177.      *     ID data for multidimensional partial.
  178.      *
  179.      *     @type string $base ID base.
  180.      *     @type array  $keys Keys for multidimensional array.
  181.      * }
  182.      */
  183.     final public function id_data() {
  184.         return $this->id_data;
  185.     }
  186.  
  187.     /**
  188.      * Renders the template partial involving the associated settings.
  189.      *
  190.      * @since 4.5.0
  191.      *
  192.      * @param array $container_context Optional. Array of context data associated with the target container (placement).
  193.      *                                 Default empty array.
  194.      * @return string|array|false The rendered partial as a string, raw data array (for client-side JS template),
  195.      *                            or false if no render applied.
  196.      */
  197.     final public function render( $container_context = array() ) {
  198.         $partial  = $this;
  199.         $rendered = false;
  200.  
  201.         if ( ! empty( $this->render_callback ) ) {
  202.             ob_start();
  203.             $return_render = call_user_func( $this->render_callback, $this, $container_context );
  204.             $ob_render = ob_get_clean();
  205.  
  206.             if ( null !== $return_render && '' !== $ob_render ) {
  207.                 _doing_it_wrong( __FUNCTION__, __( 'Partial render must echo the content or return the content string (or array), but not both.' ), '4.5.0' );
  208.             }
  209.  
  210.             /*
  211.              * Note that the string return takes precedence because the $ob_render may just\
  212.              * include PHP warnings or notices.
  213.              */
  214.             $rendered = null !== $return_render ? $return_render : $ob_render;
  215.         }
  216.  
  217.         /**
  218.          * Filters partial rendering.
  219.          *
  220.          * @since 4.5.0
  221.          *
  222.          * @param string|array|false   $rendered          The partial value. Default false.
  223.          * @param WP_Customize_Partial $partial           WP_Customize_Setting instance.
  224.          * @param array                $container_context Optional array of context data associated with
  225.          *                                                the target container.
  226.          */
  227.         $rendered = apply_filters( 'customize_partial_render', $rendered, $partial, $container_context );
  228.  
  229.         /**
  230.          * Filters partial rendering for a specific partial.
  231.          *
  232.          * The dynamic portion of the hook name, `$partial->ID` refers to the partial ID.
  233.          *
  234.          * @since 4.5.0
  235.          *
  236.          * @param string|array|false   $rendered          The partial value. Default false.
  237.          * @param WP_Customize_Partial $partial           WP_Customize_Setting instance.
  238.          * @param array                $container_context Optional array of context data associated with
  239.          *                                                the target container.
  240.          */
  241.         $rendered = apply_filters( "customize_partial_render_{$partial->id}", $rendered, $partial, $container_context );
  242.  
  243.         return $rendered;
  244.     }
  245.  
  246.     /**
  247.      * Default callback used when invoking WP_Customize_Control::render().
  248.      *
  249.      * Note that this method may echo the partial *or* return the partial as
  250.      * a string or array, but not both. Output buffering is performed when this
  251.      * is called. Subclasses can override this with their specific logic, or they
  252.      * may provide an 'render_callback' argument to the constructor.
  253.      *
  254.      * This method may return an HTML string for straight DOM injection, or it
  255.      * may return an array for supporting Partial JS subclasses to render by
  256.      * applying to client-side templating.
  257.      *
  258.      * @since 4.5.0
  259.      *
  260.      * @param WP_Customize_Partial $partial Partial.
  261.      * @param array                $context Context.
  262.      * @return string|array|false
  263.      */
  264.     public function render_callback( WP_Customize_Partial $partial, $context = array() ) {
  265.         unset( $partial, $context );
  266.         return false;
  267.     }
  268.  
  269.     /**
  270.      * Retrieves the data to export to the client via JSON.
  271.      *
  272.      * @since 4.5.0
  273.      *
  274.      * @return array Array of parameters passed to the JavaScript.
  275.      */
  276.     public function json() {
  277.         $exports = array(
  278.             'settings'           => $this->settings,
  279.             'primarySetting'     => $this->primary_setting,
  280.             'selector'           => $this->selector,
  281.             'type'               => $this->type,
  282.             'fallbackRefresh'    => $this->fallback_refresh,
  283.             'containerInclusive' => $this->container_inclusive,
  284.         );
  285.         return $exports;
  286.     }
  287.  
  288.     /**
  289.      * Checks if the user can refresh this partial.
  290.      *
  291.      * Returns false if the user cannot manipulate one of the associated settings,
  292.      * or if one of the associated settings does not exist.
  293.      *
  294.      * @since 4.5.0
  295.      *
  296.      * @return bool False if user can't edit one of the related settings,
  297.      *                    or if one of the associated settings does not exist.
  298.      */
  299.     final public function check_capabilities() {
  300.         if ( ! empty( $this->capability ) && ! current_user_can( $this->capability ) ) {
  301.             return false;
  302.         }
  303.         foreach ( $this->settings as $setting_id ) {
  304.             $setting = $this->component->manager->get_setting( $setting_id );
  305.             if ( ! $setting || ! $setting->check_capabilities() ) {
  306.                 return false;
  307.             }
  308.         }
  309.         return true;
  310.     }
  311. }
  312.