acf-field-group-functions.php — Advanced Custom Fields (ACF®) 6.2.7

advanced-custom-fields / includes / acf-field-group-functions.php

advanced-custom-fields / includes Last commit date

acf-field-group-functions.php

513 lines

1	<?php
2
3	/**
4	* acf_get_field_group
5	*
6	* Retrieves a field group for the given identifier.
7	*
8	* @date 30/09/13
9	* @since 5.0.0
10	*
11	* @param (int\|string) $id The field group ID, key or name.
12	* @return (array\|false) The field group array.
13	*/
14	function acf_get_field_group( $id = 0 ) {
15	return acf_get_internal_post_type( $id, 'acf-field-group' );
16	}
17
18	/**
19	* acf_get_raw_field_group
20	*
21	* Retrieves raw field group data for the given identifier.
22	*
23	* @date 18/1/19
24	* @since 5.7.10
25	*
26	* @param (int\|string) $id The field ID, key or name.
27	* @return (array\|false) The field group array.
28	*/
29	function acf_get_raw_field_group( $id = 0 ) {
30	return acf_get_raw_internal_post_type( $id, 'acf-field-group' );
31	}
32
33	/**
34	* acf_get_field_group_post
35	*
36	* Retrieves the field group's WP_Post object.
37	*
38	* @date 18/1/19
39	* @since 5.7.10
40	*
41	* @param (int\|string) $id The field group's ID, key or name.
42	* @return (array\|false) The field group's array.
43	*/
44	function acf_get_field_group_post( $id = 0 ) {
45	return acf_get_internal_post_type_post( $id, 'acf-field-group' );
46	}
47
48	/**
49	* acf_is_field_group_key
50	*
51	* Returns true if the given identifier is a field group key.
52	*
53	* @date 6/12/2013
54	* @since 5.0.0
55	*
56	* @param string $id The identifier.
57	* @return boolean
58	*/
59	function acf_is_field_group_key( $id = '' ) {
60	return acf_is_internal_post_type_key( $id, 'acf-field-group' );
61	}
62
63	/**
64	* Ensures the given field group is valid.
65	*
66	* @date 18/1/19
67	* @since 5.7.10
68	*
69	* @param array $field_group The field group array.
70	* @return array
71	*/
72	function acf_validate_field_group( $field_group = array() ) {
73	return acf_validate_internal_post_type( $field_group, 'acf-field-group' );
74	}
75
76	/**
77	* acf_get_valid_field_group
78	*
79	* Ensures the given field group is valid.
80	*
81	* @date 28/09/13
82	* @since 5.0.0
83	*
84	* @param array $field_group The field group array.
85	* @return array
86	*/
87	function acf_get_valid_field_group( $field_group = false ) {
88	return acf_validate_field_group( $field_group );
89	}
90
91	/**
92	* acf_translate_field_group
93	*
94	* Translates a field group's settings.
95	*
96	* @date 8/03/2016
97	* @since 5.3.2
98	*
99	* @param array $field_group The field group array.
100	* @return array
101	*/
102	function acf_translate_field_group( $field_group = array() ) {
103	return acf_translate_internal_post_type( $field_group, 'acf-field-group' );
104	}
105
106	/**
107	* acf_get_field_groups
108	*
109	* Returns and array of field_groups for the given $filter.
110	*
111	* @date 30/09/13
112	* @since 5.0.0
113	*
114	* @param array $filter An array of args to filter results by.
115	* @return array
116	*/
117	function acf_get_field_groups( $filter = array() ) {
118	return acf_get_internal_post_type_posts( 'acf-field-group', $filter );
119	}
120
121	/**
122	* acf_get_raw_field_groups
123	*
124	* Returns and array of raw field_group data.
125	*
126	* @date 18/1/19
127	* @since 5.7.10
128	*
129	* @param void
130	* @return array
131	*/
132	function acf_get_raw_field_groups() {
133	return acf_get_raw_internal_post_type_posts( 'acf-field-group' );
134	}
135
136	/**
137	* acf_filter_field_groups
138	*
139	* Returns a filtered aray of field groups based on the given $args.
140	*
141	* @date 29/11/2013
142	* @since 5.0.0
143	*
144	* @param array $field_groups An array of field groups.
145	* @param array $args An array of location args.
146	* @return array
147	*/
148	function acf_filter_field_groups( $field_groups, $args = array() ) {
149	return acf_filter_internal_post_type_posts( $field_groups, $args, 'acf-field-group' );
150	}
151
152	/**
153	* acf_get_field_group_visibility
154	*
155	* Returns true if the given field group's location rules match the given $args.
156	*
157	* @date 7/10/13
158	* @since 5.0.0
159	*
160	* @param array $field_groups An array of field groups.
161	* @param array $args An array of location args.
162	* @return boolean
163	*/
164	function acf_get_field_group_visibility( $field_group, $args = array() ) {
165
166	// Check if active.
167	if ( ! $field_group['active'] ) {
168	return false;
169	}
170
171	// Check if location rules exist
172	if ( $field_group['location'] ) {
173
174	// Get the current screen.
175	$screen = acf_get_location_screen( $args );
176
177	// Loop through location groups.
178	foreach ( $field_group['location'] as $group ) {
179
180	// ignore group if no rules.
181	if ( empty( $group ) ) {
182	continue;
183	}
184
185	// Loop over rules and determine if all rules match.
186	$match_group = true;
187	foreach ( $group as $rule ) {
188	if ( ! acf_match_location_rule( $rule, $screen, $field_group ) ) {
189	$match_group = false;
190	break;
191	}
192	}
193
194	// If this group matches, show the field group.
195	if ( $match_group ) {
196	return true;
197	}
198	}
199	}
200
201	// Return default.
202	return false;
203	}
204
205	/**
206	* acf_update_field_group
207	*
208	* Updates a field group in the database.
209	*
210	* @date 21/1/19
211	* @since 5.7.10
212	*
213	* @param array $field_group The field group array.
214	* @return array
215	*/
216	function acf_update_field_group( $field_group ) {
217	return acf_update_internal_post_type( $field_group, 'acf-field-group' );
218	}
219
220	/**
221	* _acf_apply_unique_field_group_slug
222	*
223	* Allows full control over 'acf-field-group' slugs.
224	*
225	* @date 21/1/19
226	* @since 5.7.10
227	*
228	* @param string $slug The post slug.
229	* @param integer $post_ID Post ID.
230	* @param string $post_status The post status.
231	* @param string $post_type Post type.
232	* @param integer $post_parent Post parent ID
233	* @param string $original_slug The original post slug.
234	*/
235	function _acf_apply_unique_field_group_slug( $slug, $post_ID, $post_status, $post_type, $post_parent, $original_slug ) {
236
237	// Check post type and reset to original value.
238	if ( $post_type === 'acf-field-group' ) {
239	return $original_slug;
240	}
241
242	// Return slug.
243	return $slug;
244	}
245
246	/**
247	* acf_flush_field_group_cache
248	*
249	* Deletes all caches for this field group.
250	*
251	* @date 22/1/19
252	* @since 5.7.10
253	*
254	* @param array $field_group The field group array.
255	* @return void
256	*/
257	function acf_flush_field_group_cache( $field_group ) {
258	acf_flush_internal_post_type_cache( $field_group, 'acf-field-group' );
259	}
260
261	/**
262	* acf_delete_field_group
263	*
264	* Deletes a field group from the database.
265	*
266	* @date 21/1/19
267	* @since 5.7.10
268	*
269	* @param (int\|string) $id The field group ID, key or name.
270	* @return boolean True if field group was deleted.
271	*/
272	function acf_delete_field_group( $id = 0 ) {
273	return acf_delete_internal_post_type( $id, 'acf-field-group' );
274	}
275
276	/**
277	* acf_trash_field_group
278	*
279	* Trashes a field group from the database.
280	*
281	* @date 2/10/13
282	* @since 5.0.0
283	*
284	* @param (int\|string) $id The field group ID, key or name.
285	* @return boolean True if field group was trashed.
286	*/
287	function acf_trash_field_group( $id = 0 ) {
288	return acf_trash_internal_post_type( $id, 'acf-field-group' );
289	}
290
291	/**
292	* acf_untrash_field_group
293	*
294	* Restores a field_group from the trash.
295	*
296	* @date 2/10/13
297	* @since 5.0.0
298	*
299	* @param (int\|string) $id The field_group ID, key or name.
300	* @return boolean True if field_group was trashed.
301	*/
302	function acf_untrash_field_group( $id = 0 ) {
303	return acf_untrash_internal_post_type( $id, 'acf-field-group' );
304	}
305
306	/**
307	* Filter callback which returns the previous post_status instead of "draft" for the "acf-field-group" post type.
308	*
309	* Prior to WordPress 5.6.0, this filter was not needed as restored posts were always assigned their original status.
310	*
311	* @since 5.9.5
312	*
313	* @param string $new_status The new status of the post being restored.
314	* @param integer $post_id The ID of the post being restored.
315	* @param string $previous_status The status of the post at the point where it was trashed.
316	* @return string.
317	*/
318	function _acf_untrash_field_group_post_status( $new_status, $post_id, $previous_status ) {
319	return ( get_post_type( $post_id ) === 'acf-field-group' ) ? $previous_status : $new_status;
320	}
321
322	/**
323	* acf_is_field_group
324	*
325	* Returns true if the given params match a field group.
326	*
327	* @date 21/1/19
328	* @since 5.7.10
329	*
330	* @param array $field_group The field group array.
331	* @param mixed $id An optional identifier to search for.
332	* @return boolean
333	*/
334	function acf_is_field_group( $field_group = false ) {
335	return acf_is_internal_post_type( $field_group, 'acf-field-group' );
336	}
337
338	/**
339	* acf_duplicate_field_group
340	*
341	* Duplicates a field group.
342	*
343	* @date 16/06/2014
344	* @since 5.0.0
345	*
346	* @param (int\|string) $id The field_group ID, key or name.
347	* @param integer $new_post_id Optional post ID to override.
348	* @return array The new field group.
349	*/
350	function acf_duplicate_field_group( $id = 0, $new_post_id = 0 ) {
351	return acf_duplicate_internal_post_type( $id, $new_post_id, 'acf-field-group' );
352	}
353
354	/**
355	* Activates or deactivates a field group.
356	*
357	* @param integer\|string $id The field_group ID, key or name.
358	* @param boolean $activate True if the post should be activated.
359	* @return boolean
360	*/
361	function acf_update_field_group_active_status( $id, $activate = true ) {
362	return acf_update_internal_post_type_active_status( $id, $activate, 'acf-field-group' );
363	}
364
365	/**
366	* acf_get_field_group_style
367	*
368	* Returns the CSS styles generated from field group settings.
369	*
370	* @date 20/10/13
371	* @since 5.0.0
372	*
373	* @param array $field_group The field group array.
374	* @return string.
375	*/
376	function acf_get_field_group_style( $field_group ) {
377
378	// Vars.
379	$style = '';
380	$elements = array(
381	'permalink' => '#edit-slug-box',
382	'the_content' => '#postdivrich',
383	'excerpt' => '#postexcerpt',
384	'custom_fields' => '#postcustom',
385	'discussion' => '#commentstatusdiv',
386	'comments' => '#commentsdiv',
387	'slug' => '#slugdiv',
388	'author' => '#authordiv',
389	'format' => '#formatdiv',
390	'page_attributes' => '#pageparentdiv',
391	'featured_image' => '#postimagediv',
392	'revisions' => '#revisionsdiv',
393	'categories' => '#categorydiv',
394	'tags' => '#tagsdiv-post_tag',
395	'send-trackbacks' => '#trackbacksdiv',
396	);
397
398	// Loop over field group settings and generate list of selectors to hide.
399	if ( is_array( $field_group['hide_on_screen'] ) ) {
400	$hide = array();
401	foreach ( $field_group['hide_on_screen'] as $k ) {
402	if ( isset( $elements[ $k ] ) ) {
403	$id = $elements[ $k ];
404	$hide[] = $id;
405	$hide[] = '#screen-meta label[for=' . substr( $id, 1 ) . '-hide]';
406	}
407	}
408	$style = implode( ', ', $hide ) . ' {display: none;}';
409	}
410
411	/**
412	* Filters the generated CSS styles.
413	*
414	* @date 12/02/2014
415	* @since 5.0.0
416	*
417	* @param string $style The CSS styles.
418	* @param array $field_group The field group array.
419	*/
420	return apply_filters( 'acf/get_field_group_style', $style, $field_group );
421	}
422
423	/**
424	* acf_get_field_group_edit_link
425	*
426	* Checks if the current user can edit the field group and returns the edit url.
427	*
428	* @date 23/9/18
429	* @since 5.7.7
430	*
431	* @param integer $post_id The field group ID.
432	* @return string
433	*/
434	function acf_get_field_group_edit_link( $post_id ) {
435	return acf_get_internal_post_type_edit_link( $post_id, 'acf-field-group' );
436	}
437
438	/**
439	* acf_prepare_field_group_for_export
440	*
441	* Returns a modified field group ready for export.
442	*
443	* @date 11/03/2014
444	* @since 5.0.0
445	*
446	* @param array $field_group The field group array.
447	* @return array
448	*/
449	function acf_prepare_field_group_for_export( $field_group = array() ) {
450	return acf_prepare_internal_post_type_for_export( $field_group, 'acf-field-group' );
451	}
452
453	/**
454	* acf_prepare_field_group_for_import
455	*
456	* Prepares a field group for the import process.
457	*
458	* @date 21/11/19
459	* @since 5.8.8
460	*
461	* @param array $field_group The field group array.
462	* @return array
463	*/
464	function acf_prepare_field_group_for_import( $field_group ) {
465	return acf_prepare_internal_post_type_for_import( $field_group, 'acf-field-group' );
466	}
467
468	/**
469	* acf_import_field_group
470	*
471	* Imports a field group into the databse.
472	*
473	* @date 11/03/2014
474	* @since 5.0.0
475	*
476	* @param array $field_group The field group array.
477	* @return array The new field group.
478	*/
479	function acf_import_field_group( $field_group ) {
480	return acf_import_internal_post_type( $field_group, 'acf-field-group' );
481	}
482
483	/**
484	* Returns an array of tabs for the field group settings.
485	* We combine a list of default tabs with filtered tabs.
486	* I.E. Default tabs should be static and should not be changed by the
487	* filtered tabs.
488	*
489	* @since 6.1
490	*
491	* @return array Key/value array of the default settings tabs for field group settings.
492	*/
493	function acf_get_combined_field_group_settings_tabs() {
494	$default_field_group_settings_tabs = array(
495	'location_rules' => __( 'Location Rules', 'acf' ),
496	'presentation' => __( 'Presentation', 'acf' ),
497	'group_settings' => __( 'Group Settings', 'acf' ),
498	);
499
500	$field_group_settings_tabs = (array) apply_filters( 'acf/field_group/additional_group_settings_tabs', array() );
501
502	// remove any default tab values from the filter tabs.
503	foreach ( $field_group_settings_tabs as $key => $tab ) {
504	if ( isset( $default_field_group_settings_tabs[ $key ] ) ) {
505	unset( $field_group_settings_tabs[ $key ] );
506	}
507	}
508
509	$combined_field_group_settings_tabs = array_merge( $default_field_group_settings_tabs, $field_group_settings_tabs );
510
511	return $combined_field_group_settings_tabs;
512	}
513