cafe_dynamic_form()
Purpose
Shows a dynamic form on the front end: a form that creates a post, or edits a post, user, term or the global options, with the fields of CAFE field groups. Rendering, validation and saving use the same field engine as the edit screens: the form adds no second field system.
Guide: CAFE Forms.
Syntax
cafe_dynamic_form( string|array $form ): void
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
$form |
string|array | - | The ID of a form registered with cafe_register_dynamic_form(), or the form arguments below. Arguments with the ID of a registered form add to (and override) its registered arguments. |
Form arguments:
| Argument | Type | Default | Description |
|---|---|---|---|
id |
string | Required | Form ID: lowercase letters, digits, - and _. Used in hooks, CSS classes and the nonce. |
field_groups |
string[] | [] |
Keys of the field groups to show (active groups only), in this order. |
fields |
string[] | [] |
Extra top-level fields, by key or name. |
object_type |
string | "post" |
"post", "user", "term" or "option". |
object_id |
int|string | 0 |
Object to edit. "current_user" for the signed-in user. 0 with post = create a post. |
mode |
string | derived | "create" or "edit". Only posts can be created. |
post_type |
string | "post" |
Post type of created posts (edit forms use the post's own type). |
taxonomy |
string | derived | Taxonomy of a term form (derived from the term when editing). |
post_fields |
string[] | [] |
WordPress post fields shown in the form: title, content, excerpt. |
post_terms |
string[] | [] |
Taxonomies shown as checkboxes (only those registered for the post type). |
post_status |
string | "pending" |
Status of created posts: draft, pending, publish or private. People who may not publish always get pending. |
submit_label |
string | "Submit" / "Save changes" | Button text. |
success_message |
string | "Thank you, your submission was received." / "Your changes were saved." | Shown after saving (plain text). |
redirect |
string | "" |
Where to go after saving. {object_id} is replaced with the saved object's ID. Only this site or hosts allowed by allowed_redirect_hosts. |
ajax |
bool | true |
true: sent in the background with fetch (WordPress api-fetch, no jQuery), messages appear without reloading. false: a normal form post with a page reload. Without JavaScript the form always works the normal way. |
label_placement |
string | the group's | "top" or "left". |
capability |
string | "" |
Capability people need to use the form, on top of the usual rights (creating the post type, editing the object). |
intro_html |
string | "" |
Text shown above the fields, only in this form (e.g. a heading and an explanation). HTML allowed like in posts (wp_kses_post()); paragraphs are added automatically. |
footer_html |
string | "" |
Text shown below the fields, above the button (e.g. a privacy note). Same HTML rules. |
css_class |
string | "" |
Extra CSS classes on the <form> element, separated by spaces (e.g. "property-form is-wide"). Each is cleaned with sanitize_html_class(); at most 10. |
allow_guests |
bool | false |
Create forms only: visitors who are not signed in may use the form. Their posts are always pending. |
Return value
None. The form HTML is printed. People who may not use the form see a short message instead of the form. Problems in the arguments are shown only to people who manage CAFE; others see nothing.
Example
// A form that creates "event" posts for review.
cafe_dynamic_form( [
'id' => 'new-event',
'field_groups' => [ 'group_event_details' ],
'post_type' => 'event',
'post_fields' => [ 'title', 'content' ],
'post_terms' => [ 'event_category' ],
'submit_label' => 'Send event',
'redirect' => home_url( '/thank-you/?event={object_id}' ),
] );
// A profile form for the signed-in user.
cafe_dynamic_form( [
'id' => 'my-profile',
'field_groups' => [ 'group_profile' ],
'object_type' => 'user',
'object_id' => 'current_user',
] );
Notes
- The form settings travel with the form as a signed token: the browser cannot change the fields, the object or the redirect.
- Every submission is checked on the server: who may use the form, the
form's nonce, each field's validation, the
cafe_dynamic_form_validatehook. Nothing is saved unless everything is valid. - Media fields are only shown to people who may upload files.
- Conditional logic is not evaluated in dynamic forms yet (it is not evaluated on edit screens either).
- See also
cafe_get_dynamic_form(),cafe_register_dynamic_form()andcafe_submit_dynamic_form().