Skip to content
Developer API

Output formats and escaping

3 min read

The printing functions

php
wpmcf_the_field( string $group_key, string $field_key, mixed $object = null, array $args = [] ): void
wpmcf_the_option_field( string $group_key, string $field_key, array $args = [] ): void
wpmcf_the_global( string $key, array $args = [] ): void

They echo an escaped, formatted value and return nothing. Empty values print nothing (no empty wrapper). They take the arguments of the matching get function (path, sub_key, default, context, widget_*) plus two output arguments.

format

format

Escaping

Use it for

auto (default)

The field type formats the value: a Select prints its label, a True / false prints Yes/No (or your labels), a URL field prints an escaped URL, a Link field prints an <a>, an Image field prints an <img>, a Repeater prints an ordered list.

Plain output of whatever the field is.

html

esc_html() on the value as one string

Text inside an element

attr

esc_attr()

Inside an attribute value

url

esc_url()

An href or src (only meaningful for URL-like values: on plain text it produces a mangled http://... string)

js

esc_js()

Inside inline JavaScript strings

post_html

wp_kses_post()

Rich text you want to keep basic markup of

Any other value of format falls back to auto. For every format except auto, an array value is flattened to its scalar items joined with , (a Checkbox ['red', 'blue'] prints red, blue: the stored values, not the labels), and nested arrays are dropped. A Group or Repeater with a non-auto format therefore prints nothing useful: use a path to print one sub-value, or auto for a Repeater's list markup.

Verified output for a text value Hello W & "q":

format

Output

auto, html, attr, js

Hello W &amp; &quot;q&quot;

post_html

Hello W &amp; "q"

url

http://Hello%20W%20&#038;%20q

wrap

By default the output is wrapped in a <span> that carries the field's Advanced display settings (wrapper class, wrapper ID, prefix, suffix):

html
<span id="a03id" class="wpmcf-field-value a03 big">[Hello]</span>
  • The span always has the class wpmcf-field-value (wpmcf-global-value for Global Data). The field's Wrapper class is added, its Wrapper ID becomes the id.
  • Prefix and suffix (the [ and ] above) are escaped with esc_html() and printed inside the span.
  • 'wrap' => false removes the span and with it the prefix and suffix: you get the bare escaped value.

Values that switch the wrapper off: false, 0, '0', 'false', 'no', 'off' (case-insensitive). Anything else keeps it.

php
wpmcf_the_field( 'listing', 'title' );                         // <span class="wpmcf-field-value">...</span>
wpmcf_the_field( 'listing', 'title', null, [ 'wrap' => false ] ); // bare text

default

The default is used when the stored value is NULL and is escaped like any value:

php
wpmcf_the_field( 'listing', 'note', $id, [ 'default' => 'No note <b>' ] ); // prints: No note &lt;b&gt;

For Global Data the default is printed for a missing and an empty variable (see Global Data functions).

What is never printed

  • Password fields print nothing unless the wpmcf/field/the_password filter returns true (and then only plain or encrypted passwords, never a hash). See Password helpers and security.
  • Non-scalar values that the field type cannot format (for example a Group with auto) print nothing.
  • An empty value prints nothing, so there is no empty <span> to clean up.

Examples

php
// In an attribute: use the raw getter and esc_attr(); a printing function would echo its span there.
printf(
    '<div data-city="%s">',
    esc_attr( (string) wpmcf_get_field( 'listing', 'details', null, [ 'path' => 'city' ] ) )
);

// A link made of two fields.
printf(
    '<a href="%s">%s</a>',
    esc_url( (string) wpmcf_get_field( 'listing', 'website' ) ),
    esc_html( (string) wpmcf_get_field( 'listing', 'title' ) )
);

// A rich text field: keep post-level HTML.
wpmcf_the_field( 'listing', 'description', null, [ 'format' => 'post_html', 'wrap' => false ] );

// Options page value in the footer.
wpmcf_the_option_field( 'site_settings', 'company_name', [ 'wrap' => false ] );

Raw getter or printing function?

Use

When

wpmcf_the_*

The value goes straight into the page body and you want the type's own formatting (labels, links, images, lists) and the Advanced display wrapper.

wpmcf_get_* + your own escaping

You build markup yourself (attributes, href, JSON for a script, calculations). Escape with the function that fits the place: esc_html(), esc_attr(), esc_url(), wp_json_encode(), wp_kses_post().

Never echo a wpmcf_get_* result without escaping. Values come from editors, visitors (forms), imports and other plugins.

Hooks for output

wpmcf/field/the_escaped (the escaped inner text) and wpmcf/field/the_html (the final markup, including the wrapper) filter field output; wpmcf/global/the_escaped and wpmcf/global/the_html do the same for Global Data. See Variables and hooks.

How the same escaping is shared

[wpmcf_field] and [wpmcf_global] use the same code path as the printing functions (see Shortcodes). The block and Block Bindings use their own formatter described in Blocks and Block Bindings.

Was this page helpful?

Still stuck? Contact support