Front End Forms

Purpose

Front-end forms allow you to display back-end fields in the front-end. Because of their internal mechanism, front-end forms will only display containers, which are already available in the back-end. This makes them very useful for front-end editing, however they are not recommended for usage as contact forms.

Usage

The display of forms is handled by this pair of functions:

• uf_head does most of the heavy lifting, including the loading and preparation of containers, as well as saving the data.
• uf_form simply displays the form in the needed place.

Here is how a very basic structure would look like:

<?php
uf_head(array(
    // Arguments and settings here
));

get_header();

    uf_form();

get_footer()

uf_head

The duties of this function include:

• Loading the item, which is to be edited
• Loading and filtering of all the containers, which are associated with the item
• Enqueueing scripts and styles
• Saving data when needed
• Redirecting to the proper page after the data has been saved.

The function also receives an array of arguments, which control the behaviour of the form. Please refer to the Settings section below.

uf_form

The uf_form function does not accept any arguments and simply displays the form, already prepared by uf_head.

Settings

By default uf_head will determine what object/item (post, term, user and etc.) is being displayed and will load all containers associated with that object automatically.

The following settings allow you to adjust what is being displayed.

Argument	Type	Description
containers	string[]	A list of containers IDs, which are to be included in the form. When this argument is used, the form will not attempt to load containers automatically.
exclude_containers	string[]	A list of containers to exclude. This only applies when containers is empty and containers have been autoloaded.
item	mixed	The item, which is to be edited. See Items below
create_new	mixed	Indicates if a new object must be created. See Creating new items below.
save_arguments	mixed	Holds additional arguments arguments for creating new items. Those will be supplied to functions like wp_insert_post, wp_insert_term and etc.
item_fields	mixed	Controls what object-native fields to be shown. Can be either string 'all' on an array of fields to show. See Item Fields below.
labels	string[]	Provides additional labels. See Labels below.
exclude_fields	mixed[]	This is an array of fields which should not be visible in the front-end. You can use both IDs here or actual fields.
include_fields	mixed[]	This is an array of fields which should be visible int he front-end. Once you give values here, those will be the only fields that would be shown.
redirect_to	mixed[]	Indicates where to redirect the user to after submitting a form. See Redirection below.

Example:

uf_head(array(
    'item' => 'post_5',
    'labels' => array(
        'save'          => 'Update post',
        'success_title' => 'The post was successfully updated.'
    )
));

There are more examples at the end of this article.

Items

The item argument in the $args array specifies which item should be edited. For most objects, this works exactly like the $type argument for value functions (the_value, get_value, etc.).

If you are using the create_new argument this one will be ignored!

Type	Keyword(s)	Example
Posts	post or the slug of a post type	"post_5"
Terms	term or the slug of a taxonomy	"term_6"
Users	user	"user_6"
Comments	comment	"comment_8"
Options	options	"options"

As you can see, all items expect a slug, as well as an identifier. Options is the only exception, as no IDs are needed there.

Creating new items

The front-end forms in Ultimate Fields can let users edit existing items, as well as create new ones. To allow a new item to be created, please use the create_new argument.

The argument expects the same keyword as item above, but without an ID, ex:

'create_new' => 'page'

When creating new items, you can also use the save_arguments argument of uf_head. The values in the argument would be merged with the data entered in the form when wp_insert_post or similar is being called.

Item fields

Ultimate Fields can display both user-created fields, as well as some presets. Presets are different for each item type and represent built-in WordPress field, which can automatically be displayed in the form.

Those fields can be used as strings in the item_fields array.

Posts	Terms	Users	Comments	Options
post_title	name	first_name	comment_content	No fields available
post_content	description	last_name	comment_author
		nickname	comment_author_email
		email	comment_author_url
		password
		url
		description

Example:

uf_head(array(
    // Show the post title, but skip the content
    'item_fields' => array( 'post_title' )
));

Labels

You can modify the following labels for the labels argument.

Label	Purpose	Default value
save	The text of the save button	Save
success_title	The message, indicating that data has been saved.	Your data is now saved.

Redirection

Possible options for the redirect_to parameter:

• A boolean false would redirect back to the URL of the current page.
• "item" as a string will be redirect to the edited or newly created item.
• Any other string will be considered a URL.

Displaying multiple forms

Front-end forms are handled by the Ultimate_Fields\Form class. Using uf_head and uf_form as functions works with a single instance of the class. If you need to work with multiple forms simultaneously, you can directly use the class.

The process is as follows:

1. Create a new form
2. Use $form->head() before calling get_header
3. Use $form->form() in the place where you need to display the form.

You should supply the needed arguments when creating the form. $form->head() and $form->form() do not require any.

<?php
use Ultimate_Fields\Form;

// Create the forms
$first_form = new Form(array(
    'containers' => array( 'page-content' )
));
$second_form = new Form(array(
    'containers' => array( 'page-settings' )
));

// Save & setup
$first_form->head();
$second_form->head();

// Include the standard template
get_header();

    // Display the forms
    $first_form->form();
    $second_form->form();

get_footer();

Access control

Ultimate Fields will display forms and save their values without any sort of access control: As long as an user can open a page with a form, they can see the form and enter data in it.

This leaves you, as the developer, responsible for the implementation of an access control method. While doing so, please ensure that it is not just uf_form that you are protecting, but also uf_head. This is very important, because uf_head if the function, which will save data when given.

Example configurations

Below you will find multiple examples of arguments, useful in various scenarios. Those are the arguments for the uf_head() function or the constructor of Ultimate_Fields\Form.

<?php
/**
 * Edit the currently displayed item with default arguments
 */
$args = array(
    // Nothing needed here
);

/**
 * Create a new page and redirect back to it.
 * The only field displayed for the page will be its title.
 */
$args = array(
    'create_new'  => 'page',
    'item_fields' => 'post_title',
    'redirect_to' => 'item'
);

/**
 * Edit the current item but skip the "privacy-settings"
 */
$args = array(
    'exclude_containers' => 'privacy-settings'
);

// Call the head function with any arguments set from above
uf_head( $args );

// Use the standard template
get_header();

    // Display the actual form
    uf_form();

get_footer();