Documentation

Welcome to the Dynamic FieldKit docs hub. Everything from a fresh install through advanced templates lives on this page. Use the sidebar to jump to a section.

Installation

Dynamic FieldKit is a standard WordPress plugin. Requirements: WordPress 6.0+, PHP 8.0+.

Install from zip:

1. Download dynamic-fieldkit.zip.
2. In WordPress: Plugins → Add New → Upload Plugin.
3. Choose the zip → Install Now → Activate.

Activating Pro: Visit Dynamic FieldKit → Settings, paste your license key, click Activate.

Getting Started

Three steps to your first dynamic field.

1. Create a field group. Dynamic FieldKit → Field Groups → Add New. Title: "Page hero". Add a Text field labeled Hero title and a Textarea field labeled Hero subtitle. Set location: Post Type = Page. Save.

2. Edit a page. Open any Page. The field group appears below the editor.

3. Show the values on the frontend. In your theme's page.php:

<section class="hero">
  <h1><?php dfk_the_field( 'hero_title' ); ?></h1>
  <p><?php dfk_the_field( 'hero_subtitle' ); ?></p>
</section>

Field values are stored as standard post_meta keyed by the field's name. dfk_the_field() is type-aware — it routes through the correct sanitiser per type.

Free vs Pro

Free: unlimited field groups · core field types · location rules · basic Repeater · Options Page · dfk_* helpers · cfb_* BC aliases · documentation · community support.

Pro adds: HTML Generator · Raw HTML field · Repeater with all sub-field types · Post Grid · Header Templates · Footer Templates · Menu Profiles · Created-menu tokens · HTML-safe helpers (dfk_the_field_html, dfk_the_sub_field_html, …) · Priority email support · All future Pro features.

Field Groups

A field group is a named collection of fields bound to one or more locations.

Location rules (ORed together):

• Post type equals
• Page template equals
• Post template equals
• Options page

Display settings: position (normal / side / advanced), priority (high / default / low), hide content editor.

Active/inactive status: field groups can be inactive without being deleted. Sub-fields: inside a Repeater, you nest a sub-field tree.

Field Types

Every field type, what it stores, and the helper you use to render it.

Return formats for image/file: id, url, or array (expands to a structured shape with id, url, title, alt, filename, mime, and sizes for images).

Repeater Fields

Repeaters hold an ordered array of rows with their own sub-fields.

Editor: existing rows show as collapsible cards. Add row, drag to reorder, delete.

Frontend:

<?php if ( dfk_have_rows( 'team' ) ) : ?>
  <section class="team">
    <?php while ( dfk_have_rows( 'team' ) ) : dfk_the_row(); ?>
      <article>
        <?php dfk_the_sub_field_html( 'photo' ); ?>
        <h3><?php dfk_the_sub_field( 'name' ); ?></h3>
        <p><?php dfk_the_sub_field( 'role' ); ?></p>
      </article>
    <?php endwhile; ?>
  </section>
<?php endif; ?>

Sub-field types: text, textarea, number, email, url, password, select, checkbox, radio, true/false, wysiwyg, raw_html (Pro), date, time, color, image, file, link.

Raw HTML Field Pro

A dedicated field type for safe inline-SVG and icon markup.

Use it for: inline SVG, Font Awesome / Bootstrap icon <i> tags, small controlled HTML blocks. Don't use it for: arbitrary user-supplied HTML, large content (use WYSIWYG), anything needing <script> or <iframe>.

Allow-list (on save): div, span, p, ul, ol, li, a, i, b, em, strong, small, br, img, plus SVG primitives (svg, g, defs, symbol, use, title, desc, path, rect, circle, ellipse, line, polyline, polygon).

Stripped on save: <script>, <iframe>, <object>, <embed>, <form>, every on* event handler, javascript: URLs.

Frontend:

<div class="feature-icon">
  <?php dfk_the_field_html( 'feature_icon' ); ?>
</div>

<?php while ( dfk_have_rows( 'features' ) ) : dfk_the_row(); ?>
  <span class="icon"><?php dfk_the_sub_field_html( 'icon' ); ?></span>
<?php endwhile; ?>

Extending: filter cfb_raw_html_allow_list.

Displaying Field Values

// Return
$title = dfk_get_field( 'hero_title' );
$title = dfk_get_field( 'hero_title', $post_id );

// Echo (type-aware)
dfk_the_field( 'hero_title' );

// Echo through Raw HTML sanitiser
dfk_the_field_html( 'feature_icon' );

// Block output (wpautop)
echo dfk_render_field_formatted( dfk_get_field( 'bio' ), 'wysiwyg' );
dfk_the_field_formatted( 'bio' );

