Helpers

Each of these helpers will save you time and img just may change your life. 😉

If you aren't using Advanced Custom Fields, how do you live?! Go now and buy Advanced Custom Fields Pro. If you build sites, get the "Developer" version so you can pay once and use it all over the place. With that out of the way, let's talk about how WPM makes working with ACF a breeze.

Forget all those get_field and get_fields calls. Don't do that. You're a while loop away from making your site slower than molasses. Do a few calls, get everything you need and get on with making that killer site. The way you do this is by creating groups, repeaters, and flexible content. Then use a group name as your selector (more on that in a bit), get everything in an associative array, and develop away. No more bring your database to its knees.

->postId()

To get fields from a post, pass it's ID into the postId method. If the current global post is the post you want to get fields from, you can skip the postId call. Behind the scenes acf will default to global $post if you don't specify an ID.

// get all fields in the 'banner_image' group from the current global post
$page_banner = wpm('acf')->selector('page_banner')->get();

// get all fields in the 'banner_image' group from by post ID
$page_banner = wpm('acf')->postId($post->ID)->selector('page_banner')->get();

->selector()

Use selector to choose which field, or preferrably group / repeater / flexible content, you'd like to return. By default, all ACF fields will return with formatting as outlined in the field group settings. You can turn this off by passing false as the second argument.

// get all fields in the 'banner_image' group from the current global post
$page_banner = wpm('acf')->selector('page_banner')->get();

// get the blurb without formatting
$blurb = wpm('acf')->postId($post->ID)->selector('blurb', false)->get();

->options()

To get fields from an Options Page, use the options method instead of a postId.

// get 'copyright_info' field from options page
$copyright = wpm('acf')->options()->selector('copyright_info')->first();

->get()

As with q, get will return your requested data. If you provide a selector, it will get all that selector's information and all of its children's information. If you don't use a selector and use get you will get all fields.

// get all fields stored in 'promo' group
$promo = wpm('acf')->selector('promo')->get();

// get all fields on options page
$options = wpm('acf')->options()->get();

->first()

The first method requires a selector to get a single field and all of it's children. get also gets the first field when providing a selector so there isn't much need in calling first.

$lyrics = wpm('acf')->selector('lyrics')->first();

dd()

With die & dump is a big help with you're troubleshooting the results of a query or need to know what the object you have contains. While you wouldn't use dd in production, you'll use it a lot in developing a site to check your data.

If it's a variable or a return, you can use dd to check its contents.

// get all members
$members = wpm('q.member')->get();

// die and dump the contents of $members to the page
dd($members);

img is on the fly image creation and caching. It works perfectly with featured image or Advanced Custom Fields. When you need to add an image to your theme dynamically, use img to define the image area and then pass it the id of the image to display via the media method. With img you do not need to predefine your image sizes in your function file or use one of WordPress' 3 image sizes. This frees designers and developers to select image sizes that work well in each part of the theme without worrying about the rest.

img can return an the new image url, the complete image tag and can accept an array that will allow you to adjust the image tag's attributes.

->media()

The media method expects either an ID or the URL to an image stored in WordPress' media library. For more flexibility, I recommend sending in the ID.

echo wpm('img')->media(766)->resize(200, 150)->get();

->fit()

fit allows you to define an area the image should fit within. The image will only be scaled proportionally to fit in this area and will not be cropped. Fit will not automatically create an image that is beyond the natural width and height although this can be forced with the upscale method.

// create an image element that will fit in a width of 300px
// and a proportional height
$img = wpm('img')->media(766)->fit(300)->get();

// return a url of an image that will fit in a width of 300px
// and a proportional height
$img_url = wpm('img')->media(766)->fit(300)->url();

// return an image, as above, and add a border of 1px with the
// "style" attribute
$img = wpm('img')->media(766)->fit(300)->get(['style' => 'border: 1px solid red']);

// return an image that will fit in a 400x200 area
$img = wpm('img')->media(766)->fit(400, 200)->get();

// return an image that will fit in a height of 200px by the proportional width
$img = wpm('img')->media(766)->fit(null, 200)->get();

// provide an image that will fit in an area of 500x500 and force it to
// the largest size possible
$img = wpm('img')->media(766)->fit(500, 500)->upscale()->get();

// provide an image, as above, but set teh quality to 50%
$img = wpm('img')->media(766)->fit(500, 500)->quality(50)->get();

->resize()

While fit only scales an image, resize will create a new image that is cropped to the given dimensions. It does this by scaling the image proportionally to either the given width or height and then cropping the center of the image by the opposing pixel dimension.

As an example, an image of size 1400x1200 being resized to 300x150 will be scaled to a width of 300 and a proportional height. Next the image will be cropped to display the center 150px vertically and cutting off the top and bottom.

If the original image is 500x1000, it would fit the height first to 150px and then cut the width to the middle 300px cropping the left and right.

// resize an image to 300px in width by the proportional height and return
// the url to the new image
$img = wpm('img')->media(766)->resize(300)->url();

// resize an image to 300px in width by proportional height and return the
// image tag
$img = wpm('img')->media(766)->resize(300)->get();

// resize an image to 400x200 and return an image tag with a set border style
$img = wpm('img')->media(766)->resize(400, 200)->get(['style' => 'border: 1px solid red']);

// resize an image to 500x500 and scale the image beyond its natural limits
// if necessary
$img = wpm('img')->media(766)->resize(500, 500)->upscale()->get();

// resize an image to 500x500 with the image quality of 50%
$img = wpm('img')->media(766)->resize(500, 500)->quality(50)->get();

->quality()

Use the quality method to change the image quality default from 95 to another value.

// set the quality to 50%
$img = wpm('img')->media(766)->fit(500, 500)->quality(50)->get();

->upscale()

By default, img will not scale and image higher than it's natural width and height. If you need to force the image to scale to any size set, use the upscale method.

// force image to 1000x300 regardless of natural image size
$img = wpm('img')->media(766)->resize(1000, 300)->upscale()->get();

->get()

The get method will get your formatted image as a img element ready to be echoed on the page. You can update any attribute to this img element by passing in an array to the get method.

echo wpm('img')->media(766)->fit(300, 200)->get(['class' => 'img-fluid']);

->url()

Sometimes you may need to resize an image to appear as the background of an element via css. Instead of returning the img element with get, you'll instead want to get the url to the new image.

$bg_img = wpm('img')->media(766)->resize(500, 500)->url();

Paginating results requires previous/next buttons or a numeric page navigation menu. Let these helper functions do the work for you.

// get the previous page url
$url = wpm('wp.nav')->prev();

// get a link to the previous page url
$url = wpm('wp.nav')->prev('Previous');

// get the next page url
$url = wpm('wp.nav')->next();

// get a link to the next page url
$url = wpm('wp.nav')->next('Next');

// echo a numeric page navigation.
echo wpm('wp.nav')->paginate();

// echo a numeric page navigation and pass in arguments to get_the_posts_pagination
echo wpm('wpm.nav')->paginate([
    'prev_text' => 'Prev',
    'next_text' => 'Next'
]);

wpm_post()

The results data returned when preforming a WPM q query includes author, children, meta, tag, term and ancestor helpers. You can make any post a WPM Post by passing it into the handy wpm_post function and capturing the result.

global $post;
$post = wpm_post($post);

$author_name = $post->author()->name();