acf-field-group-functions.php — Secure Custom Fields 6.9.1

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

secure-custom-fields / includes Last commit date

acf-field-group-functions.php

571 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 ACF 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 ACF 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 ACF 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 ACF 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 ACF 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 ACF 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 ACF 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 ACF 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 ACF 5.7.10
128	*
129	* @return array
130	*/
131	function acf_get_raw_field_groups() {
132	return acf_get_raw_internal_post_type_posts( 'acf-field-group' );
133	}
134
135	/**
136	* acf_filter_field_groups
137	*
138	* Returns a filtered array of field groups based on the given $args.
139	*
140	* @date 29/11/2013
141	* @since ACF 5.0.0
142	*
143	* @param array $field_groups An array of field groups.
144	* @param array $args An array of location args.
145	* @return array
146	*/
147	function acf_filter_field_groups( $field_groups, $args = array() ) {
148	return acf_filter_internal_post_type_posts( $field_groups, $args, 'acf-field-group' );
149	}
150
151	/**
152	* acf_get_field_group_visibility
153	*
154	* Returns true if the given field group's location rules match the given $args.
155	*
156	* @date 7/10/13
157	* @since ACF 5.0.0
158	*
159	* @param array $field_groups An array of field groups.
160	* @param array $args An array of location args.
161	* @return boolean
162	*/
163	function acf_get_field_group_visibility( $field_group, $args = array() ) {
164
165	// Check if active.
166	if ( ! $field_group['active'] ) {
167	return false;
168	}
169
170	// Check if location rules exist
171	if ( $field_group['location'] ) {
172
173	// Get the current screen.
174	$screen = acf_get_location_screen( $args );
175
176	// Loop through location groups.
177	foreach ( $field_group['location'] as $group ) {
178
179	// ignore group if no rules.
180	if ( empty( $group ) ) {
181	continue;
182	}
183
184	// Loop over rules and determine if all rules match.
185	$match_group = true;
186	foreach ( $group as $rule ) {
187	if ( ! acf_match_location_rule( $rule, $screen, $field_group ) ) {
188	$match_group = false;
189	break;
190	}
191	}
192
193	// If this group matches, show the field group.
194	if ( $match_group ) {
195	return true;
196	}
197	}
198	}
199
200	// Return default.
201	return false;
202	}
203
204	/**
205	* acf_update_field_group
206	*
207	* Updates a field group in the database.
208	*
209	* @date 21/1/19
210	* @since ACF 5.7.10
211	*
212	* @param array $field_group The field group array.
213	* @return array
214	*/
215	function acf_update_field_group( $field_group ) {
216	return acf_update_internal_post_type( $field_group, 'acf-field-group' );
217	}
218
219	/**
220	* _acf_apply_unique_field_group_slug
221	*
222	* Allows full control over 'acf-field-group' slugs.
223	*
224	* @date 21/1/19
225	* @since ACF 5.7.10
226	*
227	* @param string $slug The post slug.
228	* @param integer $post_ID Post ID.
229	* @param string $post_status The post status.
230	* @param string $post_type Post type.
231	* @param integer $post_parent Post parent ID
232	* @param string $original_slug The original post slug.
233	*/
234	function _acf_apply_unique_field_group_slug( $slug, $post_ID, $post_status, $post_type, $post_parent, $original_slug ) {
235
236	// Check post type and reset to original value.
237	if ( $post_type === 'acf-field-group' ) {
238	return $original_slug;
239	}
240
241	// Return slug.
242	return $slug;
243	}
244
245	/**
246	* acf_flush_field_group_cache
247	*
248	* Deletes all caches for this field group.
249	*
250	* @date 22/1/19
251	* @since ACF 5.7.10
252	*
253	* @param array $field_group The field group array.
254	* @return void
255	*/
256	function acf_flush_field_group_cache( $field_group ) {
257	acf_flush_internal_post_type_cache( $field_group, 'acf-field-group' );
258	}
259
260	/**
261	* acf_delete_field_group
262	*
263	* Deletes a field group from the database.
264	*
265	* @date 21/1/19
266	* @since ACF 5.7.10
267	*
268	* @param (int\|string) $id The field group ID, key or name.
269	* @return boolean True if field group was deleted.
270	*/
271	function acf_delete_field_group( $id = 0 ) {
272	return acf_delete_internal_post_type( $id, 'acf-field-group' );
273	}
274
275	/**
276	* acf_trash_field_group
277	*
278	* Trashes a field group from the database.
279	*
280	* @date 2/10/13
281	* @since ACF 5.0.0
282	*
283	* @param (int\|string) $id The field group ID, key or name.
284	* @return boolean True if field group was trashed.
285	*/
286	function acf_trash_field_group( $id = 0 ) {
287	return acf_trash_internal_post_type( $id, 'acf-field-group' );
288	}
289
290	/**
291	* acf_untrash_field_group
292	*
293	* Restores a field_group from the trash.
294	*
295	* @date 2/10/13
296	* @since ACF 5.0.0
297	*
298	* @param (int\|string) $id The field_group ID, key or name.
299	* @return boolean True if field_group was trashed.
300	*/
301	function acf_untrash_field_group( $id = 0 ) {
302	return acf_untrash_internal_post_type( $id, 'acf-field-group' );
303	}
304
305	/**
306	* Filter callback which returns the previous post_status instead of "draft" for the "acf-field-group" post type.
307	*
308	* Prior to WordPress 5.6.0, this filter was not needed as restored posts were always assigned their original status.
309	*
310	* @since ACF 5.9.5
311	*
312	* @param string $new_status The new status of the post being restored.
313	* @param integer $post_id The ID of the post being restored.
314	* @param string $previous_status The status of the post at the point where it was trashed.
315	* @return string.
316	*/
317	function _acf_untrash_field_group_post_status( $new_status, $post_id, $previous_status ) {
318	return ( get_post_type( $post_id ) === 'acf-field-group' ) ? $previous_status : $new_status;
319	}
320
321	/**
322	* acf_is_field_group
323	*
324	* Returns true if the given params match a field group.
325	*
326	* @date 21/1/19
327	* @since ACF 5.7.10
328	*
329	* @param array $field_group The field group array.
330	* @param mixed $id An optional identifier to search for.
331	* @return boolean
332	*/
333	function acf_is_field_group( $field_group = false ) {
334	return acf_is_internal_post_type( $field_group, 'acf-field-group' );
335	}
336
337	/**
338	* acf_duplicate_field_group
339	*
340	* Duplicates a field group.
341	*
342	* @date 16/06/2014
343	* @since ACF 5.0.0
344	*
345	* @param (int\|string) $id The field_group ID, key or name.
346	* @param integer $new_post_id Optional post ID to override.
347	* @return array The new field group.
348	*/
349	function acf_duplicate_field_group( $id = 0, $new_post_id = 0 ) {
350	return acf_duplicate_internal_post_type( $id, $new_post_id, 'acf-field-group' );
351	}
352
353	/**
354	* Activates or deactivates a field group.
355	*
356	* @param integer\|string $id The field_group ID, key or name.
357	* @param boolean $activate True if the post should be activated.
358	* @return boolean
359	*/
360	function acf_update_field_group_active_status( $id, $activate = true ) {
361	return acf_update_internal_post_type_active_status( $id, $activate, 'acf-field-group' );
362	}
363
364	/**
365	* acf_get_field_group_style
366	*
367	* Returns the CSS styles generated from field group settings.
368	*
369	* @date 20/10/13
370	* @since ACF 5.0.0
371	*
372	* @param array $field_group The field group array.
373	* @return string.
374	*/
375	function acf_get_field_group_style( $field_group ) {
376
377	// Vars.
378	$style = '';
379	$elements = array(
380	'permalink' => '#edit-slug-box',
381	'the_content' => '#postdivrich',
382	'excerpt' => '#postexcerpt',
383	'custom_fields' => '#postcustom',
384	'discussion' => '#commentstatusdiv',
385	'comments' => '#commentsdiv',
386	'slug' => '#slugdiv',
387	'author' => '#authordiv',
388	'format' => '#formatdiv',
389	'page_attributes' => '#pageparentdiv',
390	'featured_image' => '#postimagediv',
391	'revisions' => '#revisionsdiv',
392	'categories' => '#categorydiv',
393	'tags' => '#tagsdiv-post_tag',
394	'send-trackbacks' => '#trackbacksdiv',
395	);
396
397	// Loop over field group settings and generate list of selectors to hide.
398	if ( is_array( $field_group['hide_on_screen'] ) ) {
399	$hide = array();
400	foreach ( $field_group['hide_on_screen'] as $k ) {
401	if ( isset( $elements[ $k ] ) ) {
402	$id = $elements[ $k ];
403	$hide[] = $id;
404	$hide[] = '#screen-meta label[for=' . substr( $id, 1 ) . '-hide]';
405	}
406	}
407	$style = implode( ', ', $hide ) . ' {display: none;}';
408	}
409
410	/**
411	* Filters the generated CSS styles.
412	*
413	* @date 12/02/2014
414	* @since ACF 5.0.0
415	*
416	* @param string $style The CSS styles.
417	* @param array $field_group The field group array.
418	*/
419	return apply_filters( 'acf/get_field_group_style', $style, $field_group );
420	}
421
422	/**
423	* acf_get_field_group_edit_link
424	*
425	* Checks if the current user can edit the field group and returns the edit url.
426	*
427	* @date 23/9/18
428	* @since ACF 5.7.7
429	*
430	* @param integer $post_id The field group ID.
431	* @return string
432	*/
433	function acf_get_field_group_edit_link( $post_id ) {
434	return acf_get_internal_post_type_edit_link( $post_id, 'acf-field-group' );
435	}
436
437	/**
438	* acf_prepare_field_group_for_export
439	*
440	* Returns a modified field group ready for export.
441	*
442	* @date 11/03/2014
443	* @since ACF 5.0.0
444	*
445	* @param array $field_group The field group array.
446	* @return array
447	*/
448	function acf_prepare_field_group_for_export( $field_group = array() ) {
449	return acf_prepare_internal_post_type_for_export( $field_group, 'acf-field-group' );
450	}
451
452	/**
453	* acf_prepare_field_group_for_import
454	*
455	* Prepares a field group for the import process.
456	*
457	* @date 21/11/19
458	* @since ACF 5.8.8
459	*
460	* @param array $field_group The field group array.
461	* @return array
462	*/
463	function acf_prepare_field_group_for_import( $field_group ) {
464	return acf_prepare_internal_post_type_for_import( $field_group, 'acf-field-group' );
465	}
466
467	/**
468	* acf_import_field_group
469	*
470	* Imports a field group into the database.
471	*
472	* @date 11/03/2014
473	* @since ACF 5.0.0
474	*
475	* @param array $field_group The field group array.
476	* @return array The new field group.
477	*/
478	function acf_import_field_group( $field_group ) {
479	return acf_import_internal_post_type( $field_group, 'acf-field-group' );
480	}
481
482	/**
483	* Returns an array of tabs for the field group settings.
484	* We combine a list of default tabs with filtered tabs.
485	* I.E. Default tabs should be static and should not be changed by the
486	* filtered tabs.
487	*
488	* @since ACF 6.1
489	*
490	* @return array Key/value array of the default settings tabs for field group settings.
491	*/
492	function acf_get_combined_field_group_settings_tabs() {
493	$default_field_group_settings_tabs = array(
494	'location_rules' => __( 'Location Rules', 'secure-custom-fields' ),
495	'presentation' => __( 'Presentation', 'secure-custom-fields' ),
496	'group_settings' => __( 'Group Settings', 'secure-custom-fields' ),
497	);
498
499	$field_group_settings_tabs = (array) apply_filters( 'acf/field_group/additional_group_settings_tabs', array() );
500
501	// remove any default tab values from the filter tabs.
502	foreach ( $field_group_settings_tabs as $key => $tab ) {
503	if ( isset( $default_field_group_settings_tabs[ $key ] ) ) {
504	unset( $field_group_settings_tabs[ $key ] );
505	}
506	}
507
508	$combined_field_group_settings_tabs = array_merge( $default_field_group_settings_tabs, $field_group_settings_tabs );
509
510	return $combined_field_group_settings_tabs;
511	}
512
513	/**
514	* Checks if a field group has the provided location rule.
515	*
516	* @since ACF 6.2.8
517	*
518	* @param integer $post_id The post ID of the field group.
519	* @param string $location The location type to check for.
520	* @return boolean
521	*/
522	function acf_field_group_has_location_type( int $post_id, string $location ) {
523	if ( empty( $post_id ) \|\| empty( $location ) ) {
524	return false;
525	}
526
527	$field_group = acf_get_field_group( (int) $post_id );
528
529	if ( empty( $field_group['location'] ) ) {
530	return false;
531	}
532
533	foreach ( $field_group['location'] as $rule_group ) {
534	$params = array_column( $rule_group, 'param' );
535
536	if ( in_array( $location, $params, true ) ) {
537	return true;
538	}
539	}
540
541	return false;
542	}
543
544
545	/**
546	* Retrieves the field group title, or display title if set.
547	*
548	* @since ACF 6.6
549	*
550	* @param array\|integer $field_group The field group array or ID.
551	* @return string The field group title.
552	*/
553	function acf_get_field_group_title( $field_group ): string {
554	if ( is_numeric( $field_group ) ) {
555	$field_group = acf_get_field_group( $field_group );
556	}
557
558	$title = '';
559	if ( ! empty( $field_group['title'] ) && is_string( $field_group['title'] ) ) {
560	$title = $field_group['title'];
561	}
562
563	// Override with the Display Title if set.
564	if ( ! empty( $field_group['display_title'] ) && is_string( $field_group['display_title'] ) ) {
565	$title = $field_group['display_title'];
566	}
567
568	// Filter and return.
569	return apply_filters( 'acf/get_field_group_title', esc_html( $title ), $field_group );
570	}
571