WP_Customize_Partial

Core Customizer class for implementing selective refresh partials.

Defined (1)

The class is defined in the following location(s).

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