=== CustomFields ===
Contributors: customfields
Tags: custom fields, metadata, field groups, content modeling, json
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.9.0-beta.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Build structured content, relationships, blocks, listings and frontend forms. Local content tools are included in Free.

== Description ==

CustomFields Free is a complete local content-building toolkit for WordPress, currently in beta. No account or licence is needed.

* Consistent workspace navigation, searchable tool finder and optional guidance from fields to a private preview of real saved content.
* Read-only local CSV comparison with supported row outcomes, manual editor links and issue export.
* On-demand content checks, resumable scopes and read-only field-group baseline comparisons; coverage and unsupported fields stay visible.
* Visual Field Studio: starter kits, searchable types, focused editing, live sample forms, duplication, ordering, undo and keyboard saving.
* Twenty primitive, media and reference types, plus structured groups, repeaters, ordered galleries, flexible layouts, reusable groups and searchable relationships.
* Nested conditions and rich-text editing, with identity-aware preservation of hidden row values.
* Post, user, term and named site-options locations; delegated options-page permissions.
* Visual custom post type and taxonomy creation.
* Searchable multiple post/user/term references and maintained inverse relationships.
* Snapshot reusable definitions or linked definitions with reviewed compatible propagation.
* Logged-in frontend editing and creation of owned drafts.
* Custom block authoring with configurable controls, plus native field output blocks and bindings.
* Visual public listings with registered-field filters, sorting, search, pagination and responsive layouts.
* Elementor field and listing widgets. A dynamic tag is available where Elementor supports dynamic tags.
* Native metadata by default; optional dedicated-table storage with a synchronized metadata compatibility mirror.
* PHP helpers, authenticated post-field REST integration and WP-CLI schema commands.
* JSON import/export, reviewed two-way local definition-file synchronization, schema history and guarded restoration.
* Reviewed content-copy workflows and supported ACF/Secure Custom Fields/Meta Box value conversions, with source preservation and rollback.
* Post-value revisions and per-user recovery drafts.

CustomFields Pro adds reviewed CSV updates, public/member submission forms with private approval, deployment packages, content/media transfers and approved background bulk editing, plus optional private updates/support. Saved business rules, maintenance history and assigned content-change reviews also belong to Pro. Local content features remain in Free when Pro is disconnected or removed.

= Are the new checks useful without Pro? =

Yes. Compare a supported CSV, review every row outcome, export its findings and edit records manually. Content checks expose all supported findings in the captured scope, including required-value, configured-choice and known-reference problems. Continue through further scopes without upgrading. Baseline comparisons explain supported definition differences and bounded retained-value counts; external templates and unsupported fields are explicitly outside coverage. These tools do not write content.

= Does the optional guide publish anything or collect usage data? =

No. Your next step displays real permitted saved values privately and leaves publication to you. Goal/task preferences remain local to this administrator and site. Optional completed-workflow counts start off; enabling them stores only allowlisted event counts by UTC day for up to 90 active days. Nothing is transmitted. Export and clear controls are available. The counts cannot establish purchases or a Free-to-Pro conversion rate.

== Installation ==

1. Upload and activate CustomFields.
2. Open CustomFields and create a field group with a starter kit or your own fields.
3. Choose where it appears and save, then edit matching content.
4. Use Blocks & listings to publish that content, or use a template helper.

For an existing Free/Pro pair, update Free first, then Pro, to matched 0.9.0-beta.1. Keep a database backup and test this beta on staging. Do not uninstall to upgrade. Old Pro 0.4 with new Free is handled during the transition; an old Free with new Pro displays a dependency notice. Earlier installer bytes remain unchanged.

== Frequently Asked Questions ==

= Does Free really include the structured fields? =

Yes. Groups, repeaters, galleries, flexible layouts, reusable groups, options pages, frontend forms, history and supported migrations are local Free features from 0.5. Pro adds repeatable content operations and submission approval workflows. There is no licence check on Free content tools.

= Is the live sample preview saved content? =

No. Its temporary values are separate from field definitions and real content. Large previews are shortened without changing your configured limits. Save the group and open matching content to enter real values.

= Where is the data stored? =

Definitions remain in customfields_groups. Ordinary values use post/user/term metadata; options values retain the legacy customfields_pro_values name for compatibility. Deactivation or removal preserves data. A removed/renamed definition does not delete old values.

Optional custom-table storage is explicitly provisioned in Storage and selected per supported group. The table is authoritative, with a mandatory native metadata mirror for queries, revisions and returning to metadata. This is not a metadata-footprint reduction feature. Backfill preserves native source values. Transactional paths require InnoDB. Inconsistent mirrors block supported writes instead of silently choosing a winner.

= What can frontend forms do? =

[customfields_form group="group_key" post_id="123"] edits one matching group on an existing post for a logged-in authorized editor.

