Mass Custom Fields
Mass Custom Fields
Field groups, field types, the developer API, data tables, forms, variables and programmatic SEO.
Getting started
- Introduction to Mass Custom FieldsWhat Mass Custom Fields is, how its database-first storage differs from postmeta-based plugins, what the free plugin includes, what Pro adds and where to go next.
- RequirementsThe WordPress, PHP, MySQL and MariaDB versions the plugin needs, hosting and permission requirements, who can open the admin screens and a troubleshooting table.
- Installation and activationHow to install and activate the free plugin or Pro, what activation creates, when the setup wizard opens and how to go back from Pro to free.
- Setup wizard and starter templatesA walkthrough of the optional setup wizard: choosing a goal, the four starter templates and what each creates, skipping the wizard and fixing common problems.
- The dashboard and headerA tour of the WPM Fields dashboard: the health notice, the Get started checklist, overview counts, content cards, the plan card, the header and the Ctrl K search.
- SettingsThe Settings screen: the Data, Maps and Page caches options on the General tab, the AI, Health and Plan & license tabs, and a short troubleshooting table.
- Health and troubleshootingHow the plugin contains and reports errors, how integrations are switched off after repeated failures, how to read the Health tab and what to collect before asking for help.
- Plans and licensingWhat the Free, Pro, Business and Agency plans include, their site, page and task limits, how the Pro page and the Plan & license tab work and how licensing and support are handled.
- Trials, renewals and expiryHow the 14-day trial works and what happens to your site, your data and each Pro feature when a trial ends or a paid license expires, including the 14-day grace period and conversion.
- MultisiteHow the plugin behaves on WordPress Multisite: per-site data and settings, activation options, site deletion, uninstalling and license quotas.
- Privacy and dataWhere the plugin stores data, how it supports WordPress personal data export and erase, the privacy policy text it suggests and the outside services it can contact.
- Deactivating and uninstallingWhat deactivating and deleting the plugin do to your data, what the Delete all plugin data on uninstall setting removes and how to back up first.
- Getting started FAQShort answers to common questions about installation, setup, settings, plans and trials, privacy, multisite and uninstalling, with links to the full pages.
Field groups
- Field groups overviewWhat a field group is, how its values are stored in a table of its own, and where to find everything about it.
- Create a field groupStep by step: add a field group, give it fields and location rules, save it, edit it later and delete it.
- Add and arrange fieldsHow to add, rename, reorder, retype and remove fields in the field builder, how field keys become column names and how the 100-column limit works.
- Field settings: general, validation and SQL columnEvery setting on a field's General and Validation tabs, including Required, indexes, Unique, validation rules and SQL column overrides.
- Field settings: display and advancedWhat the Display tab of a field controls: the output wrapper, prefix and suffix, the admin list column and the per-field translation mode.
- Conditional logicShow or hide a field on the edit screen depending on the values of other fields in the same group.
- Location rulesDecide where a field group appears - every rule parameter, how and/or groups combine, and what each rule matches.
- Group settingsStyle, position, label and instruction placement, order, the Active switch and the integration toggles of a field group.
- Where field groups appear and how values are savedWhere a field group appears on post, user, term, comment, widget, options page and order screens, and how saving, permissions and cleanup work.
- Changing a field group safelyWhat happens to a group's database table when you add, rename, retype or remove fields, including backup columns, leftover columns and background changes on large tables.
- Table healthInspect a group's database table, repair differences between the definition and the table, handle leftover columns and unregistered tables, and delete groups.
- Query posts by field valueFilter and sort posts by their custom field values with wpmcf_query, the wpmcf: orderby syntax, distance search and wpmcf_query_posts().
- Field groups troubleshooting and FAQFixes for field groups that do not appear or save, errors when saving a group, stuck background changes, known limitations and answers to common questions.
Field types
- Field types overviewThe 32 free field types of Mass Custom Fields with their type ids, database columns, returned values and output, plus a guide to choosing a type.
- Settings every field hasThe options every field shares (default value, placeholder, required, validation, display and conditional logic), how they behave per type and which rules the server enforces.
- Text, Text area, Email and URLHow the Text, Text area, Email and URL fields are stored, cleaned on save and printed, with template examples and column options.
- Number and RangeNumeric fields stored as real numbers: column types, clamping, min and max rules, and the value you read back.
- PasswordA secret that editors can set but never read back: hashed, encrypted or plain storage, how to verify it in code, and why it never prints.
- Choice fieldsSelect, Radio buttons, Checkboxes, Button group and True / false: choices, stored values, labels and what you get back in PHP.
- Date, Date and time, and TimeThree date and time fields stored in native database columns, with strict parsing and a display format you control.
- Color picker and Icon pickerPick a hex color or a Dashicons icon; both are stored as short text values you can use in CSS and HTML.
- WYSIWYG editor, oEmbed and LinkFormatted text, embedded videos and links with their own text and target: settings, cleaning, stored shape and output.
- Image and FileAttach one image or file from the media library: stored as the attachment ID, with allowed file types and image size settings.
- MapPick a place by address search, click or coordinates; shows an OpenStreetMap or Google map on your site and keeps latitude and longitude in searchable columns.
- Post object, Page link, Relationship, Taxonomy and UserLink a field to posts, pages, terms or users: settings, the IDs that are stored and how related items are printed.
- GroupBundle several fields under one name, such as an address, and read them back as one array.
- RepeaterA list of rows that each hold the same sub-fields, such as FAQ items or team members: row limits, saving, reading and looping in templates.
- Accordion and TabOrganise long edit screens into tabs and collapsible sections. They store nothing and have no column.
- Output, formats and escapingWhat wpmcf_get_field(), wpmcf_the_field() and the [wpmcf_field] shortcode return and print for each field type, the output formats, and how escaping works.
- Pro field typesThe four field types that come with Mass Custom Fields Pro, and what happens to their data without a license.
- Troubleshooting field typesCommon problems with field values, and the reference for changing a field's type and its database column.
Developer API
- Developer API overviewA map of the public PHP functions, shortcodes, blocks, query arguments and REST attribute for reading, writing and querying field values, plus the keys, object and argument conventions they share.
- Reading valuesHow to read field values with wpmcf_get_field(), wpmcf_has_field() and the options-page getters: arguments, return types, defaults, paths into Group and Repeater fields and the fact that reads are not access-checked.
- Writing valuesHow to save or clear field values from code with wpmcf_update_field(), wpmcf_delete_field() and the options-page writers, what sanitizing does to your values and why you must check capabilities yourself.
- Object referencesEvery accepted form of the object argument (IDs, WordPress objects and references such as user_3, term_5 and option), how the context argument interacts with them and what happens with an invalid reference.
- Output formats and escapingHow the printing functions escape and format a value: the format and wrap arguments, defaults, what is never printed and when to use a raw getter with your own escaping instead.
- ShortcodesReference for the [wpmcf_field] and [wpmcf_global] shortcodes: attributes, examples, the visibility rules that apply to contributor-written content and a troubleshooting table.
- Blocks and Block BindingsHow to show field values in the block editor with the WPM Field block or the WPM Fields Block Bindings source: references, attributes, formats, visibility rules and the editor's internal REST routes.
- Querying postsHow to filter, sort and run distance searches on field values with the wpmcf_query, orderby and wpmcf_distance arguments of WP_Query, including operators, limits and the handling of invalid arguments.
- REST APIHow to read and write field values through the wpmcf attribute on core post endpoints, the validation and permission rules, and why the wpmcf/v1 namespace is internal.
- Global Data functionsReference for wpmcf_get_global(), wpmcf_the_global(), wpmcf_has_global() and wpmcf_update_global(): return values, escaping, password variables, expressions and defaults.
- Password helpers and securityHow wpmcf_check_password() and wpmcf_get_password() work with Password fields, what every other function does with them, and a security checklist for the whole developer API.
- Function referenceEvery public wpmcf_* PHP function with its exact signature, parameters, return value and an example, plus the common arguments and a list of internal helpers.
- Developer API troubleshootingA symptom-based guide to the developer API: why reads return null, printing is empty, writes return false, shortcodes or blocks show nothing, queries are ignored or REST requests fail.
Post types, taxonomies and site data
- Custom post typesHow to create, edit, deactivate and delete custom post types in the admin, including key rules, permalink behavior, developer hooks and troubleshooting.
- Post types: General and Labels tabsThe General and Labels tabs of the post type editor: description, Supports options, additional supports, attached taxonomies and the 34 label fields with their generated defaults.
- Post types: Visibility and URLs tabsThe Visibility and URLs tabs of the post type editor: admin menu placement, navigation and search settings, the meta box callback allow-list, permalink slugs, archives and query variables.
- Post types: Permissions and REST API tabsThe Permissions and REST API tabs of the post type editor: custom capability names, export and user-deletion behavior, and how the type is exposed in the REST API.
- Custom taxonomiesHow to create and configure custom taxonomies, including Basics, key rules, every Advanced tab, attaching a taxonomy to post types and using terms in your theme.
- Options pagesHow to create site-wide settings screens in the admin, attach field groups to them, read the saved values from code or shortcodes and control who can see them.
- Global DataHow to define site-wide variables once and print them anywhere: variable types, password variables, validation and display settings, template functions, the shortcode, variables and hooks.
Import, export and migration
- Import, export and migration overviewMass Custom Fields moves definitions (field groups, post types, taxonomies, options pages) and saved values between sites, files and other plugins. This page helps you pick the right tool and explains what each method does with existing items.
- Export and import definitions (JSON)Download field groups, post types, taxonomies and options pages as one JSON file, preview an import before anything is saved, and look up every message the import report can show.
- Local JSON and version controlMirror your definitions to JSON files in your theme, commit them to Git, and load changes made on another site with one click from Tools › Local JSON.
- Migrating from Advanced Custom FieldsCopy ACF field groups, options pages, post types, taxonomies and saved values into Mass Custom Fields. You get a report first, and ACF itself is never changed.
- Moving field values (WordPress export files) and duplicating postsField values travel inside WordPress export (WXR) files and follow a post when it is duplicated. This page covers the import order, the limit on ids and how to copy values from your own code.
- WP-CLI commandsReference for every wp wpmcf command with its options and examples: export, import, Local JSON, ACF migration, tasks and PHP-registered field groups. Use it in scripts, deployments and on servers without a working cron.
- Background tasksLong jobs run in small batches in the background through Action Scheduler. Learn the task statuses, retries and watchdog, and what to check when a job seems stuck.
Variables and developer hooks
- Variables overviewVariables are {{ }} expressions that print Global Data, field values, post data and site facts inside your text. This page explains what the engine can and cannot do and points to each part of the reference.
- SyntaxThe exact grammar of a {{ }} expression: literals, paths, filters, function calls, operators, the ternary, nesting, limits, and what happens when an expression is wrong.
- NamespacesEvery namespace an expression can read (glb, fg, wp, sys, woo, src and pseo), with each available name, what it returns and when it is empty.
- Filters and functionsEvery built-in filter and function of the variables engine, with its arguments, its behavior on empty or mismatched input, and a worked example with the result.
- Where variables workLists the places that evaluate {{ }} expressions (field values, placeholders, defaults, Global Data, Elementor settings, Programmatic SEO templates, your own PHP) and the places that deliberately do not.
- SecurityHow the variables engine stays safe: no PHP execution, a fixed vocabulary, rules for who may run expressions, password exclusion, the option allow-list, hard limits and escaping, plus the filter that adjusts each rule.
- PHP APIEvaluate templates from your own code with wpmcf_resolve_variables() and wpmcf_make_context(), use the engine and registry directly, and add your own namespaces, filters and functions.
- Hooks reference: actionsReference for every wpmcf/ action the plugin fires, grouped by area, with arguments, timing, the plan each belongs to and examples.
- Hooks reference: filtersReference for every wpmcf/ filter the plugin applies, grouped by area, with arguments, defaults, return types, timing, the plan each belongs to and examples.
- Constants and configurationThe WPMCF_ constants the plugin defines, the ones you can set in wp-config.php (grace period, client IP header, AI keys, error rethrow) and the WordPress constants it honors.
- TroubleshootingFixes for expressions that print nothing, print their braces, print the wrong value or print HTML, and for custom namespaces or hooks that do not run.
Pro fields, admin columns and page builders
- Pro fields, admin columns and page builders overviewIntroduces the Pro field types, the admin list tools and the page builder integrations, with a table of which plan each feature needs and links to every page in this section.
- GalleryThe Gallery field stores several images from the media library in one field. This page covers its settings, what is saved, how to read the list of attachment IDs and how it prints.
- Flexible contentThe Flexible content field lets editors mix rows of different layouts that you define. This page covers layouts, limits, the row editor, saving, reading and printing.
- CloneThe Clone field reuses the fields of another field group and keeps them in sync with it. This page covers choosing the source, which fields can be cloned, storage and reading.
- Programmatic SEO page fieldThe Programmatic SEO page field links a post, term or option to one page generated by a Programmatic SEO task. This page covers choosing the task, the picker, what is stored and what prints.
- Admin columnsShow field values as columns in the post, term and user lists. Learn how each field type is displayed and sorted, and which list tools need a Pro plan.
- List filtersNarrow the posts and users lists by field values with controls above the table. Learn which field types get which control and how the filters combine.
- Quick edit and bulk editChange field values from the posts list with WordPress Quick Edit and Bulk Edit. Learn which field types are supported, how values are cleaned and what is not validated.
- CSV export of listsDownload a posts list with its field columns as a CSV file. This page covers what is included, how filters and sort order apply, how cells are written and how spreadsheet formulas are neutralized.
- Page builders overviewWhich page builders Mass Custom Fields supports and what each one receives, how a field is referenced, what a builder can read, and the safety rules that apply in every builder.
- ElementorUse field values in Elementor through dynamic tags, the free Field widget and {{ }} variables in the settings of any widget, and see what needs Elementor Pro or a Pro plan.
- Elementor display conditionsShow or hide Elementor widgets, sections, columns and containers by field values. This page covers the WPM Conditions controls, operators, how rules are evaluated and what happens without a license.
- Post gridThe Elementor Post grid widget lists posts as cards that you can filter and order by field values. This page covers the query, the card content and pagination with page numbers or a Load more button.
- Repeater, gallery and other widgetsSettings and output of the Elementor widgets Repeater, Field gallery, Data table list and Field form, and how they behave in the editor and after a license ends.
- Styling the widgetsThe Style tab sections of each WPM Fields widget in Elementor, the CSS classes and custom properties the widgets print, and what the plugin stylesheet does.
- BricksUse field values as Bricks dynamic data with {wpmcf:group.field} tags. This page covers the :html option, paths into repeaters, links, images and query loops.
- DiviUse field values as Divi 4 dynamic content. This page covers the WPM Fields entries for text, links and images and the Before, After and Keep field formatting options.
- BreakdanceUse field values as Breakdance dynamic data, which Oxygen 6 shares. This page covers the Field value, Field URL and Field image entries in the WPM Fields category.
- Oxygen ClassicUse field values in Oxygen Classic 4.x through its dynamic data entries and the [wpmcf_oxygen] shortcode for links and images.
- Page cache pluginsWhich page cache plugins and hosts are cleared automatically, which changes trigger a purge, how requests are batched and how to turn the feature off.
- License expiry and the free pluginWhat each feature in this section does when a Pro license or trial ends or when you run the free plugin, including what keeps working and what pauses.
- Troubleshooting and FAQQuick answers for Pro field types, admin columns, page builder integrations and page caches, each with a link to the detailed page.
Data tables and forms
- Data tables overviewLearn what a data table is, how its rows are stored, which column types and plans it supports, and what happens to your tables when a license ends.
- Create a data tableCreate a data table, define its columns, mark a column unique for updates, change columns later, choose which columns the site may show, and delete a table.
- Browse, search and edit rowsWork with the rows of a data table on the Entries tab: search, add, edit and delete rows, see what each column type accepts, and learn how password columns behave.
- Import a CSV fileImport a CSV file into a data table: separators and encodings, column matching, the append, update and replace modes, background processing for large files, and the messages you may see.
- Export to CSVDownload a whole data table as a CSV file, see what the file contains and how it is protected against spreadsheet formulas, and learn how to export after a license expires.
- Feeds and syncFill a data table from a Google Sheets link or from your WordPress content, sync it by hand or on a schedule (Business plan and above), and fix sync errors.
- Show rows on your sitePrint the rows of a data table on any page with the [wpmcf_table_rows] shortcode or the Data table list block, including filters, sorting, paging, layouts, caching and safety rules.
- Front-end forms overviewUnderstand front-end forms: the four kinds, how a submission is processed, which field types work, how to place a form on a page, and what happens when a license ends.
- Create a formCreate a front-end form step by step: choose its kind and fields, set who may submit, decide what happens after submission, save the form and put it on a page.
- Post forms (create or edit a post)Let visitors or members submit posts of any public post type with field group values, review status, title and content, and let logged-in users edit posts they are allowed to edit.
- User profile formsLet logged-in members edit the custom field values stored on their own user account from a page on your site.
- User registration formsLet visitors create a user account with extra fields, with safe roles, password rules, email-link passwords and closed registration, and see every message the form shows.
- Data table entry formsCollect leads, signups or applications from visitors: every submission becomes a row of a data table, with required columns, unique values, uploads and passwords.
- Guests and spam protectionSee how forms protect themselves from bots without a CAPTCHA, using a signed guest token, a honeypot, a rate limit and a duplicate guard, and how to set the visitor IP behind a proxy, add your own CAPTCHA check and control access.
- File uploads in formsLet visitors upload images and files through forms: which fields support uploads, allowed file types, size limits, the checks made before saving, where files end up and the messages shown.
- Notifications, messages and redirectsSet up the optional email you receive after each entry, the success message, the redirect to another page, the button label and the error summary, and hook the submission action as a developer.
- Connections to other form pluginsSave the submissions of Contact Form 7, Gravity Forms, WPForms and Fluent Forms as rows of a data table, including field matching, add or update behavior, files, statistics and error handling.
- Choices from a data tableFill the dropdown, radio and checkbox options of a Contact Form 7, Gravity Forms, WPForms or Fluent Forms form from the rows of a data table, and refuse values that are not on the list.
- Troubleshooting data tables and formsFind symptoms and fixes for data tables, imports, feeds, lists, front-end forms, spam protection, uploads and form connections, plus the known limits.
Programmatic SEO and AI
- Programmatic SEO overviewProgrammatic SEO turns a data table and one page template into many search-optimized pages. This overview explains the building blocks, how virtual pages work and what each plan includes.
- Quick start with sample dataTry Programmatic SEO in a minute with a one-click sample of 20 cities. You create the sample, generate the first 10 pages, edit them through the template and delete everything again.
- Data sourcesLearn what a Programmatic SEO task can read: data tables, WordPress content feeds and field group tables. The page covers filters, combining several sources on Business and using columns as variables.
- TasksA walkthrough of the task editor and the task cards on the Programmatic SEO screen. It explains each step, the difference between Save and Save and run now, and which changes need a new run.
- URL and title patternsBuild page addresses and titles from your data with the parent path, page URL and page title patterns. It covers variables, filters, URL cleaning, duplicates and what happens when a pattern changes.
- Templates and field valuesExplains how the page template is rendered for every generated page and how variables are escaped. It also shows how field group values resolve on generated pages and how to set values for a single page.
- Running and scheduling tasksHow a task runs in the background, what the run counters mean and how to schedule runs on Business. It also covers data-change updates, the daily page cap, batch size and the notices a task can show.
- Limits and plansPage and task limits per plan, which pages count toward them and what happens at the limit. It also explains what happens to generated pages when a plan is downgraded, a license expires or a trial ends.
- Serving pages, 404s and URL conflictsShows how a generated page is served and which status each kind of page answers (200, 301, 404 or 410). It also explains what happens when real WordPress content or another generated page uses the same URL.
- Managing generated pagesManage the pages of a task from the Pages list: search, filters, hide and show, and bulk actions. The page also covers the SEO health checklist and the page editor for one page's values.
- SEO plugins and meta tagsDescribes the search-engine data every generated page prints and the Search engines step of the task editor. It explains quality rules and how Yoast SEO, Rank Math and All in One SEO are handled.
- Structured data (JSON-LD)Add schema.org JSON-LD to generated pages with the builder or a raw template. You can map properties to data columns, fixed templates or AI and check the result in the preview.
- SitemapsShows where generated pages appear in the WordPress, Yoast SEO and Rank Math sitemaps and which pages are listed. It also explains lastmod, images and how to submit the sitemap.
- Internal links between generated pagesLink generated pages to each other with the wpmcf_pseo_links shortcode or the Generated Page Links block. You can filter by shared column values and control order, number and layout.
- Freshness, data changes and cache purgeExplains how template, data and setting changes reach generated pages and what moves a page's last modified date. It also covers page cache purging and what to do when a cache still serves old pages.
- Multilingual pages (WPML and Polylang)On Business, a task can create one page per row and language with WPML or Polylang. This page covers setup, translated columns, URLs, hreflang output and the limits.
- Converting generated pages into postsTurn the live pages of a task into regular published posts, with a pre-flight, plan limits and 301 redirects from the old URLs. The page also explains what each post receives and how conversion works around license expiry.
- The Programmatic SEO page fieldThe Programmatic SEO page field links a post, term or option to one generated page of a chosen task. This page covers the settings, the picker, what the field prints and returns, CSV import and what happens when the page changes.
- AI setup (bring your own key)Connect an AI provider to write content for generated pages with your own API key. It covers choosing a provider and model, storing the key safely, request limits and testing the connection.
- AI briefs and runsWrite a brief and choose which fields, SEO values and structured data properties AI should write. The page explains how runs work, what is kept or rewritten and how failures are handled.
- AI privacy, data sent and costsDetails what your site sends to the AI provider, what is stored locally and who pays. It also shows how to estimate and keep down the cost of AI runs.
- WP-CLI and REST for Programmatic SEOProgrammatic SEO uses the general wp wpmcf tasks commands for running tasks from the command line. The page also lists the REST routes for automating tasks, pages, conversion and AI.
- Troubleshooting Programmatic SEO and AISymptom-based fixes for Programmatic SEO: 404s, missing variables, too few pages, runs that do not start, SEO plugin output, AI errors and conversion problems.
Integrations
- Field groups registered in PHPDefine field groups in code with wpmcf_register_field_group() instead of the editor. It covers the definition format, stable field uids, when the group is created, the read-only editor, errors and WP-CLI.
- Post meta bridgeThe post meta bridge lets get_post_meta() and update_post_meta() read and write your field values. This page explains what is bridged, how return values differ from core, importer use and how to turn it off.
- REST API and WPGraphQLExpose field values to other systems with the group switches for the REST API and WPGraphQL. It covers the REST attribute, GraphQL requirements, naming, value types and visibility.
- WooCommerce order fieldsShow field groups on the WooCommerce order edit screen and read the values with wpmcf_get_order_field(). The page covers location rules, HPOS and classic orders, saving, and what happens when a license ends.
- WPML and PolylangOn Business, choose per field whether a WPML or Polylang translation translates, copies or ignores the original's value. The page explains the three modes, when values sync and the limitations.
- Duplicate Post, SEO plugins and site searchThree small integrations: field values follow duplicated posts, fields work as variables in Yoast SEO and Rank Math templates, and chosen groups are included in the front-end WordPress search.
- Integrations troubleshootingProblem and fix tables for PHP-registered groups, the post meta bridge, REST and GraphQL, WooCommerce order fields, WPML and Polylang, and the SEO and search integrations. It ends with the known limitations of this version.