# WordPress

The following directives are specific to WordPress core functionality.

# @query

@query initializes a standard WP_Query as $query and accepts the usual WP_Query parameters (opens new window) as an array.

@query([
  'post_type' => 'post'
])

# @posts

@posts begins the post loop and by default, assumes that WP_Query is set to $query (which is the case when using @query). It is wrapped in a have_posts() conditional and thus will return null if no posts are found.

Inside of the @posts loop you have full access to the Blade Loop Variable (opens new window).

@endposts is available to end your loop and have_posts() conditional as well as resetting your loop with wp_reset_postdata() (opens new window).

@query([
  'post_type' => 'post'
])

@posts
  <h2 class="entry-title">@title</h2>
  <div class="entry-content">
    @content
  </div>
@endposts

If an instance of WP_Query is passed to @posts, it will use that instead:

@php
  $query = new WP_Query([
    'post_type' => 'post'
  ]);
@endphp

@posts($query)
  <h2 class="entry-title">@title</h2>
  <div class="entry-content">
    @content
  </div>
@endposts

Additionally, you can pass a single post ID, post object, or an array containing a mixture of the two:

@posts(12)
  <h2 class="entry-title">@title</h2>
  <div class="entry-content">
    @content
  </div>
@endposts

@posts(get_post(4))
  <h2 class="entry-title">@title</h2>
  <div class="entry-content">
    @content
  </div>
@endposts

@posts([6, get_post(9), 3])
  <h2 class="entry-title">@title</h2>
  <div class="entry-content">
    @content
  </div>
@endposts

When passing an array of ID's / objects, the posts will be sorted by the order of the array.

If @query is not used and an argument is not passed to @posts, it will use the main loop from the $wp_query global.

# @hasposts

@hasposts accepts the same exact arguments as @posts, but simply runs a conditional without the while loop. It can be closed using @endhasposts.

@hasposts
  <ul>
    @posts
      <li>@title</li>
    @endposts
  </ul>
@endhasposts

# @noposts

@noposts again has the exact same arguments as @posts, but runs a ! conditional without the while loop. It can be closed using @endnoposts.

@noposts
  <div class="py-2 px-4 bg-red-500 text-white">
    🏜️
  </div>
@endnoposts

# @postmeta

@postmeta allows you to get the post meta for a post using get_post_meta (opens new window).

@postmeta will always expect a key as the first argument with an optional post_id for the second.

The third argument is optional and allows you to control the $single bool to only return a single value.

@postmeta('key')
@postmeta('key', 1)
@postmeta(1)
@postmeta('key', 1, true)

# @title

@title echo's the current posts title using get_the_title() (opens new window).

@title

To echo the title of a specific post, you can pass the post ID or a WP_Post instance as a parameter:

@title(1)
@title(get_post(1))

# @content

@content echo's the current posts content using the_content() (opens new window).

@content

# @excerpt

@excerpt echo's the current posts excerpt using the_excerpt() (opens new window).

@excerpt

# @permalink

@permalink echo's the current posts URL using get_permalink() (opens new window).

@permalink

To echo the URL of a specific post, you can pass the post ID or a WP_Post instance as a parameter:

@permalink(1)
@permalink(get_post(1))

# @thumbnail

@thumbnail echo's the current posts featured image using get_the_post_thumbnail (opens new window). By default, it passes thumbnail as the size.

@thumbnail

To echo the featured image of a specific post, you can pass the post ID or a WP_Post instance as the first parameter:

@thumbnail(1)
@thumbnail(get_post(1))

To echo the featured image with a specific size, you can either pass it as a parameter by it's self, or as the second parameter when a post ID or WP_Post instance is present:

@thumbnail('full')
@thumbnail(1, 'full')
@thumbnail(get_post(1), 'full')

To echo the featured image URL (without img markup), you can pass false as the last parameter on any of the above options:

<img src="@thumbnail(false)" alt="My Image" />
<img src="@thumbnail(1, false)" alt="Post 1" />
<img src="@thumbnail(get_post(1), false)" alt="Post 1" />
<img src="@thumbnail('full', false)" alt="Full Image" />
<img src="@thumbnail(1, 'full', false)" alt="Post 1's Full Image" />
<img src="@thumbnail(get_post(1), 'full', false)" alt="Post 1's Full Image" />

# @author

@author echo's the author of the current posts display name.

@author

To echo the display name of a specific author, you can pass the author's ID as a parameter:

@author(1)

# @authorurl

@authorurl echo's the author of the current posts archive URL.

<span class="author" itemprop="author" itemscope itemtype="http://schema.org/Person">
  <a href="@authorurl" itemprop="url">
    <span class="fn" itemprop="name" rel="author">@author</span>
  </a>
</span>

To echo the URL of a specific author, you can pass the author's ID as a parameter:

<a href="@authorurl(2)">@author</a>

# @published

@published echo's the current posts published date. By default, it uses the date format set in Settings > General.

@published

To change the formatting of the date (opens new window), you can pass it as the first parameter:

<time class="entry-time">
  <span>@published('F j, Y')</span>
  <span itemprop="datePublished" content="@published('c')"></span>
</time>

To echo the published date of a specific post, you can pass a post ID or an instance of WP_Post as the first parameter:

@published(1)
@published(get_post(1))

To format the published date of a specific post, you can pass the format as the first parameter, and the post ID or instance of WP_Post as the second parameter:

@published('F j, Y', 1)
@published('F j, Y', get_post(1))

# @modified

@modified is similar to @published, but instead echo's the current posts last modified date. By default, it uses the date format set in Settings > General.

@modified

To change the formatting of the date (opens new window), you can pass it as the first parameter:

