Usage Documentation for Wenprise Forms – A WordPress Form Library Based on Nette Forms

WordPress has never provided a sufficiently convenient form generation class for developers. In WordPress theme development, creating forms is often an essential task. To improve development efficiency and increase the quality of WordPress theme and plugin projects, we developed a WordPress form generation library based on the Nette Forms library — Wenprise Forms.

Wenprise Forms provides a fluent API, supporting web form generation, backend validation, frontend validation, operations like showing or hiding based on form options, and integration with WordPress, supporting advanced features like random number validation, color picking, visual editors, Ajax uploads, and more.

The Git repository address for Wenprise Forms is: https://github.com/iwillhappy1314/wenprise-forms. Interested friends are welcome to participate in development; you can also submit issues on GitHub if you encounter problems while using it.

Wenprise Forms Installation

Wenprise Forms has been published on Packagist. If you already use Composer to manage your theme or plugin dependencies, you can directly run the following command to install it:

composer require wenprise/forms

If you’re not using Composer yet, we recommend using it to manage your project dependencies. Currently, Wenprise Forms doesn’t provide an entry file for direct inclusion, and won’t support it in the future.

Wenprise Forms Quick Start Guide

Use the following code on the page where you need to display the form. This will add a form with a POST action, containing a “First Name” field and a save button. After successful form submission, the submitted content will be displayed directly on the page.

use WenpriseFormsForm;

$form = new Form;

// Set the form rendering method; you can set a custom rendering method based on your frontend framework
wprs_form( $form );

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

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

// Validate form and display form values
if ( $form->isSuccess() ) {

    // Get the form values submitted from the frontend
    $values = $form->getValues();

    // Access form values via class properties
    $first_name = $values->first_name;

    echo $first_name;
}

echo $form;

Wenprise Forms Methods

Wenprise Forms contains many convenient form methods that can be used to set various attributes of the form, briefly introduced below. In addition to those introduced below, there are some advanced form methods; since they aren’t commonly used, they won’t be detailed here. Interested friends please refer to the source code for usage.

// Set the URL to receive form submission
$form->setAction('/submit.php')

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

$form->addText('first_name', esc_html__('First Name', 'wprs'))
     ->setRequired(false) // Set as required
     ->setValue()  // Set form value
     ->setDefaultValue('') // Set default value
     ->setDisabled(true)  // Set disabled attribute
     ->setOmitted()    // Ignore this item upon submission
     ->addRule() // Add validation rule
     ->setAttribute('data-cond', [name=street] == magic) // Set visibility based on other field input
     ->setHtmlType(); // Set the HTML type of the text field, e.g., number

// Determine if form submission was successful; only returns true if all items pass validation
$form->isSuccess();

// Get form submission values; returning an object, access via property
$values = $form->getValues();

Usage Methods for Various Form Types

Text Field

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

Textarea

$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'));

Multi-file 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'));

Form upload fields need backend support; refer to the following Ajax backend example:

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');
    require_once(ABSPATH . 'wp-admin/includes/media.php');

    $attachment_id = media_handle_upload('file', 0);

    $thumb_url  = wp_get_attachment_thumb_url($attachment_id);
    $origin_url = wp_get_attachment_url($attachment_id);

    $thumb = get_post($attachment_id);

    $file_data = [
        'id'       => $attachment_id,
        'original' => $thumb->post_title,
        'size'     => $thumb->size,
        'state'    => 'SUCCESS',
        'title'    => $thumb->post_title,
        'type'     => $thumb->post_mime_type,
        'thumb'    => $thumb_url,
        'url'      => $origin_url,
    ];

    wp_send_json($file_data, 200);

    return false;
});

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

Implemented using the jQuery Chosen plugin; parameters for the Chosen plugin can be set in the last array.

$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

Adds a WordPress random number (nonce) validation; automatically validates this field upon form submission, no separate validation required.

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

WordPress Visual Editor

Implemented using the built-in WordPress wp_editor function; modify the component’s behavior via the last array.

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

Number Range Slider

Implemented using Ion.RangeSlider; set behavior for this jQuery plugin in the last array.

$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 Submit Field

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

Signature Field

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

Signature-generated images are submitted via Base64 encoding. Upon backend saving, you can save to the database or as a file as needed.

This library can be used when developing WordPress custom fields, custom settings pages, and custom widgets, which is very convenient. We’ve used it in multiple projects with excellent client feedback; interested friends can give it a try. Of course, if you have questions or suggestions, welcome to bring them up in the comments.