1. Getting Started | Field Forge - Custom Fields, Built for Speed

Shared Forge Suite Diagnostics

When Field Forge is active, the shared Forge Suite > Setup & Health panel is available in WordPress admin. Its read-only AJAX action is forge_suite_health_check; it requires manage_options and the localized forge_suite_health_check nonce. The response returns diagnostics for active Forge plugins, local license records, credits widget readiness, Avakode API /health, permalinks, and migration/integration source plugins such as ACF and ACF Pro. It does not import ACF data, create field groups, write field values, call AI endpoints, spend credits, or change license/Freemius state.

Making Your Theme Work with Field Forge

Field Forge stores values in custom database tables (wp_fieldforge_values) rather than wp_postmeta. It provides an ACF-compatible function layer so existing theme code works without modification. This means you can use get_field(), the_field(), have_rows(), and all other familiar functions — Field Forge registers them automatically when ACF is not active. During ACF activation requests, Field Forge defers to ACF so ACF Pro can be enabled for migration without a PHP redeclare fatal.

Checking if Field Forge is active:

// functions.php -- ensure field functions are always available
if ( ! function_exists( 'get_field' ) ) {
    // Field Forge (or ACF) is not active -- provide fallbacks
    function get_field( $selector, $post_id = false ) {
        return get_post_meta( $post_id ?: get_the_ID(), $selector, true );
    }
}

This pattern ensures your theme never breaks even if Field Forge is deactivated. The fallback reads from wp_postmeta, which is where standard WordPress stores custom fields.

Checking for Field Forge specifically:

// Check for Field Forge (not ACF)
if ( defined( 'FIELDFORGE_VERSION' ) ) {
    // Field Forge-specific code here
    $version = FIELDFORGE_VERSION; // e.g., '1.2.0'
}

// Check for Field Forge PRO features
if ( defined( 'FIELDFORGE_PRO' ) && FIELDFORGE_PRO ) {
    // PRO-only code: repeaters, flexible content, options pages, etc.
}

Basic field access in a template:

<?php
// single.php -- display custom fields on a post
$subtitle = get_field( 'subtitle' );
$hero_image = get_field( 'hero_image' ); // Returns array when return_format = 'array'

if ( $subtitle ) : ?>
    <h2 class="entry-subtitle"><?php echo esc_html( $subtitle ); ?></h2>
<?php endif; ?>

<?php if ( $hero_image ) : ?>
    <img src="<?php echo esc_url( $hero_image['url'] ); ?>"
         alt="<?php echo esc_attr( $hero_image['alt'] ); ?>"
         width="<?php echo esc_attr( $hero_image['width'] ); ?>"
         height="<?php echo esc_attr( $hero_image['height'] ); ?>">
<?php endif; ?>

Outputting a field directly:

<p class="lead"><?php the_field( 'lead_text' ); ?></p>

Using fields in archive templates:

<?php // archive.php or index.php
if ( have_posts() ) :
    while ( have_posts() ) : the_post(); ?>
        <article class="post-card">
            <?php $thumb = get_field( 'card_thumbnail' ); ?>
            <?php if ( $thumb ) : ?>
                <img src="<?php echo esc_url( $thumb['url'] ); ?>"
                     alt="<?php echo esc_attr( $thumb['alt'] ); ?>"
                     class="post-card__image">
            <?php endif; ?>
            <h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
            <p><?php the_field( 'excerpt_text' ); ?></p>
        </article>
    <?php endwhile;
endif; ?>

Using fields in a page template:

<?php
/**
 * Template Name: About Us
 */
get_header();

$team_photo   = get_field( 'team_photo' );
$mission      = get_field( 'mission_statement' );
$founded_year = get_field( 'founded_year' );
?>

<main class="about-page">
    <section class="about-hero">
        <?php if ( $team_photo ) : ?>
            <img src="<?php echo esc_url( $team_photo['url'] ); ?>"
                 alt="<?php echo esc_attr( $team_photo['alt'] ); ?>">
        <?php endif; ?>
        <div class="about-hero__content">
            <h1><?php the_title(); ?></h1>
            <?php if ( $mission ) : ?>
                <blockquote><?php echo esc_html( $mission ); ?></blockquote>
            <?php endif; ?>
            <?php if ( $founded_year ) : ?>
                <p class="founded">Established <?php echo esc_html( $founded_year ); ?></p>
            <?php endif; ?>
        </div>
    </section>
</main>

<?php get_footer(); ?>

Theme Support Declaration

There is no special add_theme_support() call required. Field Forge activates its compatibility layer automatically when ACF is not active. If ACF is active alongside Field Forge, the ACF functions take priority and Field Forge acts as a storage backend only. The same guard applies during wp-admin and WordPress plugin-API activation, so enabling ACF Pro after Field Forge is already active does not redeclare get_field().

Recommended Theme Structure

Organize your theme files for clean Field Forge integration:

my-theme/
  functions.php             # Load field setup, register blocks
  inc/
    fieldforge-setup.php    # Options pages, programmatic field groups
    template-functions.php  # Helper functions wrapping get_field()
  template-parts/
    content-*.php           # Partial templates using fields
    builder/                # Flexible content section templates
  blocks/                   # PHP block templates
  fieldforge-json/          # Local JSON sync directory (PRO)

Creating helper functions for repeated field patterns:

<?php
// inc/template-functions.php

/**
 * Get the hero image URL with a fallback.
 *
 * @param int|false $post_id Post ID or false for current post.
 * @return string Image URL.
 */
function theme_get_hero_image( $post_id = false ) {
    $image = get_field( 'hero_image', $post_id );
    if ( $image && isset( $image['url'] ) ) {
        return $image['url'];
    }
    return get_template_directory_uri() . '/assets/img/default-hero.jpg';
}

/**
 * Render social links from options page.
 */
function theme_render_social_links() {
    $platforms = [ 'facebook', 'twitter', 'instagram', 'linkedin', 'youtube' ];
    echo '<div class="social-links">';
    foreach ( $platforms as $platform ) {
        $url = get_field( 'social_' . $platform, 'options' );
        if ( $url ) {
            printf(
                '<a href="%s" class="social-link social-link--%s" target="_blank" rel="noopener">%s</a>',
                esc_url( $url ),
                esc_attr( $platform ),
                esc_html( ucfirst( $platform ) )
            );
        }
    }
    echo '</div>';
}

—