Output, formats and escaping

There are two ways to read a field, and they behave differently on purpose.

The full function reference is in Developer API. This page lists what each type gives you.

The three ways to read

// 1. Raw value (you escape):
$price = wpmcf_get_field( 'product', 'price' );
echo esc_html( $price );

// 2. Printed and escaped by the field type:
wpmcf_the_field( 'product', 'price' );

// 3. Shortcode, in content or a widget:
echo do_shortcode( '[wpmcf_field group="product" field="price"]' );

// Is there a value? (0, "0" and false count as values; null, "" and [] do not)
if ( wpmcf_has_field( 'product', 'price' ) ) { /* … */ }

Which object is read?

The third argument names the object: null (the current post), a post ID, a WP_Post, WP_User, WP_Term or WP_Comment, or a reference string.

wpmcf_get_field( 'g', 'f' );                       // current post
wpmcf_get_field( 'g', 'f', 42 );                   // post 42
wpmcf_get_field( 'g', 'f', 'user_3' );             // user 3
wpmcf_get_field( 'g', 'f', 'term_5' );             // term 5 (also "category_5")
wpmcf_get_field( 'g', 'f', 'comment_7' );          // comment 7
wpmcf_get_field( 'g', 'f', 'option' );             // options page value
wpmcf_get_field( 'g', 'f', 42, [ 'context' => 'post' ] );

Arguments (the fourth argument and shortcode attributes)

A field that is not found, or an object that does not exist, returns the default (or null) and prints nothing. The default is not printed when the object itself does not exist.

The shortcode and visibility

The shortcode only prints values a visitor could see anyway. With id="…" it prints nothing for a post the visitor cannot view (draft, private, password-protected), for a user that is not themselves, the author of the current post or someone who can list users, and so on. wpmcf_get_field() and wpmcf_the_field() in theme code are trusted and unrestricted. The wpmcf/shortcode/can_view filter changes this.

What format="auto" does for each type

With the default auto format the field type prints its own best output.

Each type's page shows the same examples in detail.

The other formats

The other formats do not use the type's formatter. They take the raw value, turn an array into a comma-separated string of its simple items, and escape it for one context. Use them for values that you place in HTML attributes, URLs or scripts.

Examples with a stored select value a&b (label A & B):

So with a non-auto format a Select prints its stored value, not its label; a True / false prints 1 for on and nothing for off; and a Link prints its parts as url, title, instead of a link. Keep auto for those types and use url only for URL, Page link and similar text values.

[wpmcf_field group="company" field="website" format="url" wrap="false"]
[wpmcf_field group="company" field="tagline" format="attr" wrap="false"]

The wrapper and Display options

Every printed value is wrapped in <span class="wpmcf-field-value">, with the field's Prefix, Suffix, Wrapper CSS class and Wrapper HTML ID from the Display tab (see Settings every field has).

<span id="price-box" class="wpmcf-field-value price">$19.9 USD</span>

For block-level output (WYSIWYG, Repeater, Relationship, Map, Image) use wrap="false" or 'wrap' => false, otherwise the span would contain block elements.

Escaping rules in short

• wpmcf_get_field() returns unescaped data. Always escape on output: esc_html(), esc_attr(), esc_url(), wp_kses_post().
• wpmcf_the_field() and the shortcode escape for you (and the Display options are escaped too).
• Rich text is filtered when saved (wp_kses_post) and again when printed.
• Passwords are never printed or returned by the variable engine.

Variables in values

A stored string can contain {{ expression }} (the edit screen offers an insert button on Text, Text area, Email and URL fields). wpmcf_get_field(), wpmcf_the_field() and the shortcode resolve the expressions when the person who wrote the value may post unfiltered HTML (the post's author, or the user themself for user fields); comment values are never resolved. A filter, wpmcf/field/resolve_variables, can override that.

Filters for developers

REST API

When a field group has REST enabled, a post's REST response contains the same values as wpmcf_get_field() under wpmcf, grouped by field group key:

{ "wpmcf": { "faq": { "items": [ { "question": "…" } ], "featured": true, "location": { "address": "A", "lat": 1, "lng": 2, "zoom": 13 } } } }

Writing goes through the same sanitizers as the edit screen; password fields are never returned.

Troubleshooting

• Nothing prints. The field is empty, the object cannot be found, the visitor cannot view the object (shortcode with id), or the field is a Group, Accordion, Tab or Password (see their pages).
• I see & where I expect &. That is correct HTML. wpmcf_the_field() escapes; the browser shows &.
• My default text is not shown. default is used when the object exists and the field is empty. It is not printed when the object itself cannot be found.
• A shortcode in a WYSIWYG value did not run. It runs only in printed output, not in wpmcf_get_field().