field.php (18273B)
1 <?php 2 /** 3 * The field base class. 4 * This is the parent class of all custom fields defined by the plugin, which defines all the common methods. 5 * Fields must inherit this class and overwrite methods with its own. 6 * 7 * @package Meta Box 8 */ 9 10 /** 11 * The field base class. 12 */ 13 abstract class RWMB_Field { 14 /** 15 * Add actions. 16 */ 17 public static function add_actions() { 18 } 19 20 /** 21 * Enqueue scripts and styles. 22 */ 23 public static function admin_enqueue_scripts() { 24 } 25 26 /** 27 * Show field HTML 28 * Filters are put inside this method, not inside methods such as "meta", "html", "begin_html", etc. 29 * That ensures the returned value are always been applied filters. 30 * This method is not meant to be overwritten in specific fields. 31 * 32 * @param array $field Field parameters. 33 * @param bool $saved Whether the meta box is saved at least once. 34 * @param int $post_id Post ID. 35 */ 36 public static function show( $field, $saved, $post_id = 0 ) { 37 $meta = self::call( $field, 'meta', $post_id, $saved ); 38 $meta = self::filter( 'field_meta', $meta, $field, $saved ); 39 40 $begin = self::call( $field, 'begin_html', $meta ); 41 $begin = self::filter( 'begin_html', $begin, $field, $meta ); 42 43 // Separate code for cloneable and non-cloneable fields to make easy to maintain. 44 if ( $field['clone'] ) { 45 $field_html = RWMB_Clone::html( $meta, $field ); 46 } else { 47 // Call separated methods for displaying each type of field. 48 $field_html = self::call( $field, 'html', $meta ); 49 $field_html = self::filter( 'html', $field_html, $field, $meta ); 50 } 51 52 $end = self::call( $field, 'end_html', $meta ); 53 $end = self::filter( 'end_html', $end, $field, $meta ); 54 55 $html = self::filter( 'wrapper_html', "$begin$field_html$end", $field, $meta ); 56 57 // Display label and input in DIV and allow user-defined classes to be appended. 58 $classes = "rwmb-field rwmb-{$field['type']}-wrapper " . $field['class']; 59 if ( ! empty( $field['required'] ) ) { 60 $classes .= ' required'; 61 } 62 63 $outer_html = sprintf( 64 $field['before'] . '<div class="%s">%s</div>' . $field['after'], 65 esc_attr( trim( $classes ) ), 66 $html 67 ); 68 $outer_html = self::filter( 'outer_html', $outer_html, $field, $meta ); 69 70 echo $outer_html; // WPCS: XSS OK. 71 } 72 73 /** 74 * Get field HTML. 75 * 76 * @param mixed $meta Meta value. 77 * @param array $field Field parameters. 78 * 79 * @return string 80 */ 81 public static function html( $meta, $field ) { 82 return ''; 83 } 84 85 /** 86 * Show begin HTML markup for fields. 87 * 88 * @param mixed $meta Meta value. 89 * @param array $field Field parameters. 90 * 91 * @return string 92 */ 93 public static function begin_html( $meta, $field ) { 94 $field_label = ''; 95 if ( $field['name'] ) { 96 $field_label = sprintf( 97 '<div class="rwmb-label"> 98 <label for="%s">%s%s</label> 99 %s 100 </div>', 101 esc_attr( $field['id'] ), 102 $field['name'], 103 $field['required'] || ! empty( $field['attributes']['required'] ) ? '<span class="rwmb-required">*</span>' : '', 104 self::label_description( $field ) 105 ); 106 } 107 108 $data_max_clone = is_numeric( $field['max_clone'] ) && $field['max_clone'] > 1 ? ' data-max-clone=' . $field['max_clone'] : ''; 109 110 $input_open = sprintf( 111 '<div class="rwmb-input"%s>', 112 $data_max_clone 113 ); 114 115 return $field_label . $input_open; 116 } 117 118 /** 119 * Show end HTML markup for fields. 120 * 121 * @param mixed $meta Meta value. 122 * @param array $field Field parameters. 123 * 124 * @return string 125 */ 126 public static function end_html( $meta, $field ) { 127 return RWMB_Clone::add_clone_button( $field ) . self::call( 'input_description', $field ) . '</div>'; 128 } 129 130 /** 131 * Display field label description. 132 * 133 * @param array $field Field parameters. 134 * @return string 135 */ 136 protected static function label_description( $field ) { 137 $id = $field['id'] ? ' id="' . esc_attr( $field['id'] ) . '-label-description"' : ''; 138 return $field['label_description'] ? "<p{$id} class='description'>{$field['label_description']}</p>" : ''; 139 } 140 141 /** 142 * Display field description. 143 * 144 * @param array $field Field parameters. 145 * @return string 146 */ 147 protected static function input_description( $field ) { 148 $id = $field['id'] ? ' id="' . esc_attr( $field['id'] ) . '-description"' : ''; 149 return $field['desc'] ? "<p{$id} class='description'>{$field['desc']}</p>" : ''; 150 } 151 152 /** 153 * Get raw meta value. 154 * 155 * @param int $object_id Object ID. 156 * @param array $field Field parameters. 157 * @param array $args Arguments of {@see rwmb_meta()} helper. 158 * 159 * @return mixed 160 */ 161 public static function raw_meta( $object_id, $field, $args = array() ) { 162 if ( empty( $field['id'] ) ) { 163 return ''; 164 } 165 166 if ( isset( $field['storage'] ) ) { 167 $storage = $field['storage']; 168 } elseif ( isset( $args['object_type'] ) ) { 169 $storage = rwmb_get_storage( $args['object_type'] ); 170 } else { 171 $storage = rwmb_get_storage( 'post' ); 172 } 173 174 if ( ! isset( $args['single'] ) ) { 175 $args['single'] = $field['clone'] || ! $field['multiple']; 176 } 177 178 if ( $field['clone'] && $field['clone_as_multiple'] ) { 179 $args['single'] = false; 180 } 181 182 $value = $storage->get( $object_id, $field['id'], $args ); 183 $value = self::filter( 'raw_meta', $value, $field, $object_id, $args ); 184 return $value; 185 } 186 187 /** 188 * Get meta value. 189 * 190 * @param int $post_id Post ID. 191 * @param bool $saved Whether the meta box is saved at least once. 192 * @param array $field Field parameters. 193 * 194 * @return mixed 195 */ 196 public static function meta( $post_id, $saved, $field ) { 197 /** 198 * For special fields like 'divider', 'heading' which don't have ID, just return empty string 199 * to prevent notice error when displaying fields. 200 */ 201 if ( empty( $field['id'] ) ) { 202 return ''; 203 } 204 205 // Get raw meta. 206 $meta = self::call( $field, 'raw_meta', $post_id ); 207 208 // Use $field['std'] only when the meta box hasn't been saved (i.e. the first time we run). 209 $meta = ! $saved || ! $field['save_field'] ? $field['std'] : $meta; 210 211 if ( $field['clone'] ) { 212 $meta = RWMB_Helpers_Array::ensure( $meta ); 213 214 // Ensure $meta is an array with values so that the foreach loop in self::show() runs properly. 215 if ( empty( $meta ) ) { 216 $meta = array( '' ); 217 } 218 219 if ( $field['multiple'] ) { 220 $first = reset( $meta ); 221 222 // If users set std for a cloneable checkbox list field in the Builder, they can only set [value1, value2]. We need to transform it to [[value1, value2]]. 223 // In other cases, make sure each value is an array. 224 $meta = is_array( $first ) ? array_map( 'RWMB_Helpers_Array::ensure', $meta ) : array( $meta ); 225 } 226 } elseif ( $field['multiple'] ) { 227 $meta = RWMB_Helpers_Array::ensure( $meta ); 228 } 229 230 // Escape attributes. 231 $meta = self::call( $field, 'esc_meta', $meta ); 232 233 return $meta; 234 } 235 236 /** 237 * Escape meta for field output. 238 * 239 * @param mixed $meta Meta value. 240 * 241 * @return mixed 242 */ 243 public static function esc_meta( $meta ) { 244 return is_array( $meta ) ? array_map( __METHOD__, $meta ) : esc_attr( $meta ); 245 } 246 247 /** 248 * Process the submitted value before saving into the database. 249 * 250 * @param mixed $value The submitted value. 251 * @param int $object_id The object ID. 252 * @param array $field The field settings. 253 */ 254 public static function process_value( $value, $object_id, $field ) { 255 $old_value = self::call( $field, 'raw_meta', $object_id ); 256 257 // Allow field class change the value. 258 if ( $field['clone'] ) { 259 $value = RWMB_Clone::value( $value, $old_value, $object_id, $field ); 260 } else { 261 $value = self::call( $field, 'value', $value, $old_value, $object_id ); 262 $value = self::filter( 'sanitize', $value, $field, $old_value, $object_id ); 263 } 264 $value = self::filter( 'value', $value, $field, $old_value, $object_id ); 265 266 return $value; 267 } 268 269 /** 270 * Set value of meta before saving into database. 271 * 272 * @param mixed $new The submitted meta value. 273 * @param mixed $old The existing meta value. 274 * @param int $post_id The post ID. 275 * @param array $field The field parameters. 276 * 277 * @return mixed 278 */ 279 public static function value( $new, $old, $post_id, $field ) { 280 return $new; 281 } 282 283 /** 284 * Save meta value. 285 * 286 * @param mixed $new The submitted meta value. 287 * @param mixed $old The existing meta value. 288 * @param int $post_id The post ID. 289 * @param array $field The field parameters. 290 */ 291 public static function save( $new, $old, $post_id, $field ) { 292 if ( empty( $field['id'] ) || ! $field['save_field'] ) { 293 return; 294 } 295 $name = $field['id']; 296 $storage = $field['storage']; 297 298 // Remove post meta if it's empty. 299 if ( ! RWMB_Helpers_Value::is_valid_for_field( $new ) ) { 300 $storage->delete( $post_id, $name ); 301 return; 302 } 303 304 // If field is cloneable AND not force to save as multiple rows, value is saved as a single row in the database. 305 if ( $field['clone'] && ! $field['clone_as_multiple'] ) { 306 $storage->update( $post_id, $name, $new ); 307 return; 308 } 309 310 // Save cloned fields as multiple values instead serialized array. 311 if ( ( $field['clone'] && $field['clone_as_multiple'] ) || $field['multiple'] ) { 312 $storage->delete( $post_id, $name ); 313 $new = (array) $new; 314 foreach ( $new as $new_value ) { 315 $storage->add( $post_id, $name, $new_value, false ); 316 } 317 return; 318 } 319 320 // Default: just update post meta. 321 $storage->update( $post_id, $name, $new ); 322 } 323 324 /** 325 * Normalize parameters for field. 326 * 327 * @param array|string $field Field settings. 328 * @return array 329 */ 330 public static function normalize( $field ) { 331 // Quick define text fields with "name" attribute only. 332 if ( is_string( $field ) ) { 333 $field = array( 334 'name' => $field, 335 'id' => sanitize_key( $field ), 336 ); 337 } 338 $field = wp_parse_args( 339 $field, 340 array( 341 'id' => '', 342 'name' => '', 343 'type' => 'text', 344 'label_description' => '', 345 'multiple' => false, 346 'std' => '', 347 'desc' => '', 348 'format' => '', 349 'before' => '', 350 'after' => '', 351 'field_name' => isset( $field['id'] ) ? $field['id'] : '', 352 'placeholder' => '', 353 'save_field' => true, 354 355 'clone' => false, 356 'max_clone' => 0, 357 'sort_clone' => false, 358 'add_button' => __( '+ Add more', 'meta-box' ), 359 'clone_default' => false, 360 'clone_as_multiple' => false, 361 362 'class' => '', 363 'disabled' => false, 364 'required' => false, 365 'autofocus' => false, 366 'attributes' => array(), 367 368 'sanitize_callback' => null, 369 ) 370 ); 371 372 // Store the original ID to run correct filters for the clonable field. 373 if ( $field['clone'] ) { 374 $field['_original_id'] = $field['id']; 375 } 376 377 if ( $field['clone_default'] ) { 378 $field['attributes'] = wp_parse_args( 379 $field['attributes'], 380 array( 381 'data-default' => $field['std'], 382 'data-clone-default' => 'true', 383 ) 384 ); 385 } 386 387 if ( 1 === $field['max_clone'] ) { 388 $field['clone'] = false; 389 } 390 391 return $field; 392 } 393 394 /** 395 * Get the attributes for a field. 396 * 397 * @param array $field Field parameters. 398 * @param mixed $value Meta value. 399 * 400 * @return array 401 */ 402 public static function get_attributes( $field, $value = null ) { 403 $attributes = wp_parse_args( 404 $field['attributes'], 405 array( 406 'disabled' => $field['disabled'], 407 'autofocus' => $field['autofocus'], 408 'required' => $field['required'], 409 'id' => $field['id'], 410 'class' => '', 411 'name' => $field['field_name'], 412 ) 413 ); 414 415 $attributes['class'] = trim( implode( ' ', array_merge( array( "rwmb-{$field['type']}" ), (array) $attributes['class'] ) ) ); 416 417 return $attributes; 418 } 419 420 /** 421 * Renders an attribute array into an html attributes string. 422 * 423 * @param array $attributes HTML attributes. 424 * 425 * @return string 426 */ 427 public static function render_attributes( $attributes ) { 428 $output = ''; 429 430 $attributes = array_filter( $attributes, 'RWMB_Helpers_Value::is_valid_for_attribute' ); 431 foreach ( $attributes as $key => $value ) { 432 if ( is_array( $value ) ) { 433 $value = wp_json_encode( $value ); 434 } 435 436 $output .= sprintf( ' %s="%s"', $key, esc_attr( $value ) ); 437 } 438 439 return $output; 440 } 441 442 /** 443 * Get the field value. 444 * The difference between this function and 'meta' function is 'meta' function always returns the escaped value 445 * of the field saved in the database, while this function returns more meaningful value of the field, for ex.: 446 * for file/image: return array of file/image information instead of file/image IDs. 447 * 448 * Each field can extend this function and add more data to the returned value. 449 * See specific field classes for details. 450 * 451 * @param array $field Field parameters. 452 * @param array $args Additional arguments. Rarely used. See specific fields for details. 453 * @param int|null $post_id Post ID. null for current post. Optional. 454 * 455 * @return mixed Field value 456 */ 457 public static function get_value( $field, $args = array(), $post_id = null ) { 458 // Some fields does not have ID like heading, custom HTML, etc. 459 if ( empty( $field['id'] ) ) { 460 return ''; 461 } 462 463 if ( ! $post_id ) { 464 $post_id = get_the_ID(); 465 } 466 467 // Get raw meta value in the database, no escape. 468 $value = self::call( $field, 'raw_meta', $post_id, $args ); 469 470 // Make sure meta value is an array for cloneable and multiple fields. 471 if ( $field['clone'] || $field['multiple'] ) { 472 $value = is_array( $value ) && $value ? $value : array(); 473 } 474 475 return $value; 476 } 477 478 /** 479 * Output the field value. 480 * Depends on field value and field types, each field can extend this method to output its value in its own way 481 * See specific field classes for details. 482 * 483 * Note: we don't echo the field value directly. We return the output HTML of field, which will be used in 484 * rwmb_the_field function later. 485 * 486 * @use self::get_value() 487 * @see rwmb_the_value() 488 * 489 * @param array $field Field parameters. 490 * @param array $args Additional arguments. Rarely used. See specific fields for details. 491 * @param int|null $post_id Post ID. null for current post. Optional. 492 * 493 * @return string HTML output of the field 494 */ 495 public static function the_value( $field, $args = array(), $post_id = null ) { 496 $value = self::call( 'get_value', $field, $args, $post_id ); 497 498 if ( false === $value ) { 499 return ''; 500 } 501 502 return self::call( 'format_value', $field, $value, $args, $post_id ); 503 } 504 505 /** 506 * Format value for the helper functions. 507 * 508 * @param array $field Field parameters. 509 * @param string|array $value The field meta value. 510 * @param array $args Additional arguments. Rarely used. See specific fields for details. 511 * @param int|null $post_id Post ID. null for current post. Optional. 512 * 513 * @return string 514 */ 515 public static function format_value( $field, $value, $args, $post_id ) { 516 if ( ! $field['clone'] ) { 517 return self::call( 'format_clone_value', $field, $value, $args, $post_id ); 518 } 519 $output = '<ul>'; 520 foreach ( $value as $clone ) { 521 $output .= '<li>' . self::call( 'format_clone_value', $field, $clone, $args, $post_id ) . '</li>'; 522 } 523 $output .= '</ul>'; 524 return $output; 525 } 526 527 /** 528 * Format value for a clone. 529 * 530 * @param array $field Field parameters. 531 * @param string|array $value The field meta value. 532 * @param array $args Additional arguments. Rarely used. See specific fields for details. 533 * @param int|null $post_id Post ID. null for current post. Optional. 534 * 535 * @return string 536 */ 537 public static function format_clone_value( $field, $value, $args, $post_id ) { 538 if ( ! $field['multiple'] ) { 539 return self::call( 'format_single_value', $field, $value, $args, $post_id ); 540 } 541 $output = '<ul>'; 542 foreach ( $value as $single ) { 543 $output .= '<li>' . self::call( 'format_single_value', $field, $single, $args, $post_id ) . '</li>'; 544 } 545 $output .= '</ul>'; 546 return $output; 547 } 548 549 /** 550 * Format a single value for the helper functions. Sub-fields should overwrite this method if necessary. 551 * 552 * @param array $field Field parameters. 553 * @param string $value The value. 554 * @param array $args Additional arguments. Rarely used. See specific fields for details. 555 * @param int|null $post_id Post ID. null for current post. Optional. 556 * 557 * @return string 558 */ 559 public static function format_single_value( $field, $value, $args, $post_id ) { 560 return $value; 561 } 562 563 /** 564 * Call a method of a field. 565 * This should be replaced by static::$method( $args ) in PHP 5.3. 566 * 567 * @return mixed 568 */ 569 public static function call() { 570 $args = func_get_args(); 571 572 $check = reset( $args ); 573 574 // Params: method name, field, other params. 575 if ( is_string( $check ) ) { 576 $method = array_shift( $args ); 577 $field = reset( $args ); // Keep field as 1st param. 578 } else { 579 $field = array_shift( $args ); 580 $method = array_shift( $args ); 581 582 if ( 'raw_meta' === $method ) { 583 // Add field param after object id. 584 array_splice( $args, 1, 0, array( $field ) ); 585 } else { 586 $args[] = $field; // Add field as last param. 587 } 588 } 589 590 return call_user_func_array( array( RWMB_Helpers_Field::get_class( $field ), $method ), $args ); 591 } 592 593 /** 594 * Apply various filters based on field type, id. 595 * Filters: 596 * - rwmb_{$name} 597 * - rwmb_{$field['type']}_{$name} 598 * - rwmb_{$field['id']}_{$name} 599 * 600 * @return mixed 601 */ 602 public static function filter() { 603 $args = func_get_args(); 604 605 // 3 first params must be: filter name, value, field. Other params will be used for filters. 606 $name = array_shift( $args ); 607 $value = array_shift( $args ); 608 $field = array_shift( $args ); 609 610 // List of filters. 611 $filters = array( 612 'rwmb_' . $name, 613 'rwmb_' . $field['type'] . '_' . $name, 614 ); 615 if ( $field['id'] ) { 616 $field_id = $field['clone'] ? $field['_original_id'] : $field['id']; 617 $filters[] = 'rwmb_' . $field_id . '_' . $name; 618 } 619 620 // Filter params: value, field, other params. Note: value is changed after each run. 621 array_unshift( $args, $field ); 622 foreach ( $filters as $filter ) { 623 $filter_args = $args; 624 array_unshift( $filter_args, $value ); 625 $value = apply_filters_ref_array( $filter, $filter_args ); 626 } 627 628 return $value; 629 } 630 }