[customfields_form group="group_key" mode="create" post_type="post"] creates an owned draft, with a title and group values. The group must match the post type without specific-post or template restrictions. WordPress handles later publication. Anonymous submissions, arbitrary authors, checkout and email actions are not included. A creation receipt prevents identical retries from creating duplicate drafts.

= How do linked reusable definitions work? =

Existing clones remain reviewed snapshots. Linked mode references a source group, rejects cycles and uses the source's definitions. Source edits affecting linked consumers require Review linked updates. The review checks downstream compatibility and applies the source and consumers together. Saved values are never silently rewritten into a different structure.

= What do blocks and listings support? =

Blocks & listings creates distinct named blocks with up to 20 text, rich-text, number, choice, checkbox, image, email or URL controls and card, stack or banner presentation. Each inserted block keeps its own values. Templates are fixed trusted code; uploaded executable templates are not accepted.

Listings query public, published, non-password-protected content. Choose a content type, registered scalar field filter/order, taxonomy terms, display fields, layout, page size and search. Select which custom fields visitors may see. Use the CustomFields listing block or [customfields_listing id="your-listing"]. Up to 50 definitions of each kind, 40 items per page and 12 displayed fields are supported.

= How does Elementor integration work? =

Elementor Free supports the CustomFields value and CustomFields listing widgets. The scalar dynamic tag uses Elementor's dynamic-tag API; using dynamic tags requires Elementor's own supported edition, normally Elementor Pro. No Elementor licence is included. No Bricks/Divi/Oxygen connector is claimed in this release.

= How do references and permissions work? =

Single-reference dropdowns retain their existing bounded selection behavior. The Relationship type provides authorized search, ordered multiple selection and optional reciprocal top-level fields. Configure matching object types/scopes and reciprocal identities. Reciprocal changes verify both sides and roll back if any required target cannot be edited. Relationships are not a way to bypass object or metadata permissions. Clearing an attachment value keeps its media file.

= What do location and condition filters support? =

Post groups match selected types, optionally restricted by post IDs and saved page templates. User groups appear on permitted profile screens. Term groups edit existing terms in selected taxonomies. Attachment, comment, menu and network-settings targets are not included.

Conditions support all/any rules and seven operators; nested rules reference sibling fields. Cycles are rejected. Hidden fields keep stored values. Visibility controls presentation, not authorization.

= How do I use PHP and REST? =

Use customfields_get('field_name', $post_id), customfields_get_object('field_name', 'user', $user_id), its 'term' equivalent, or customfields_get_option('field_name'). These trusted PHP helpers return unescaped values; authorize private output and escape for its context.

The [customfield name="field_name"] shortcode prints escaped scalar text with visibility checks. The Custom field block supports richer values.

REST-enabled post types expose authenticated edit-context customfields values for authorized editors. No public metadata endpoint is added. Omitted groups remain unchanged; included groups must contain active editable fields. Other plugins can expose metadata independently.

= How do local JSON and migration work? =

Define CUSTOMFIELDS_JSON_DIR as an existing writable private directory. Supported schema saves write back after the request commits, unless the file has unreviewed changes. Local sync shows changes in customfields-schema.json and offers reviewed file-to-database or database-to-file application. Imports are explicit; files are never executed. File and schema fingerprints block stale reviews. Export failure does not undo the database save.

Use wp customfields schema export, check <file>, or import <file>. CLI import applies only with --apply --expected-hash=<hash-from-check> and an administrator user. CLI replacement and local-file import replace the full registry; the ordinary JSON import screen merges by group key. Content remains stored.

Content migration is separate from schema import. Workflows supports posts, users, terms and explicitly registered default or custom-prefix ACF/SCF options pages; compatible scalars, nested groups, repeaters, flexible layouts, galleries and post/user/term references; supported Clone, Link and Google Map values converted to matching native groups; and supported Meta Box groups, scalar clones, clone_as_multiple, repeated collections, timestamp dates and taxonomy fields that load their effective terms. Source definitions, exact raw snapshots, compatible destinations and explicit review are required. Scalar clones use a repeater child named value. Options apply/undo checks the entire native container, including siblings. Source values remain intact; competitor-specific relationship graphs and templates are not rewritten. See the developer guide for adapter-specific limits.

A narrow Meta Box Custom Table adapter reads only a dedicated InnoDB table bound to one applicable active registry group, with an integer primary ID and direct field-ID column. Table names cannot be supplied in the migration form. Source rows are rechecked and locked during the destination transaction. This paid-extension adapter has contract-fixture qualification; the paid MB Custom Table/Group plugins were not installed for integration testing. This is not an automatic whole-site migration.

= How do recovery and history work? =