// Repeater
if ( dfk_have_rows( 'rows' ) ) {
    while ( dfk_have_rows( 'rows' ) ) {
        dfk_the_row();
        dfk_the_sub_field( 'name' );
        dfk_the_sub_field_html( 'icon' );
    }
}

// Options Page
$company = dfk_get_option( 'company_name' );
dfk_the_option( 'company_name' );

HTML Generator Pro

Turn a static HTML mock-up into a field group + PHP template.

Workflow:

1. Dynamic FieldKit → HTML Generator.
2. Set title, target post type, optional page/post template, options-page toggle, output mode (Hide empty or Inline fallback).
3. Paste your HTML → click Analyse HTML.
4. Review detected fields + generated PHP.
5. Copy Code or Download as .php.
6. Create Field Group to save the fields.
7. Drop the template into your theme. Edit a matching post — fields appear.

What it detects:

• Plain text → text or textarea
• <svg>…</svg>, Font Awesome / Bootstrap icons → raw_html
• Anchors and CTA buttons → link
• <img> → image
• Sibling elements with same tag/class signature → repeater
• <tbody> / <ul> / <ol> / <dl> with homogeneous rows → repeater
• <button> with multiple element children → recurse

Template Conversion Workflow

1. Prepare your mock-up. One HTML file per page. Paste only <body> content.
2. Run the HTML Generator. Follow the workflow above.
3. Drop the generated PHP into your theme as a page template:

<?php
/**
 * Template Name: Hero landing page
 */
get_header();

while ( have_posts() ) : the_post(); ?>

  <?php /* paste the generated template here */ ?>

<?php endwhile;

get_footer();

4. Enqueue the mock-up's CSS/JS from functions.php.
5. Edit and ship.

Post Grid Field Pro

Query and render a list of posts inline in any field group.

Settings:

• Selection mode: automatic (query) or manual (admin-picked IDs).
• Post type, taxonomy filters, max posts, ordering.
• Layout: grid (configurable columns) or list.
• Display fields: featured image, title, excerpt, date, author, categories, plus any text-like custom field from the post's own field groups.

Frontend:

<?php dfk_the_field( 'related_posts' ); // emits its own markup ?>

Menu Profiles Pro

Preserve theme-imported CSS class names through wp_nav_menu() via a custom walker.

Create a profile: Dynamic FieldKit → Menu Profiles → Add New. Pick a menu location, fill in standard menu classes (top-level UL/LI/A, submenu UL/LI/A, active states, parent LI, dropdown caret). Optionally fill mega-menu classes.

Replace a static menu in a Header Template:

{{wp_menu_by_id:42}}

This expands at render time via wp_nav_menu() with the walker applying your profile's classes.

Plugin-registered fallback locations: dfk_primary_menu, dfk_mobile_menu, dfk_footer_menu, dfk_footer_company_menu, dfk_footer_services_menu. Short aliases (primary, mobile, footer, …) resolve when not theme-registered.

Header Templates Pro

1. Dynamic FieldKit → Header Templates → Add New.
2. Set template name, wrapper selector (e.g. header, .site-header).
3. Paste your full header HTML.
4. Replace static menus with {{wp_menu_by_id:<id>}}. Replace static logo / title / search with {{site_logo}} / {{site_title}} / {{search_form}}.
5. Set Display Conditions + Status (Active).
6. Save.

Render: auto-injection via wp_body_open, or call manually:

echo dfk_render_header_template();
echo dfk_render_header_template( 42 );  // specific template ID

Footer Templates Pro

Same workflow as Header Templates with a footer-specific token: {{copyright_text}} (composes "© <year> <site_title>").

echo dfk_render_footer_template();

Template Tokens

Site tokens: {{site_logo}}, {{site_title}}, {{site_tagline}}, {{home_url}}, {{site_url}}, {{search_form}} (header only), {{current_year}}, {{admin_email}}, {{copyright_text}} (footer only).

Menu tokens:

• {{wp_menu_by_id:<id>}} — render the WP menu with that term ID.
• {{wp_menu:<location_slug>}} — render the menu assigned to a location (legacy).

Unknown tokens are left untouched in the output.

Troubleshooting

"Plugin could not load" notice. Check wp-content/debug.log and the notice text (includes file + line of the bootstrap error).

Field values aren't appearing on the frontend. Confirm The Loop is active (or pass an explicit $post_id). For Options Page fields use dfk_get_option().

Raw HTML field saves empty. Field type is probably Text, not Raw HTML. Change the type and re-save. The plugin auto-upgrades icon-named text fields (icon, icon_svg, feature_icon, svg, svg_icon) to raw_html on the next field-group save.

