Wenprise Forms Documentation: A WordPress Form Library Built on Nette Forms

WordPress has never offered developers a particularly convenient built-in form builder. But in theme and plugin development, form creation is often unavoidable. To improve development efficiency and project quality, we built a WordPress form library on top of Nette Forms called Wenprise Forms.

Wenprise Forms provides a fluent API and supports form rendering, back-end validation, front-end validation, conditional field display, and a range of WordPress-specific features such as nonce verification, color pickers, visual editors, and Ajax uploads.

The GitHub repository is https://github.com/iwillhappy1314/wenprise-forms. If you are interested, feel free to contribute or open issues there.

Install Wenprise Forms

Wenprise Forms is published on Packagist. If your theme or plugin already uses Composer, install it with the following command:

composer require wenprise/forms

If you are not using Composer yet, we strongly recommend adopting it for dependency management. Wenprise Forms does not provide a separate non-Composer entry-file installation mode, and that is not planned for the future.

Quick start with Wenprise Forms

Use code like the following on a page where the form should be rendered. This example creates a POST form with a first_name field and a submit button, then displays the submitted data after a successful submission.

use WenpriseFormsForm;

$form = new Form;

// Set the rendering strategy.
wprs_form( $form );

// Set the form method.
$form->setMethod( 'POST' );

// Add fields.
$form->addText( 'first_name', esc_html__( 'First Name', 'wprs' ) );
$form->addSubmit( 'send', esc_html__( 'Save', 'wprs' ) );

Wenprise Forms methods

Wenprise Forms includes a number of convenient methods for configuring form behavior and attributes. The examples below cover the most common ones. There are additional advanced methods in the source code if you need more specialized behavior.

// Set the form action URL.
$form->setAction( '/submit.php' );

// Set the request method.
$form->setMethod( 'POST' );

$form->addText( 'first_name', esc_html__( 'First Name', 'wprs' ) )
     ->setRequired( false )      // Mark the field as optional or required.
     ->setValue()                // Set the current field value.
     ->setDefaultValue( '' );    // Set the default field value.

Field type examples

Text field

$form->addText( 'age', esc_html__( 'Age:', 'wprs' ) );

Textarea field

$form->addTextArea( 'note', esc_html__( 'Note:', 'wprs' ) );

Email field

$form->addEmail( 'email', esc_html__( 'Email:', 'wprs' ) );

Integer field

$form->addInteger( 'level', esc_html__( 'Level:', 'wprs' ) );

Upload field

$form->addUpload( 'thumbnail', esc_html__( 'Thumbnail:', 'wprs' ) );

Multiple upload field

$form->addMultiUpload( 'files', esc_html__( 'Files', 'wprs' ) );

Ajax file upload field

$form->addAjaxUpload( 'files', esc_html__( 'Files', 'wprs' ) )
      ->setAttribute( 'data-url', home_url( 'wp-admin/admin-ajax.php?action=wprs_upload' ) );

Ajax upload fields also need server-side support. A simplified Ajax handler can look like this:

add_actions( ['wp_ajax_wprs_upload', 'wp_ajax_nopriv_wprs_upload'], function () {
    if ( ! is_user_logged_in() ) {
        return false;
    }

    require_once( ABSPATH . 'wp-admin/includes/image.php' );
    require_once( ABSPATH . 'wp-admin/includes/file.php' );
} );

Hidden field

$form->addHidden( 'userid' );

Checkbox field

$form->addCheckbox( 'agree', esc_html__( 'I agree with terms', 'wprs' ) );

Radio field

$form->addRadioList( 'gender', esc_html__( 'Gender:', 'wprs' ), [ 'm' => 'male', 'f' => 'female' ] );

Checkbox list field

$form->addCheckboxList( 'colors', esc_html__( 'Colors:', 'wprs' ), [ 'r' => 'red', 'g' => 'green', 'b' => 'blue' ] );

Select field

$form->addSelect( 'country', esc_html__( 'Country:', 'wprs' ), $countries );

Chosen select field

This uses the jQuery Chosen plugin. The last array argument can be used to pass Chosen options.

$form->addChosen( 'chosen', esc_html__( 'Chosen', 'wprs' ), ['aaaa', 'bbbb'], [] );

Multi-select field

$form->addMultiSelect( 'options', esc_html__( 'Pick many:', 'wprs' ), $options );

Chosen multi-select field

$form->addMultiChosen( 'chosen2', esc_html__( 'Multi chosen', 'wprs' ), ['aaaa', 'bbbb'], [] );

Password field

$form->addPassword( 'password', esc_html__( 'Password:', 'wprs' ) );

Button field

$form->addButton( 'raise', esc_html__( 'Raise salary', 'wprs' ) );

WordPress nonce field

This adds a WordPress nonce. The form will validate it automatically on submission, so no additional nonce handling is needed in the usual flow.

$form->addCsrf( 'post-form', esc_html__( 'Nonce invalidate', 'wprs' ) );

WordPress visual editor

This uses WordPress’s built-in wp_editor() support, and the final array can be used to customize the behavior.

$form->addEditor( 'post_extra', esc_html__( 'Extra content', 'wprs' ), [] );

Range slider

This field type is powered by Ion.RangeSlider, and the last array can be used to customize that jQuery plugin.

$form->addEditor( 'price', esc_html__( 'Price', 'wprs' ), [] );

Date picker

$form->addDatePicker( 'date', esc_html__( 'Date', 'wprs' ), [] );

Color picker

$form->addColorPicker( 'color', esc_html__( 'Color', 'wprs' ), [] );

Submit field

$form->addSubmit( 'submit', esc_html__( 'Register', 'wprs' ) );

Image button field

$form->addImage( 'submit', '/path/to/image' );

Signature field

$form->addSignature( 'signature', esc_html__( 'Signature', 'wprs' ) );

The generated signature image is submitted as Base64 data. On the back end, you can store it in the database or save it as a file depending on the project.

This library is very handy for building WordPress custom fields, custom settings pages, and custom widgets. We have already used it in multiple projects with good feedback from clients. If you try it and have suggestions or problems, feel free to raise them.