advanced-custom-fields / includes / fields.php

fields.php in Advanced Custom Fields (ACF®) 6.1.6, at includes/fields.php

480 lines 11.6 KB

Raw Download Zip

1	<?php
2
3	if ( ! defined( 'ABSPATH' ) ) {
4	exit; // Exit if accessed directly
5	}
6
7	if ( ! class_exists( 'acf_fields' ) ) :
8	#[AllowDynamicProperties]
9	class acf_fields {
10
11	/** @var array Contains an array of field type instances */
12	var $types = array();
13
14
15	/*
16	* __construct
17	*
18	* This function will setup the class functionality
19	*
20	* @type function
21	* @date 5/03/2014
22	* @since 5.4.0
23	*
24	* @param n/a
25	* @return n/a
26	*/
27
28	function __construct() {
29	/* do nothing */
30	}
31
32
33	/*
34	* register_field_type
35	*
36	* This function will register a field type instance
37	*
38	* @type function
39	* @date 6/07/2016
40	* @since 5.4.0
41	*
42	* @param $class (string)
43	* @return n/a
44	*/
45
46	function register_field_type( $class ) {
47
48	// allow instance
49	if ( $class instanceof acf_field ) {
50	$this->types[ $class->name ] = $class;
51
52	// allow class name
53	} else {
54	$instance = new $class();
55	$this->types[ $instance->name ] = $instance;
56	}
57	}
58
59
60	/*
61	* get_field_type
62	*
63	* This function will return a field type instance
64	*
65	* @type function
66	* @date 6/07/2016
67	* @since 5.4.0
68	*
69	* @param $name (string)
70	* @return (mixed)
71	*/
72
73	function get_field_type( $name ) {
74	return isset( $this->types[ $name ] ) ? $this->types[ $name ] : null;
75	}
76
77
78	/*
79	* is_field_type
80	*
81	* This function will return true if a field type exists
82	*
83	* @type function
84	* @date 6/07/2016
85	* @since 5.4.0
86	*
87	* @param $name (string)
88	* @return (mixed)
89	*/
90
91	function is_field_type( $name ) {
92	return isset( $this->types[ $name ] );
93	}
94
95
96	/*
97	* register_field_type_info
98	*
99	* This function will store a basic array of info about the field type
100	* to later be overriden by the above register_field_type function
101	*
102	* @type function
103	* @date 29/5/17
104	* @since 5.6.0
105	*
106	* @param $info (array)
107	* @return n/a
108	*/
109
110	function register_field_type_info( $info ) {
111
112	// convert to object
113	$instance = (object) $info;
114	$this->types[ $instance->name ] = $instance;
115	}
116
117
118	/*
119	* get_field_types
120	*
121	* This function will return an array of all field types
122	*
123	* @type function
124	* @date 6/07/2016
125	* @since 5.4.0
126	*
127	* @param $name (string)
128	* @return (mixed)
129	*/
130
131	function get_field_types() {
132	return $this->types;
133	}
134	}
135
136
137	// initialize
138	acf()->fields = new acf_fields();
139
140	endif; // class_exists check
141
142
143	/*
144	* acf_register_field_type
145	*
146	* alias of acf()->fields->register_field_type()
147	*
148	* @type function
149	* @date 31/5/17
150	* @since 5.6.0
151	*
152	* @param n/a
153	* @return n/a
154	*/
155
156	function acf_register_field_type( $class ) {
157	return acf()->fields->register_field_type( $class );
158	}
159
160
161	/*
162	* acf_register_field_type_info
163	*
164	* alias of acf()->fields->register_field_type_info()
165	*
166	* @type function
167	* @date 31/5/17
168	* @since 5.6.0
169	*
170	* @param n/a
171	* @return n/a
172	*/
173
174	function acf_register_field_type_info( $info ) {
175	return acf()->fields->register_field_type_info( $info );
176	}
177
178
179	/*
180	* acf_get_field_type
181	*
182	* alias of acf()->fields->get_field_type()
183	*
184	* @type function
185	* @date 31/5/17
186	* @since 5.6.0
187	*
188	* @param n/a
189	* @return n/a
190	*/
191
192	function acf_get_field_type( $name ) {
193	return acf()->fields->get_field_type( $name );
194	}
195
196
197	/*
198	* acf_get_field_types
199	*
200	* alias of acf()->fields->get_field_types()
201	*
202	* @type function
203	* @date 31/5/17
204	* @since 5.6.0
205	*
206	* @param n/a
207	* @return n/a
208	*/
209
210	function acf_get_field_types( $args = array() ) {
211
212	// default
213	$args = wp_parse_args(
214	$args,
215	array(
216	'public' => true, // true, false
217	)
218	);
219
220	// get field types
221	$field_types = acf()->fields->get_field_types();
222
223	// filter
224	return wp_filter_object_list( $field_types, $args );
225	}
226
227
228	/**
229	* acf_get_field_types_info
230	*
231	* Returns an array containing information about each field type
232	*
233	* @date 18/6/18
234	* @since 5.6.9
235	*
236	* @param type $var Description. Default.
237	* @return type Description.
238	*/
239
240	function acf_get_field_types_info( $args = array() ) {
241
242	// vars
243	$data = array();
244	$field_types = acf_get_field_types();
245
246	// loop
247	foreach ( $field_types as $type ) {
248	$data[ $type->name ] = array_filter(
249	array(
250	'label' => $type->label,
251	'name' => $type->name,
252	'description' => $type->description,
253	'category' => $type->category,
254	'public' => $type->public,
255	'doc_url' => $type->doc_url,
256	'tutorial_url' => $type->tutorial_url,
257	'preview_image' => $type->preview_image,
258	'pro' => $type->pro,
259	)
260	);
261	}
262
263	// return
264	return $data;
265	}
266
267
268	/*
269	* acf_is_field_type
270	*
271	* alias of acf()->fields->is_field_type()
272	*
273	* @type function
274	* @date 31/5/17
275	* @since 5.6.0
276	*
277	* @param n/a
278	* @return n/a
279	*/
280
281	function acf_is_field_type( $name = '' ) {
282	return acf()->fields->is_field_type( $name );
283	}
284
285
286	/*
287	* acf_get_field_type_prop
288	*
289	* This function will return a field type's property
290	*
291	* @type function
292	* @date 1/10/13
293	* @since 5.0.0
294	*
295	* @param n/a
296	* @return (array)
297	*/
298
299	function acf_get_field_type_prop( $name = '', $prop = '' ) {
300	$type = acf_get_field_type( $name );
301	return ( $type && isset( $type->$prop ) ) ? $type->$prop : null;
302	}
303
304
305	/*
306	* acf_get_field_type_label
307	*
308	* This function will return the label of a field type
309	*
310	* @type function
311	* @date 1/10/13
312	* @since 5.0.0
313	*
314	* @param n/a
315	* @return (array)
316	*/
317
318	function acf_get_field_type_label( $name = '' ) {
319	$label = acf_get_field_type_prop( $name, 'label' );
320	return $label ? $label : '<span class="acf-tooltip-js" title="' . __( 'Field type does not exist', 'acf' ) . '">' . __( 'Unknown', 'acf' ) . '</span>';
321	}
322
323
324	/*
325	* acf_field_type_exists (deprecated)
326	*
327	* deprecated in favour of acf_is_field_type()
328	*
329	* @type function
330	* @date 1/10/13
331	* @since 5.0.0
332	*
333	* @param $type (string)
334	* @return (boolean)
335	*/
336
337	function acf_field_type_exists( $type = '' ) {
338	return acf_is_field_type( $type );
339	}
340
341	/**
342	* Returns an array of localised field categories.
343	*
344	* @since 6.1
345	*
346	* @return array
347	*/
348	function acf_get_field_categories_i18n() {
349
350	$categories_i18n = array(
351	'basic' => __( 'Basic', 'acf' ),
352	'content' => __( 'Content', 'acf' ),
353	'choice' => __( 'Choice', 'acf' ),
354	'relational' => __( 'Relational', 'acf' ),
355	'advanced' => __( 'Advanced', 'acf' ),
356	'layout' => __( 'Layout', 'acf' ),
357	'pro' => __( 'PRO', 'acf' ),
358	);
359
360	return apply_filters( 'acf/localized_field_categories', $categories_i18n );
361	}
362
363
364	/**
365	* Returns an multi-dimentional array of field types "name => label" grouped by category
366	*
367	* @since 5.0.0
368	*
369	* @return array
370	*/
371	function acf_get_grouped_field_types() {
372
373	// vars
374	$types = acf_get_field_types();
375	$groups = array();
376	$l10n = acf_get_field_categories_i18n();
377
378	// loop
379	foreach ( $types as $type ) {
380
381	// translate
382	$cat = $type->category;
383	$cat = isset( $l10n[ $cat ] ) ? $l10n[ $cat ] : $cat;
384
385	// append
386	$groups[ $cat ][ $type->name ] = $type->label;
387	}
388
389	// filter
390	$groups = apply_filters( 'acf/get_field_types', $groups );
391
392	// return
393	return $groups;
394	}
395
396	/**
397	* Returns an array of tabs for a field type.
398	* We combine a list of default tabs with filtered tabs.
399	* I.E. Default tabs should be static and should not be changed by the
400	* filtered tabs.
401	*
402	* @since 6.1
403	*
404	* @return array Key/value array of the default settings tabs for field type settings.
405	*/
406	function acf_get_combined_field_type_settings_tabs() {
407	$default_field_type_settings_tabs = array(
408	'general' => __( 'General', 'acf' ),
409	'validation' => __( 'Validation', 'acf' ),
410	'presentation' => __( 'Presentation', 'acf' ),
411	'conditional_logic' => __( 'Conditional Logic', 'acf' ),
412	);
413
414	$field_type_settings_tabs = (array) apply_filters( 'acf/field_group/additional_field_settings_tabs', array() );
415
416	// remove any default tab values from filter tabs.
417	foreach ( $field_type_settings_tabs as $key => $tab ) {
418	if ( isset( $default_field_type_settings_tabs[ $key ] ) ) {
419	unset( $field_type_settings_tabs[ $key ] );
420	}
421	}
422
423	$combined_field_type_settings_tabs = array_merge( $default_field_type_settings_tabs, $field_type_settings_tabs );
424
425	return $combined_field_type_settings_tabs;
426	}
427
428
429
430	/**
431	* Get the PRO only fields and their core metadata.
432	*
433	* @since 6.1
434	*
435	* @return array An array of all the pro field types and their field type selection required meta data.
436	*/
437	function acf_get_pro_field_types() {
438	return array(
439	'clone' => array(
440	'name' => 'clone',
441	'label' => _x( 'Clone', 'noun', 'acf' ),
442	'doc_url' => acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/clone/', 'docs', 'field-type-selection' ),
443	'preview_image' => acf_get_url() . '/assets/images/field-type-previews/field-preview-clone.png',
444	'description' => __( 'This allows you to select and display existing fields. It does not duplicate any fields in the database, but loads and displays the selected fields at run-time. The Clone field can either replace itself with the selected fields or display the selected fields as a group of subfields.', 'acf' ),
445	'category' => 'layout',
446	'pro' => true,
447	),
448	'flexible_content' => array(
449	'name' => 'flexible_content',
450	'label' => __( 'Flexible Content', 'acf' ),
451	'doc_url' => acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/flexible-content/', 'docs', 'field-type-selection' ),
452	'preview_image' => acf_get_url() . '/assets/images/field-type-previews/field-preview-flexible-content.png',
453	'description' => __( 'This provides a simple, structured, layout-based editor. The Flexible Content field allows you to define, create and manage content with total control by using layouts and subfields to design the available blocks.', 'acf' ),
454	'tutorial_url' => acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/building-layouts-with-the-flexible-content-field-in-a-theme/', 'docs', 'field-type-selection' ),
455	'category' => 'layout',
456	'pro' => true,
457	),
458	'gallery' => array(
459	'name' => 'gallery',
460	'label' => __( 'Gallery', 'acf' ),
461	'doc_url' => acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/gallery/', 'docs', 'field-type-selection' ),
462	'preview_image' => acf_get_url() . '/assets/images/field-type-previews/field-preview-gallery.png',
463	'description' => __( 'This provides an interactive interface for managing a collection of attachments. Most settings are similar to the Image field type. Additional settings allow you to specify where new attachments are added in the gallery and the minimum/maximum number of attachments allowed.', 'acf' ),
464	'tutorial_url' => acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/how-to-use-the-gallery-field/', 'docs', 'field-type-selection' ),
465	'category' => 'content',
466	'pro' => true,
467	),
468	'repeater' => array(
469	'name' => 'repeater',
470	'label' => __( 'Repeater', 'acf' ),
471	'doc_url' => acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/repeater/', 'docs', 'field-type-selection' ),
472	'preview_image' => acf_get_url() . '/assets/images/field-type-previews/field-preview-repeater.png',
473	'description' => __( 'This provides a solution for repeating content such as slides, team members, and call-to-action tiles, by acting as a parent to a set of subfields which can be repeated again and again.', 'acf' ),
474	'tutorial_url' => acf_add_url_utm_tags( 'https://www.advancedcustomfields.com/resources/repeater/how-to-use-the-repeater-field/', 'docs', 'field-type-selection' ),
475	'category' => 'layout',
476	'pro' => true,
477	),
478	);
479	}
480