Download the PHP package digitalnodecom/larafields without Composer

Abstract Form Maker

A flexible form maker package that allows you to define custom form groups for WordPress posts and taxonomies.

Installation

You can install this package with Composer:

After installation, you need to:

1. Clear the Acorn cache:

This step is necessary for the package to be recognized by Acorn.

2. Publish the package assets and configuration:

3. Run the database migrations:

4. Build the JavaScript and CSS assets:

This step compiles the JavaScript and CSS files needed for the package to function properly.

4. Add the following hooks to your current theme's functions.php file.

5. Clear the cached views

Configuration

Form groups are defined in the config/larafields.php file. Each form group can be configured to display on specific post types or taxonomies.

Basic Structure

Core Concepts

The package uses several key terms throughout its configuration and API:

Object Types and Names

• object_type: Defines the WordPress entity type where fields can be attached. Can be one of:

  • post_type: For WordPress posts and custom post types
  • taxonomy: For categories, tags, and custom taxonomies
  • user: For WordPress user profiles
  • settings: For option pages, term option pages, and user option pages

• object_name: The specific identifier within an object type. Examples:

  • For post_type: Could be "post", "page", "product", or any custom post type name
  • For taxonomy: Could be "category", "post_tag", "product_cat", or any custom taxonomy name
  • For user: Always null
  • For settings: The slug of the options page, term options page, or user options page
• object_id: The unique identifier for a specific instance:
  • For posts: The post ID
  • For taxonomies: The term ID
  • For users: The user ID
  • For settings pages: The page slug

These concepts are used throughout the package's API and configuration to precisely target where fields should be displayed and how data should be stored and retrieved.

Display Conditions

You can display form groups on any Post Type, any Term, and/or create a custom Options page:

Post Type Display

This will display the form group on the specified post type's edit screen in the WordPress Admin dashboard.

Taxonomy Display

This will display the form group on the specified taxonomy's term edit screen in the WordPress Admin dashboard.

Options Page Display

This will create a new page in the WordPress Admin dashboard with the specified title and menu entry. The form group will be rendered on this custom options page.

Term Option Page Display

This will add an action link (alongside Edit, Quick Edit, Delete, View) on the taxonomy overview page. When clicked, it opens a custom page where the form group will be rendered, with the data being related to both the selected term and taxonomy.

User Profile Display

This will display the form group on the user's "Edit Profile" page in the WordPress Admin dashboard.

User Page Display

This will add an action link (alongside Edit, Delete, and other user actions) on the Users overview page. When clicked, it opens a custom page where the form group will be rendered for the selected user.

Available Field Types

Text Field

Simple text input with optional character limit.

Date Field

Date picker input field.

DateTime Field

Date and time picker input field.

Week Field

Week picker input field.

Month Field

Month picker input field.

File Field

File upload field with image preview support. Files are stored in the default disk under the 'larafields' directory.

Textarea Field

Multiline text input with optional character limit.

Number Field

Numeric input with optional min/max values.

Multiselect Field

Dropdown field that allows selecting multiple options.

When custom_values is set to true, users can enter and select values that are not predefined in the options list. This is useful when you want to allow for flexible input while still providing common options.

Repeater Field

Group of fields that can be repeated multiple times.

Repeater Field Validation

The package includes a validation system that allows you to enforce data integrity rules on your form fields, including unique validation within repeater fields.

Unique Within Repeater Validation

You can ensure that values within a repeater field are unique by adding validation rules to your field schema. This is particularly useful for fields like categories, IDs, or names that should not be duplicated within the same repeater.

Validation Features

• Case-insensitive comparison: "Test" and "test" are considered duplicates
• Whitespace trimming: Leading and trailing spaces are ignored during comparison
• Empty value handling: Empty values are ignored (required validation handles empty fields separately)
• Error display: Validation errors appear below each field in red text
• Form submission prevention: Forms with validation errors cannot be submitted until fixed

Validation Rules

The validation system supports the following rules:

• unique_within_repeater: Ensures the value is unique within the current repeater field
• unique_message: Custom error message to display when uniqueness validation fails
• required: Field must have a value (existing functionality)
• characterLimit: Maximum number of characters allowed (existing functionality)

• Adding Field Groups Programmatically

You can programmatically add new field groups using the FormMaker::add_group() method. This can be added to an action hook in your theme or plugin:

The structure follows the same format as defined in the configuration file, allowing you to specify labels, settings, and fields for your new group.

Retrieving Field Data Programmatically

You can fetch field data from the database using the FormMaker::get_field() method. This method accepts three optional parameters:

At least one of these parameters must be provided:

• $fieldKey: The specific field key to retrieve
• $objectName: The name of the object type (e.g., 'product', 'category')
• $objectId: The ID of the object

The method will throw an Exception if none of these parameters are provided.

Example usage:

Extending Fields

You can modify or manipulate the existing fields using the larafields_load_fields WordPress filter. This filter provides access to the fields collection before it's processed:

Dashboard Menu Pages

You can add custom dashboard menu pages using the larafields_load_pages filter. This allows you to create additional admin pages for your application.

Adding Dashboard Menu Pages

Use the larafields_load_pages filter to add new pages to the WordPress admin dashboard:

JavaScript Bundling

This package uses webpack to bundle JavaScript dependencies. The main JavaScript dependency is tom-select, which is used for the multiselect field type.

Development

To work on the JavaScript files:

1. Make changes to the JavaScript files in the resources/js directory
2. Run npm run dev to watch for changes and automatically rebuild the JavaScript files

Production

To build the JavaScript files for production:

1. Run npm run build to build both CSS and JavaScript files
2. The bundled JavaScript file will be available at resources/js/public/larafields.js
3. The tom-select CSS file will be available at resources/js/public/css/tom-select.css

API Documentation

The package provides REST API endpoints for querying and updating forms and their data.

Query Endpoint

Authentication

The API uses Basic Authentication with WordPress Application Passwords:

• Username: Your WordPress username
• Password: Generated Application Password key

Request Body Parameters

The endpoint accepts the following parameters in the request body:

*At least one of these parameters must be provided.

Field Validation

The API implements the following validation rules:

• object_id: Required if neither object_name nor field_key is provided
• object_name: Required if neither object_id nor field_key is provided
• field_key: Required if neither object_id nor object_name is provided

This means you must provide at least one of these three parameters in your request.

Query Examples

Query by Object ID

This will return all form data associated with the object ID 123.

Query by Object Name

This will return all form data associated with the object type "product".

Query by Field Key

This will return the specific field data for the field key "product_gender".

Combined Query

This will return form data that matches both the object ID 123 and object type "product".

Update Endpoint

Authentication

The API uses Basic Authentication with WordPress Application Passwords (same as the Query Endpoint).

Request Body

The request body should be a JSON object with the following properties:

Example Request

Response

A successful update will return a JSON response with status 'ok':

Complete Examples

Post Type Form Group

Taxonomy Form Group