{{wp_menu_by_id:42}} renders nothing. Confirm the menu with that term ID exists in Appearance → Menus. Missing menus emit an HTML comment marker.

Auto-injected header/footer doesn't appear. Confirm: status Active, wrapper selector matches your theme, auto-injection enabled in Settings.

Repeater rows missing after save. Check sub-field name collisions.

FAQ

GPL? Yes — free plugin is GPL-2.0-or-later. Pro is gated by activation check.

Field values survive uninstall? Yes by default. Set DFK_UNINSTALL_PURGE_ALL = true in wp-config.php to opt into a full wipe.

Migrate from another field plugin? No automated migration at launch. Manual path: re-create field groups with matching field names — your existing post_meta is readable through dfk_get_field().

Page-builder compatibility? Standard post_meta storage — any builder that reads post_meta can use DFK values.

Pro on a client site? Yes. Standard license covers one production site.

Refunds? 14 days, no questions.

Usage limits? None.

Telemetry? None. Pro activation makes one check against the license server when you enter the key.

Security Notes

Per-type save sanitisation:

• text/email/url/select/radio/date/time/color → sanitize_text_field() or type-specific WP sanitiser
• textarea → wp_kses_post()
• wysiwyg → wp_kses_post( wpautop( $value ) )
• raw_html → wp_kses() with the Raw HTML allow-list
• image/file → (int) cast
• link → array shape sanitised per key
• repeater → recursive per sub-field
• post_grid → configuration sanitised per setting

Frontend output: type-aware helpers re-sanitise on output (defence in depth).

Capability checks: field group / template / settings saves require manage_options. Menu-item field saves require edit_theme_options. AJAX requires edit_posts.

Nonces on every save, delete, download, and AJAX request.

Template HTML on save: PHP tags regex-stripped first. Users with unfiltered_html (single-site admins) store as-is; others run through wp_kses with an extended-but-bounded allow-list.

Tokens: regex constrains both token name and colon-suffix to [a-zA-Z0-9_-]. Numeric tokens (int)-cast and validated positive. Unknown tokens passed through unchanged.

SQL: all queries use $wpdb->prepare() with placeholders.

Developer Notes

Public helper API:

dfk_get_field( $name, $post_id = null )
dfk_the_field( $name, $post_id = null )
dfk_get_field_html( $name, $post_id = null )
dfk_the_field_html( $name, $post_id = null )
dfk_have_rows( $name, $post_id = null )
dfk_the_row()
dfk_get_sub_field( $name )
dfk_the_sub_field( $name )
dfk_get_sub_field_html( $name )
dfk_the_sub_field_html( $name )
dfk_get_option( $name )
dfk_the_option( $name )
dfk_the_field_formatted( $name, $post_id = null )
dfk_the_sub_field_formatted( $name )
dfk_the_option_formatted( $name )
dfk_render_field_html( $value, $type )
dfk_render_field_formatted( $value, $type )
dfk_render_raw_html( $value )
dfk_sanitize_raw_html( $raw )
dfk_sanitize_safe_html( $raw )
dfk_replace_dynamic_tokens( $html, $template_id = null )
dfk_render_header_template( $template_id = null )
dfk_render_footer_template( $template_id = null )

All have cfb_* backward-compatibility aliases.

Hooks (cfb_* prefix for back-compat):

• cfb_pre_save_field_group_data (filter)
• cfb_field_group_saved (action)
• cfb_field_group_deleted (action)
• cfb_field_type_labels (filter)
• cfb_render_field_before / cfb_render_field_after (actions)
• cfb_skip_default_render_<type> (filter)
• dfk_get_field (filter)
• dfk_get_option (filter)
• cfb_raw_html_allow_list (filter)
• cfb_sanitize_value (filter)
• cfb_template_token_value (filter)
• cfb_auto_inject_header_html / cfb_auto_inject_footer_html (filters)

Data model: field values in wp_postmeta keyed by field name. Repeater rows as a serialised array under the repeater's key. Field-group definitions stored as cfb_field_group posts with the schema in _cfb_fields post meta.

Best Practices

• Name fields semantically (hero_title, not top_text_1).
• Prefer many small field groups over one massive one.
• Use the Options Page for site-wide values only — not per-page content.
• Default to dfk_the_field(). Use _html variants only for raw_html fields. Use _formatted variants only when the field is a standalone block.
• Keep sub-fields shallow. A repeater with 12 sub-fields is harder to edit than two with 6 each.
• Reserve Raw HTML for admin-editable controlled content (icons, SVGs, small marketing blocks).
• Use Inline fallback output mode while migrating; switch to Hide empty before shipping.
• Take a database backup before any major field-group restructure.