OForms v1.2.0

Plugin constants

OForms\Core\Plugin

Singleton. Entry point called from oforms.php. boot() loads the text domain, runs DB migration, registers shortcode/submission/queue/REST, registers the Gutenberg block, boots the admin menu if is_admin(), then fires do_action('of_loaded').

PHPPlugin::get_instance()->boot();

OForms\Core\DB

Static $wpdb wrapper. All methods prepend {prefix}of_ to the table name automatically.

PHPDB::insert('entries', ['form_id' => 1, 'data' => '{}']);
DB::update('entries', ['status' => 'read'], ['id' => 42]);
DB::delete('entries', ['id' => 42]);
DB::get_row('forms', ['id' => 1]);
DB::get_results('entries', ['form_id' => 1], 'id DESC');

OForms\Forms\FormRepository

PHP$repo = new FormRepository();
$repo->all(200);
$repo->get(int $id);
$repo->get_fields(int $id);
$repo->create(string $name, array $settings): int
$repo->update(int $id, string $name, array $settings): void
$repo->save_fields(int $form_id, array $fields): void  // replaces all fields
$repo->delete(int $id): void
$repo->duplicate(int $id): int  // clones form + fields, appends " (Copy)"

OForms\Entries\EntryRepository

PHP$repo = new EntryRepository();
$repo->get(int $id);
$repo->for_form(int $form_id, int $limit, int $offset, string $status, string $search): array
$repo->count_for_form(int $form_id, string $status, string $search): int
$repo->create(int $form_id, array $data): int|false
$repo->update_status(int $id, string $status): void  // new|read|starred|spam|trash
$repo->update_email_status(int $id, string $status): void
$repo->delete(int $id): bool
$repo->get_stats_by_day(int $form_id, int $days = 30): array  // [{day, total}, ...]
$repo->export_csv(int $form_id): void  // streams CSV and exits

Field config JSON

JSON · of_form_fields.config{
  "label":              "Your Name",
  "placeholder":        "e.g. Jane Smith",
  "default":            "",
  "required":           true,
  "validation_message": "Please enter your full name.",
  "options":            ["Option A", "Option B"],
  "min":                0,
  "max":                100,
  "step":               1,
  "accept":             "jpg,png,pdf",
  "max_size":           2097152,
  "stars":              5,
  "heading_level":      "h3",
  "html_content":       "<p>Some <strong>HTML</strong></p>",
  "condition": {
    "field":    "42",
    "operator": "equals",
    "value":    "yes"
  }
}

Shortcode

[oform id="42"]

Renders the form, enqueues form-v1.css and form-v1.js, and localises ofData to JS with the form's settings. The only parameter is id (required, form ID).

Gutenberg block

Block name: oforms/embed, registered via blocks/oforms-embed/block.json. The editor shows a SelectControl dropdown of all forms. Output is server-side rendered via do_shortcode('[oform id="X"]'); the save() function returns null.

How it works

Progress bar classes

• Active step label: .of-step-label--active
• Completed steps: .of-step-label--done (green)
• Fill width updates proportionally to current step

Supported operators

JS behaviour

On any change input event, all conditional fields are re-evaluated. Hidden fields get class .of-field--hidden and their inputs are disabled, preventing submission of hidden data. Validation also skips .of-field--hidden fields.

Entry data format

Stored in of_entries.data as JSON. Internal keys (prefixed with _) are hidden from the receipt and entry view but stored for workflow use.

JSON{
  "42": { "label": "Your Name",  "value": "Jane Smith" },
  "43": { "label": "Email",      "value": "jane@example.com" },
  "44": { "label": "Topics",     "value": ["Support", "Billing"] }
}

Save & continue

Endpoint: admin-ajax.php?action=of_save_partial (logged-in or nopriv). Body: form_id, resume_token (optional), current_step, field_data (JSON). Returns the resume token. Resuming via ?of_resume=token rehydrates the form.

Abandonment capture

Endpoint: admin-ajax.php?action=of_log_abandonment. Fires on visibilitychange when the user leaves with at least one field touched. Stored with type = 'abandoned' for funnel analysis. Both partial and abandoned rows are pruned by the of_process_queue cron handler when expires_at passes.

Condition types

Action types (11)

Delayed actions

Any action can have a delay_seconds value. Delayed actions are stored in wp_of_queue and processed by the of_process_queue cron event, which fires every minute via the of_every_minute custom schedule. Failed actions retry up to 5 times with exponential backoff.

Signing

If a secret is set on the subscription, the dispatcher computes hash_hmac('sha256', $payload, $secret) and sends it in the X-OForms-Signature header. Receivers should reject any payload that fails to verify with hash_equals().

REST management

CRUD via /wp-json/of/v1/webhooks. Test a wired endpoint with POST /webhooks/{id}/test; the dispatcher fires a synthetic payload and returns the receiver's response code and latency.

Status flow

Every entry moves through a lifecycle of statuses, shown as tabs across the top of the Entries list.

Filtering, search & bulk actions

Filter by status using the tab links. Full-text search via LIKE %query% on the data column. Both can be combined. Bulk actions: Mark as Read, Mark as Spam, Delete (hard-delete from database).

Setup

1. Go to OForms → Settings
2. Enable reCAPTCHA v3
3. Enter your Site Key and Secret Key from google.com/recaptcha

How it works

of_forms

of_form_fields

of_entries

of_workflows & of_queue

of_partial_entries

of_webhook_subscriptions

of_views

One row per form impression for conversion analytics: form_id, variant (a / b for split tests), session_id, ip_address, device_type, country, created_at. Joined with of_entries by form_id + date window to compute conversion rate.

of_email_queue

of_api_keys

Authenticates REST calls without a logged-in admin cookie. Columns: name, api_key (UNIQUE, prefixed ofk_), created_at, last_used. Rotate keys from Settings; revoking deletes the row.

Actions

Filters

Custom workflow action via hook

PHPadd_action('of_workflow_action', function($type, $action, $entry_id, $data) {
    if ($type !== 'my_custom_action') return;
    // do something with the entry data
}, 10, 4);

OMailer integration

OForms detects OMailer by checking if omailer_subscribe() is defined. No explicit plugin dependency; if OMailer is not active, the subscribe_omailer action silently no-ops.

PHP · OMailer function signatureomailer_subscribe(int $list_id, string $email, string $name = ''): void

Global settings (wp_options key: of_settings)

Other wp_options keys

Per-form settings (of_forms.settings JSON)

Adding a custom field type

1. Add your type slug to the $field_types array in form-edit.php
2. Add a rendering case in form-render.php (switch($type) block)
3. Add a config UI case in appendField() in admin-v1.js
4. Add serialisation logic in the form editor submit handler in admin-v1.js
5. Add any validation logic in validateField() in form-v1.js

Adding a custom form theme

1. Add your theme slug to $allowed in form-render.php
2. Add .of-theme--{slug} CSS rules to form-v1.css
3. Add the option to the theme <select> in form-edit.php

Adding a custom workflow action

1. Add a case in WorkflowEngine::run_action()
2. Add the option to the <select> in workflow-edit.php
3. Handle the action config UI in appendAction() in admin-v1.js
4. Handle serialisation in the workflow editor submit handler in admin-v1.js