<time class="entry-time">
  <span>@published('F j, Y')</span>
  <span itemprop="datePublished" content="@published('c')"></span>
  <span itemprop="dateModified" class="updated" content="@modified('c')"></span>
</time>

To echo the modified date of a specific post, you can pass a post ID or an instance of WP_Post as the first parameter:

@modified(1)
@modified(get_post(1))

To format the modified date of a specific post, you can pass the format as the first parameter, and the post ID or instance of WP_Post as the second parameter:

@modified('F j, Y', 1)
@modified('F j, Y', get_post(1))

# @category

@category echo's the first category of the current post.

@category

To echo the category as a link, pass true as a parameter:

@category(true)

To echo the category of a specific post, pass the post ID as a parameter:

@category(1)

To echo the category of a specific post as a link, pass the post ID as the first parameter, and true as the second parameter:

@category(1, true)

# @categories

@categories echo's a comma seperated list of the current post's categories.

@categories

To echo the categories of a specific post, pass the post ID as the first parameter:

@categories(1)

Similar to @category, if you would like to return the categories as links, pass true as the first parameter when by it's self, or as the second parameter when a post ID is present:

@categories(true)
@categories(1, true)

# @term

@term echo's the taxonomy term of the current post. If multiple terms are present, it will echo the first term returned in the array.

@term('genre')

Similar to @category, if you would like to return the terms of a specific post or as links, you can follow the same syntax, except keeping the taxonomy name as the first parameter:

@term('genre', 1)
@term('genre', 1, true)
@term('genre', true)

# @terms

@terms echo's a comma seperated list of the taxonomy terms of the current post.

@terms('genre')

It accepts the same parameters as @term:

@terms('genre', 1)
@terms('genre', 1, true)
@terms('genre', true)

# @image

@image echo's an image using wp_get_attachment_image() (opens new window).

Since I find this mostly useful with ACF fields (being that it automatically handles responsive image sizes), if ACF is present and a field name in the form of a string is passed as the first parameter, @image will attempt to deep-dive get_field() and get_sub_field() to retrieve your image field. If the image returns as an array instead of an id, the directive will automatically check for the existance of $image['id'] and pass that value to wp_get_attachment_image().

By default, @image uses the thumbnail image size and the default media library attachment alt tag.

@image(1)

Optionally, pass it an image size and an alt tag:

@image(1, 'full', 'My alt tag')

If you require an image without a set width, height, or srcset, our friends at WordPress core don't agree (opens new window) with you and their word is law.

But since we do what we want, you can pass raw as an image size to return the attachment URL and build the image markup yourself.

<img src="@image(1, 'raw')" alt="Take that, WordPress." />

Outside of a raw image, if you need access to the <img> tag attributes directly, use an array as the third parameter instead:

@image(1, 'thumbnail', ['alt' => 'My alt tag', 'class' => 'block w-32 h-32'])

Accessing an ACF field, sub field, or even option field is just as easy:

@image('my_image_field')
@image('my_image_field', 'full', 'My alt tag')
@image('my_image_field', 'thumbnail', ['alt' => 'My alt tag', 'class' => 'block w-32 h-32'])

<img src="@image('my_image_field', 'raw')" alt="My alt tag" />

# @shortcode

@shortcode echo's the specified shortcode using do_shortcode() (opens new window).

@shortcode('[my-shortcode]')

# @role

@role allows you to display specific content only to users who are logged in and have a specific role. With wp_get_current_user()->roles (opens new window) returning an array of roles in all lowercase, the passed role is automatically lowercased using strtolower. It can be closed using @endrole.

@role('author')
  This content is only displayed to Authors.
@endrole

@role('author', 'contributor')
  This content is only displayed to Authors and Contributors.
@endrole

# @user

@user is a simple is_user_logged_in() conditional to display specific content only when a user is logged in. It can be closed using @enduser.

@user
  You are logged in!
@enduser

# @guest

@guest is a simple ! is_user_logged_in() conditional to display specific content only when a user is not logged in. It can be closed using @endguest.

@guest
  You must be <a href="/wp-login.php">logged in</a> to view this content.
@endguest

# @wpautop

@wpautop runs a passed string through wpautop() (opens new window) and echo's the output.

@wpautop($content)

# @wpautokp

@wpautokp does the same as @wpautop but also sanitizes the string with wp_kses_post() (opens new window).

@wpautokp($content)

# @action

@action allows you to trigger a WordPress action through the use of do_action (opens new window).

@action('get_footer')

# @filter

@filter echoes the result of what its been passed through the use of apply_filters (opens new window).

@filter('the_content', 'some string')

# @wphead

This is just a directive version of wp_head (opens new window).

# @wpfooter

This is just a directive version of wp_footer (opens new window).

# @bodyclass

@bodyclass behaves just as body_class (opens new window) does. You can pass strings to it to have them added to the body class. Has the same limitations on passing arrays as any other directive.

@bodyclass('add-me')

# @wpbodyopen

This is a directive version of wp_body_open (opens new window) except that it will work on WordPress versions below 5.2.

# @postclass

@postclass functions the same as post_class (opens new window) accepting an optional class and post ID.

@postclass
@postclass('bg-white')
@postclass('bg-white', $post->ID)

@sidebar is a simply directive that calls dynamic_sidebar (opens new window).

It comes with two assisting directives @hassidebar and @endhassidebar that checks for the existence of the sidebar using is_active_sidebar (opens new window).

@sidebar('sidebar-primary')

@hassidebar('sidebar-primary')
  @sidebar('sidebar-primary')
@endhassidebar

# @thememod

@thememod echoes the result of get_theme_mod (opens new window) function accepting theme modification name and optional default value

@thememod('header-bg-color')
@thememod('header-bg-color', '#fff')

← Sage Directives ACF →