Per-user post recovery drafts retain valid field groups for up to 24 hours. Restore fills the editor for review and only works with matching schema and permissions. WordPress post revisions include field snapshots when revisions are enabled, with compatible-identity and permission checks on restoration. Schema history stores up to 20 snapshots within 4 MB; guarded restore scans up to 2,000 values. A blocked review leaves saved values intact.

= What are the limits? =

Schemas allow 100 groups, 200 fields per group and 1 MB JSON imports. Nested structures support three composite levels, 20 children per container, 100 rows and shared 4,000-value/render budgets. Runtime request limits can be smaller. Content migration is bounded to 50 objects, five-object batches and a 2 MB journal with an expiring review; options use a single destination. Rich text uses WordPress post-safe HTML. Numbers are finite floating-point values, not arbitrary-precision financial amounts. Date/time inputs do not convert timezones.

Incompatible existing values are locked for review, not truncated. Direct WordPress metadata writes by other code do not receive all form validation. Protected relationship/table writes add atomic storage handling; ordinary metadata writes retain WordPress behavior. Plugin validation does not replace a site-wide publication approval system.


= Can I explore Pro without installing it? =

Explore Pro shows clearly labelled examples using fictional records in your browser tab. Applying or undoing an example does not change WordPress content or make a service request. Contextual suggestions appear on selected CustomFields screens after setup; Hide suggestions stores only your local per-site administrator preference. Explore Pro remains available and lets you show suggestions again. No account, telemetry or remote tracking is added.

== Changelog ==

= 0.9.0-beta.1 =
* Add optional real-content onboarding and a local next-action dashboard.
* Add private read-only CSV comparison and resumable content-quality checks.
* Add field-group baseline comparison, supported impact information and manual fixes.
* Tie optional Pro guidance to real supported tasks; add explicit local-only workflow measurement.


= 0.8.0-beta.1 =
* Keep all existing Free content tools and add a local Explore Pro guide with interactive examples.
* Add quiet, dismissible workflow suggestions and a per-site administrator display preference.
* Add shared navigation for Pro CSV and submission workflows.


= 0.7.0-beta.1 =
* Split migration setup, review and field history into focused views, with searchable mobile value comparisons.
* Add supported Clone, Link, Map, custom option-prefix, timestamp-date and taxonomy-value conversions.
* Preserve original source data and refuse ambiguous or lossy conversions.

= 0.6.0-beta.1 =
* Unify workspace navigation, styling, guided setup and local package-file review.
* Extend reviewed migration to supported user, term and options sources, references and Meta Box cloned values.
* Preserve source snapshots and destination recovery guards across the expanded targets.

= 0.5.0-beta.1 =
* Move all existing local Pro content tools into Free with preserved data keys and compatibility aliases.
* Add content types, taxonomies, searchable reciprocal relationships and optional dedicated storage.
* Add linked definitions and authenticated draft creation.
* Add custom block authoring, visual listings and Elementor widgets.
* Add reviewed local JSON synchronization and broader structured value conversion.

= 0.4.0-beta.1 =
* Interactive structured-field, media and rich-text previews when their extension is active; preview values stay separate from saved schemas.
* Preserve structured editing context across recovery drafts and block-editor saves.
* Matched companion release for the expanded Pro workspace.

= 0.3.0-beta.1 =
* Introduce the Field Studio with starter kits, searchable field selection, focused editing and a live form preview.
* Add readable choice editing, reversible field removal, drag ordering with keyboard controls, and keyboard saving.
* Save definitions without a page reload while retaining validation, permissions and stale-schema protection.
* Simplify group navigation and move storage settings into expandable sections.
* Refresh responsive styling with self-hosted fonts and reduced-motion support.

= 0.2.0-beta.1 =
* Expand Free to twenty field types, including media, rich text, multiple choices, references, and time/date-time.
* Add numeric/text constraints, visual conditions, user/term locations, and post ID/template filters.
* Add field duplication, search, collapse controls, and presets.
* Add native field output blocks/bindings and authenticated edit-context REST integration.
* Add valid-group recovery drafts, field revision snapshots, and supported-editor publication checks.
* Add optional local JSON export and explicit CLI schema validation/import workflows.
* Preserve incompatible stored values and unknown extension settings through validation locks.

= 0.1.0-beta.1 =
* Initial beta: visual field groups, nine core types, strict submission validation, JSON import/export, and extension hooks.

== Privacy ==

Free makes no third-party API calls, automatic usage reports or account registration. Optional workflow counts are disabled by default and stay in per-site administrator metadata; they can be exported or cleared locally. Goals, private CSV comparisons, diagnostic checkpoints and baseline results stay on this WordPress site. Content, drafts, journals and creation receipts remain in the site's database. Search, editing and recovery requests use the site's own endpoints. Local JSON writes use the configured directory. Optional external builders have their own privacy practices. The separate Pro licence connection is opt-in and described in Pro's readme.
