Meta and ACF

Meta and ACF

Read

Every model (Post, Page, Media, User, Category, Tag, Comment, and your own ISelfRepresentative models) has:

Member	Returns
meta	The raw meta object
metaValue<T>(key)	meta[key] as T, or null
acf	The raw acf map (Advanced Custom Fields), or null
acfValue<T>(field)	acf[field] as T, or null

final post = (await client.posts.retrieve(RetrievePostRequest(id: 42))).dataOrThrow();

final rating = post.metaValue<int>('rating');
final featured = post.metaValue<bool>('featured');
final price = post.acfValue<double>('price');
final launch = post.acfValue<DateTime>('launch_date');
final gallery = post.acfValue<List<dynamic>>('gallery');

WordPress often stores numbers and booleans as strings, so values are converted leniently:

T	Accepts
int, double, num	Numbers and numeric strings ('12')
bool	true/false, 1/0, '1'/'0', 'true'/'false', 'yes'/'no', 'on'/'off', '' as false
String	Strings, numbers, booleans
DateTime	ISO dates and ACF date pickers (20240131)
anything else	The value when it already has that type

A missing key or a value that cannot be converted gives null; nothing throws.

Write

Create and update requests take meta and acf maps:

await client.posts.update(
  UpdatePostRequest(
    id: 42,
    meta: {'rating': 5},
    acf: {'price': 9.5, 'launch_date': '20240131'},
  ),
);

acf is available on create and update for posts, pages, categories, tags, users and comments, and on update for media.

Make the fields visible

• Meta must be registered with show_in_rest:

  register_post_meta('post', 'rating', [
      'type' => 'integer',
      'single' => true,
      'show_in_rest' => true,
  ]);

• ACF field groups need "Show in REST API" turned on (ACF 5.11+). The values appear under acf.

Writes also need a user with permission to edit the item. Unregistered meta keys are silently ignored by WordPress.

Custom post types

metaValue and acfValue work on any ISelfRepresentative, including models made by the Model Generator and used with client.resource.