Themeisle Docs

Appearance

Using MPG Placeholders in Custom PHP Templates ​

This guide explains why MPG placeholders like {{mpg_city}} appear as plain text in custom PHP theme templates and how to make them render correctly in those contexts.

In this article

How MPG Pages Are Generated ​

Each MPG project uses a Template page — a regular WordPress page or post that you design in the editor (Gutenberg, Elementor, etc.) and assign in the project settings under the Template dropdown. When a visitor opens a generated URL, MPG intercepts the request, loads the template page's content, replaces all placeholders with data from your source file, and serves the result.

MPG performs this replacement by rewriting the page's post content directly (on the template_redirect hook) and through output buffering. It does not use WordPress's the_content filter. This is why content that never becomes part of the rewritten post content, such as values you echo directly in a PHP template, is not processed automatically.

When Custom PHP Templates Are Needed ​

In most cases, designing your layout inside the MPG Template page in the WordPress editor is sufficient. However, there are situations where a developer builds custom PHP theme templates that output content outside of the standard post content area:

  • A theme has a custom post type template (e.g., single-location.php) that renders additional fields or sections directly in PHP, bypassing the block editor content.
  • A developer builds a header, sidebar, or footer section in a PHP template file that reads values from the post and echoes them directly.
  • A custom theme template uses get_post_meta() to pull values and display them outside the main content loop.

In all these cases, any {{mpg_placeholder}} text output directly in PHP will not be processed, because MPG only rewrites the generated page's post content, not content you output yourself.

Rendering Placeholders in Custom PHP Templates ​

To render MPG placeholders inside a custom theme template file, pass the content through MPG's own replacement function, MPG_CoreModel::mpg_shortcode_replacer( $content, $project_id ).

⚠️ Important: Passing content through apply_filters( 'the_content', $content ) does not trigger MPG's replacement, because MPG does not hook into the the_content filter. Use mpg_shortcode_replacer() instead.

Example — outputting a static string with placeholders:

php
<?php
$project_id = 123; // Replace with your MPG project ID
$content    = 'Welcome to {{mpg_city}}! Explore the best services in {{mpg_state}}.';

if ( class_exists( 'MPG_CoreModel' ) ) {
    $content = MPG_CoreModel::mpg_shortcode_replacer( $content, $project_id );
}

echo wp_kses_post( $content );
?>

Example — reading a post meta value that contains placeholders:

php
<?php
$project_id = 123; // Replace with your MPG project ID
$content    = get_post_meta( get_the_ID(), 'your_meta_key', true );

if ( class_exists( 'MPG_CoreModel' ) ) {
    $content = MPG_CoreModel::mpg_shortcode_replacer( $content, $project_id );
}

echo wp_kses_post( $content );
?>

Replace 123 with the numeric ID of your MPG project, which you can find in the URL when editing a project in All Projects.

📝 Note: MPG_CoreModel::mpg_shortcode_replacer() runs only MPG's own replacement logic. Wrapping the result in wp_kses_post() is a WordPress best practice that allows safe HTML tags while stripping potentially dangerous markup.

Common Pitfalls and Troubleshooting ​

Placeholders still appear as plain text ​

  • Confirm the project is set up. Go to All Projects and make sure the project has been created and saved, and that its source data and template are configured.
  • Check placeholder spelling. Placeholder names are derived directly from your data source column headers (CSV, Google Sheet, etc.). For example, a column named city becomes {{mpg_city}}. There is no need to add mpg_ manually — MPG adds that prefix automatically when reading headers.
  • Pass the right project ID. mpg_shortcode_replacer() needs the ID of the project whose data you want to use. Double-check the ID you passed matches the project.
  • Test in standard post content first. Open the MPG Template page in the WordPress editor, add a block with the same placeholder text, and preview a generated URL. If the placeholder renders there, the issue is specific to your custom template. If it does not render there either, see How to Solve MPG Tags that are Not Parsed?.

The output is modified in unexpected ways ​

mpg_shortcode_replacer() returns raw content. If the surrounding output looks wrong:

  1. Test the template on a staging environment with only MPG and the default theme active.
  2. Progressively re-enable other plugins to identify any conflict.
  3. Make sure you are not also passing the content through apply_filters( 'the_content', $content ), since that runs unrelated callbacks (SEO plugins, caching plugins, page builders) without triggering MPG's replacement.

Verifying the Fix ​

After calling mpg_shortcode_replacer() in your template, open a generated URL in your browser and confirm that the placeholder values are replaced with real data from your source file. If you still see {{mpg_city}} instead of an actual city name, review the troubleshooting steps above or consult the MPG Troubleshooting Guide.

Was this helpful?