BP_XProfile_Field_Type

Represents a type of XProfile field and holds meta information about the type of value that it accepts.

Defined (1)

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

/bp-xprofile/classes/class-bp-xprofile-field-type.php  
  1. abstract class BP_XProfile_Field_Type { 
  2.  
  3. /** 
  4. * Validation regex rules for field type. 
  5. * @since 2.0.0 
  6. * @var array Field type validation regexes. 
  7. */ 
  8. protected $validation_regex = array(); 
  9.  
  10. /** 
  11. * Whitelisted values for field type. 
  12. * @since 2.0.0 
  13. * @var array Field type whitelisted values. 
  14. */ 
  15. protected $validation_whitelist = array(); 
  16.  
  17. /** 
  18. * Name for field type. 
  19. * @since 2.0.0 
  20. * @var string The name of this field type. 
  21. */ 
  22. public $name = ''; 
  23.  
  24. /** 
  25. * The name of the category that this field type should be grouped with. Used on the [Users > Profile Fields] screen in wp-admin. 
  26. * @since 2.0.0 
  27. * @var string 
  28. */ 
  29. public $category = ''; 
  30.  
  31. /** 
  32. * If allowed to store null/empty values. 
  33. * @since 2.0.0 
  34. * @var bool If this is set, allow BP to store null/empty values for this field type. 
  35. */ 
  36. public $accepts_null_value = false; 
  37.  
  38. /** 
  39. * If this is set, BP will set this field type's validation whitelist from the field's options (e.g checkbox, selectbox). 
  40. * @since 2.0.0 
  41. * @var bool Does this field support options? e.g. selectbox, radio buttons, etc. 
  42. */ 
  43. public $supports_options = false; 
  44.  
  45. /** 
  46. * If allowed to support multiple options as default. 
  47. * @since 2.0.0 
  48. * @var bool Does this field type support multiple options being set as default values? e.g. multiselectbox, checkbox. 
  49. */ 
  50. public $supports_multiple_defaults = false; 
  51.  
  52. /** 
  53. * If the field type supports rich text by default. 
  54. * @since 2.4.0 
  55. * @var bool 
  56. */ 
  57. public $supports_richtext = false; 
  58.  
  59. /** 
  60. * If the field type has a type-specific settings section on the Edit Field panel. 
  61. * @since 2.7.0 
  62. * @var bool|null Boolean if set explicitly by the type object, otherwise null. 
  63. */ 
  64. protected $do_settings_section = null; 
  65.  
  66. /** 
  67. * If object is created by an BP_XProfile_Field object. 
  68. * @since 2.0.0 
  69. * @var BP_XProfile_Field If this object is created by instantiating a {@link BP_XProfile_Field},  
  70. * this is a reference back to that object. 
  71. */ 
  72. public $field_obj = null; 
  73.  
  74. /** 
  75. * Constructor. 
  76. * @since 2.0.0 
  77. */ 
  78. public function __construct() { 
  79.  
  80. /** 
  81. * Fires inside __construct() method for BP_XProfile_Field_Type class. 
  82. * @since 2.0.0 
  83. * @param BP_XProfile_Field_Type $this Current instance of 
  84. * the field type class. 
  85. */ 
  86. do_action( 'bp_xprofile_field_type', $this ); 
  87.  
  88. /** 
  89. * Set a regex that profile data will be asserted against. 
  90. * You can call this method multiple times to set multiple formats. When validation is performed,  
  91. * it's successful as long as the new value matches any one of the registered formats. 
  92. * @since 2.0.0 
  93. * @param string $format Regex string. 
  94. * @param string $replace_format Optional; if 'replace', replaces the format instead of adding to it. 
  95. * Defaults to 'add'. 
  96. * @return BP_XProfile_Field_Type 
  97. */ 
  98. public function set_format( $format, $replace_format = 'add' ) { 
  99.  
  100. /** 
  101. * Filters the regex format for the field type. 
  102. * @since 2.0.0 
  103. * @param string $format Regex string. 
  104. * @param string $replace_format Optional replace format If "replace", replaces the 
  105. * format instead of adding to it. Defaults to "add". 
  106. * @param BP_XProfile_Field_Type $this Current instance of the BP_XProfile_Field_Type class. 
  107. */ 
  108. $format = apply_filters( 'bp_xprofile_field_type_set_format', $format, $replace_format, $this ); 
  109.  
  110. if ( 'add' === $replace_format ) { 
  111. $this->validation_regex[] = $format; 
  112. } elseif ( 'replace' === $replace_format ) { 
  113. $this->validation_regex = array( $format ); 
  114.  
  115. return $this; 
  116.  
  117. /** 
  118. * Add a value to this type's whitelist that profile data will be asserted against. 
  119. * You can call this method multiple times to set multiple formats. When validation is performed,  
  120. * it's successful as long as the new value matches any one of the registered formats. 
  121. * @since 2.0.0 
  122. * @param string|array $values Whitelisted values. 
  123. * @return BP_XProfile_Field_Type 
  124. */ 
  125. public function set_whitelist_values( $values ) { 
  126. foreach ( (array) $values as $value ) { 
  127.  
  128. /** 
  129. * Filters values for field type's whitelist that profile data will be asserted against. 
  130. * @since 2.0.0 
  131. * @param string $value Field value. 
  132. * @param array $values Original array of values. 
  133. * @param BP_XProfile_Field_Type $this Current instance of the BP_XProfile_Field_Type class. 
  134. */ 
  135. $this->validation_whitelist[] = apply_filters( 'bp_xprofile_field_type_set_whitelist_values', $value, $values, $this ); 
  136.  
  137. return $this; 
  138.  
  139. /** 
  140. * Check the given string against the registered formats for this field type. 
  141. * This method doesn't support chaining. 
  142. * @since 2.0.0 
  143. * @param string|array $values Value to check against the registered formats. 
  144. * @return bool True if the value validates 
  145. */ 
  146. public function is_valid( $values ) { 
  147. $validated = false; 
  148.  
  149. // Some types of field (e.g. multi-selectbox) may have multiple values to check. 
  150. foreach ( (array) $values as $value ) { 
  151.  
  152. // Validate the $value against the type's accepted format(s). 
  153. foreach ( $this->validation_regex as $format ) { 
  154. if ( 1 === preg_match( $format, $value ) ) { 
  155. $validated = true; 
  156. continue; 
  157.  
  158. } else { 
  159. $validated = false; 
  160.  
  161. // Handle field types with accepts_null_value set if $values is an empty array. 
  162. if ( ( false === $validated ) && is_array( $values ) && empty( $values ) && $this->accepts_null_value ) { 
  163. $validated = true; 
  164.  
  165. // If there's a whitelist set, make sure that each value is a whitelisted value. 
  166. if ( ( true === $validated ) && ! empty( $values ) && ! empty( $this->validation_whitelist ) ) { 
  167. foreach ( (array) $values as $value ) { 
  168. if ( ! in_array( $value, $this->validation_whitelist, true ) ) { 
  169. $validated = false; 
  170. break; 
  171.  
  172. /** 
  173. * Filters whether or not field type is a valid format. 
  174. * @since 2.0.0 
  175. * @param bool $validated Whether or not the field type is valid. 
  176. * @param string|array $values Value to check against the registered formats. 
  177. * @param BP_XProfile_Field_Type $this Current instance of the BP_XProfile_Field_Type class. 
  178. */ 
  179. return (bool) apply_filters( 'bp_xprofile_field_type_is_valid', $validated, $values, $this ); 
  180.  
  181. /** 
  182. * Check whether the current field type should have a settings ("options") section on the Edit Field panel. 
  183. * Falls back on `supports_options` if no value is set by the field type. 
  184. * @since 2.7.0 
  185. * @return bool 
  186. */ 
  187. public function do_settings_section() { 
  188. if ( null === $this->do_settings_section ) { 
  189. $this->do_settings_section = $this->supports_options; 
  190.  
  191. return (bool) $this->do_settings_section; 
  192.  
  193. /** 
  194. * Output the edit field HTML for this field type. 
  195. * Must be used inside the {@link bp_profile_fields()} template loop. 
  196. * @since 2.0.0 
  197. * @param array $raw_properties Optional key/value array of permitted attributes that you want to add. 
  198. * @return void 
  199. */ 
  200. abstract public function edit_field_html( array $raw_properties = array() ); 
  201.  
  202. /** 
  203. * Output HTML for this field type on the wp-admin Profile Fields screen. 
  204. * Must be used inside the {@link bp_profile_fields()} template loop. 
  205. * @since 2.0.0 
  206. * @param array $raw_properties Optional key/value array of permitted attributes that you want to add. 
  207. * @return void 
  208. */ 
  209. abstract public function admin_field_html( array $raw_properties = array() ); 
  210.  
  211. /** 
  212. * Output the edit field options HTML for this field type. 
  213. * BuddyPress considers a field's "options" to be, for example, the items in a selectbox. 
  214. * These are stored separately in the database, and their templating is handled separately. 
  215. * Populate this method in a child class if it's required. Otherwise, you can leave it out. 
  216. * This templating is separate from {@link BP_XProfile_Field_Type::edit_field_html()} because 
  217. * it's also used in the wp-admin screens when creating new fields, and for backwards compatibility. 
  218. * Must be used inside the {@link bp_profile_fields()} template loop. 
  219. * @since 2.0.0 
  220. * @param array $args Optional. The arguments passed to {@link bp_the_profile_field_options()}. 
  221. */ 
  222. public function edit_field_options_html( array $args = array() ) {} 
  223.  
  224. /** 
  225. * Output HTML for this field type's children options on the wp-admin Profile Fields "Add Field" and "Edit Field" screens. 
  226. * You don't need to implement this method for all field types. It's used in core by the 
  227. * selectbox, multi selectbox, checkbox, and radio button fields, to allow the admin to 
  228. * enter the child option values (e.g. the choices in a select box). 
  229. * Must be used inside the {@link bp_profile_fields()} template loop. 
  230. * @since 2.0.0 
  231. * @param BP_XProfile_Field $current_field The current profile field on the add/edit screen. 
  232. * @param string $control_type Optional. HTML input type used to render the current 
  233. * field's child options. 
  234. */ 
  235. public function admin_new_field_html( BP_XProfile_Field $current_field, $control_type = '' ) { 
  236. $type = array_search( get_class( $this ), bp_xprofile_get_field_types() ); 
  237. if ( false === $type ) { 
  238. return; 
  239.  
  240. $class = $current_field->type != $type ? 'display: none;' : ''; 
  241. $current_type_obj = bp_xprofile_create_field_type( $type ); 
  242. ?> 
  243.  
  244. <div id="<?php echo esc_attr( $type ); ?>" class="postbox bp-options-box" style="<?php echo esc_attr( $class ); ?> margin-top: 15px;"> 
  245. <h3><?php esc_html_e( 'Please enter options for this Field:', 'buddypress' ); ?></h3> 
  246. <div class="inside" aria-live="polite" aria-atomic="true" aria-relevant="all"> 
  247. <p> 
  248. <label for="sort_order_<?php echo esc_attr( $type ); ?>"><?php esc_html_e( 'Sort Order:', 'buddypress' ); ?></label> 
  249. <select name="sort_order_<?php echo esc_attr( $type ); ?>" id="sort_order_<?php echo esc_attr( $type ); ?>" > 
  250. <option value="custom" <?php selected( 'custom', $current_field->order_by ); ?>><?php esc_html_e( 'Custom', 'buddypress' ); ?></option> 
  251. <option value="asc" <?php selected( 'asc', $current_field->order_by ); ?>><?php esc_html_e( 'Ascending', 'buddypress' ); ?></option> 
  252. <option value="desc" <?php selected( 'desc', $current_field->order_by ); ?>><?php esc_html_e( 'Descending', 'buddypress' ); ?></option> 
  253. </select> 
  254. </p> 
  255.  
  256. <?php 
  257.  
  258. // Does option have children? 
  259. $options = $current_field->get_children( true ); 
  260.  
  261. // If no children options exists for this field, check in $_POST 
  262. // for a submitted form (e.g. on the "new field" screen). 
  263. if ( empty( $options ) ) { 
  264.  
  265. $options = array(); 
  266. $i = 1; 
  267.  
  268. while ( isset( $_POST[$type . '_option'][$i] ) ) { 
  269.  
  270. // Multiselectbox and checkboxes support MULTIPLE default options; all other core types support only ONE. 
  271. if ( $current_type_obj->supports_options && ! $current_type_obj->supports_multiple_defaults && isset( $_POST["isDefault_{$type}_option"][$i] ) && (int) $_POST["isDefault_{$type}_option"] === $i ) { 
  272. $is_default_option = true; 
  273. } elseif ( isset( $_POST["isDefault_{$type}_option"][$i] ) ) { 
  274. $is_default_option = (bool) $_POST["isDefault_{$type}_option"][$i]; 
  275. } else { 
  276. $is_default_option = false; 
  277.  
  278. // Grab the values from $_POST to use as the form's options. 
  279. $options[] = (object) array( 
  280. 'id' => -1,  
  281. 'is_default_option' => $is_default_option,  
  282. 'name' => sanitize_text_field( stripslashes( $_POST[$type . '_option'][$i] ) ),  
  283. ); 
  284.  
  285. ++$i; 
  286.  
  287. // If there are still no children options set, this must be the "new field" screen, so add one new/empty option. 
  288. if ( empty( $options ) ) { 
  289. $options[] = (object) array( 
  290. 'id' => -1,  
  291. 'is_default_option' => false,  
  292. 'name' => '',  
  293. ); 
  294.  
  295. // Render the markup for the children options. 
  296. if ( ! empty( $options ) ) { 
  297. $default_name = ''; 
  298.  
  299. for ( $i = 0, $count = count( $options ); $i < $count; ++$i ) : 
  300. $j = $i + 1; 
  301.  
  302. // Multiselectbox and checkboxes support MULTIPLE default options; all other core types support only ONE. 
  303. if ( $current_type_obj->supports_options && $current_type_obj->supports_multiple_defaults ) { 
  304. $default_name = '[' . $j . ']'; 
  305. ?> 
  306.  
  307. <div id="<?php echo esc_attr( "{$type}_div{$j}" ); ?>" class="bp-option sortable"> 
  308. <span class="bp-option-icon grabber"></span> 
  309. <label for="<?php echo esc_attr( "{$type}_option{$j}" ); ?>" class="screen-reader-text"><?php 
  310. /** translators: accessibility text */ 
  311. esc_html_e( 'Add an option', 'buddypress' ); 
  312. ?></label> 
  313. <input type="text" name="<?php echo esc_attr( "{$type}_option[{$j}]" ); ?>" id="<?php echo esc_attr( "{$type}_option{$j}" ); ?>" value="<?php echo esc_attr( stripslashes( $options[$i]->name ) ); ?>" /> 
  314. <label for="<?php echo esc_attr( "{$type}_option{$default_name}" ); ?>"> 
  315. <input type="<?php echo esc_attr( $control_type ); ?>" id="<?php echo esc_attr( "{$type}_option{$default_name}" ); ?>" name="<?php echo esc_attr( "isDefault_{$type}_option{$default_name}" ); ?>" <?php checked( $options[$i]->is_default_option, true ); ?> value="<?php echo esc_attr( $j ); ?>" /> 
  316. <?php _e( 'Default Value', 'buddypress' ); ?> 
  317. </label> 
  318.  
  319. <?php if ( 1 !== $j ) : ?> 
  320. <div class ="delete-button"> 
  321. <a href='javascript:hide("<?php echo esc_attr( "{$type}_div{$j}" ); ?>")' class="delete"><?php esc_html_e( 'Delete', 'buddypress' ); ?></a> 
  322. </div> 
  323. <?php endif; ?> 
  324.  
  325. </div> 
  326.  
  327. <?php endfor; ?> 
  328.  
  329. <input type="hidden" name="<?php echo esc_attr( "{$type}_option_number" ); ?>" id="<?php echo esc_attr( "{$type}_option_number" ); ?>" value="<?php echo esc_attr( $j + 1 ); ?>" /> 
  330. <?php } ?> 
  331.  
  332. <div id="<?php echo esc_attr( "{$type}_more" ); ?>"></div> 
  333. <p><a href="javascript:add_option('<?php echo esc_js( $type ); ?>')"><?php esc_html_e( 'Add Another Option', 'buddypress' ); ?></a></p> 
  334.  
  335. <?php 
  336.  
  337. /** 
  338. * Fires at the end of the new field additional settings area. 
  339. * @since 2.3.0 
  340. * @param BP_XProfile_Field $current_field Current field being rendered. 
  341. */ 
  342. do_action( 'bp_xprofile_admin_new_field_additional_settings', $current_field ) ?> 
  343. </div> 
  344. </div> 
  345.  
  346. <?php 
  347.  
  348. /** 
  349. * Allow field types to modify submitted values before they are validated. 
  350. * In some cases, it may be appropriate for a field type to catch 
  351. * submitted values and modify them before they are passed to the 
  352. * is_valid() method. For example, URL validation requires the 
  353. * 'http://' scheme (so that the value saved in the database is always 
  354. * a fully-formed URL), but in order to allow users to enter a URL 
  355. * without this scheme, BP_XProfile_Field_Type_URL prepends 'http://' 
  356. * when it's not present. 
  357. * By default, this is a pass-through method that does nothing. Only 
  358. * override in your own field type if you need this kind of pre- 
  359. * validation filtering. 
  360. * @since 2.1.0 
  361. * @since 2.4.0 Added the `$field_id` parameter. 
  362. * @param mixed $field_value Submitted field value. 
  363. * @param string|int $field_id Optional. ID of the field. 
  364. * @return mixed 
  365. */ 
  366. public static function pre_validate_filter( $field_value, $field_id = '' ) { 
  367. return $field_value; 
  368.  
  369. /** 
  370. * Allow field types to modify the appearance of their values. 
  371. * By default, this is a pass-through method that does nothing. Only 
  372. * override in your own field type if you need to provide custom 
  373. * filtering for output values. 
  374. * @since 2.1.0 
  375. * @since 2.4.0 Added `$field_id` parameter. 
  376. * @param mixed $field_value Field value. 
  377. * @param string|int $field_id ID of the field. 
  378. * @return mixed 
  379. */ 
  380. public static function display_filter( $field_value, $field_id = '' ) { 
  381. return $field_value; 
  382.  
  383. /** 
  384. * Save miscellaneous settings related to this field type. 
  385. * Override in a specific field type if it requires an admin save routine. 
  386. * @since 2.7.0 
  387. * @param int $field_id Field ID. 
  388. * @param array $settings Array of settings. 
  389. */ 
  390. public function admin_save_settings( $field_id, $settings ) {} 
  391.  
  392. /** Protected *************************************************************/ 
  393.  
  394. /** 
  395. * Get a sanitised and escaped string of the edit field's HTML elements and attributes. 
  396. * Must be used inside the {@link bp_profile_fields()} template loop. 
  397. * This method was intended to be static but couldn't be because php.net/lsb/ requires PHP >= 5.3. 
  398. * @since 2.0.0 
  399. * @param array $properties Optional key/value array of attributes for this edit field. 
  400. * @return string 
  401. */ 
  402. protected function get_edit_field_html_elements( array $properties = array() ) { 
  403.  
  404. $r = bp_parse_args( $properties, array( 
  405. 'id' => bp_get_the_profile_field_input_name(),  
  406. 'name' => bp_get_the_profile_field_input_name(),  
  407. ) ); 
  408.  
  409. if ( bp_get_the_profile_field_is_required() ) { 
  410. $r['aria-required'] = 'true'; 
  411.  
  412. /** 
  413. * Filters the edit html elements and attributes. 
  414. * @since 2.0.0 
  415. * @param array $r Array of parsed arguments. 
  416. * @param string $value Class name for the current class instance. 
  417. */ 
  418. $r = (array) apply_filters( 'bp_xprofile_field_edit_html_elements', $r, get_class( $this ) ); 
  419.  
  420. return bp_get_form_field_attributes( sanitize_key( bp_get_the_profile_field_name() ), $r );