[su_posts template="templates/teaser-loop.php" posts_per_page="10" post_type="add-ons"]

Table of contents

  1. Description
  2. Options
  3. Pagination
  4. Built-in templates
  5. Template editing
  6. Creating custom templates

Description

The [su_posts] shortcode is intended for display of posts, pages, and various post types. You can display posts from a specific category or by a specific tag. You can also choose multiple taxonomies and select the number of displayed posts. This shortcode uses WP_Query class.

Options

Option namePossible valuesDefault value
template
Relative path to the template file. Default templates placed in the plugin directory (templates folder). You can copy them under your theme directory and modify as you want. You can use following default templates that already available in the plugin directory:
templates/default-loop.php – posts loop
templates/teaser-loop.php – posts loop with thumbnail and title
templates/single-post.php – single post template
templates/list-loop.php – unordered list with posts titles
Any text valuetemplates/default-loop.php
id
Enter comma separated ID’s of the posts that you want to show
Any text value– none –
posts_per_page
Specify number of posts that you want to show. Enter -1 to get all posts
Number from -1 to 1000012
post_type
Select post types. Hold Ctrl key to select multiple post types
Post type slug(s) separated by comma(s)post
taxonomy
Select taxonomy to show posts from
Taxonomy slug(s) separated by comma(s)category
tax_term
Select terms to show posts from
Term slug(s) separated by comma(s)– none –
tax_operator
Operator to test
IN (IN – posts that have any of selected categories terms)
NOT IN (NOT IN – posts that is does not have any of selected terms)
AND (AND – posts that have all selected terms)
IN
author
Enter here comma-separated list of author’s IDs. Example: 1,7,18
Any text value– none –
meta_key
Enter meta key name to show posts that have this key
Any text value– none –
offset
Specify offset to start posts loop not from first post
Number from 0 to 100000
order
Posts order
desc (Descending)
asc (Ascending)
DESC
orderby
Order posts by
none (None)
id (Post ID)
author (Post author)
title (Post title)
name (Post slug)
date (Date)
modified (Last modified date)
parent (Post parent)
rand (Random)
comment_count (Comments number)
menu_order (Menu order)
meta_value (Meta key values)
date
post_parent
Show childrens of entered post (enter post ID)
Any text value– none –
post_status
Show only posts with selected status
publish (Published)
pending (Pending)
draft (Draft)
auto-draft (Auto-draft)
future (Future post)
private (Private post)
inherit (Inherit)
trash (Trashed)
any (Any)
publish
ignore_sticky_posts
Select Yes to ignore posts that is sticked
yes or nono

Pagination

Unfortunately, pagination is currently not available in the shortcode. This function will be added in future versions.

Built-in templates

[su_posts] shortcode allows using various templates for display of posts. You can use several templates built into the plugin. Built-in templates are located in the /wp-content/plugins/shortcodes-ultimate/templates/ folder. The list of built-in templates is given below:

  • default-loop.php – posts loop
  • teaser-loop.php – posts loop with thumbnails and titles
  • single-post.php – single post template
  • list-loop.php – unordered list with post titles

Use template attribute to change the template. The value of this attribute should be a relative path to template file from plugin folder or folder of your theme. Shortcode example:

[su_posts template="templates/default-loop.php"]

In this example, search for the template will be made in the following locations (in the specified order):

  1. /wp-content/themes/child-theme/templates/default-loop.php
  2. /wp-content/themes/parent-theme/templates/default-loop.php
  3. /wp-content/plugins/shortcodes-ultimate/templates/default-loop.php

Template editing

Do not edit templates in the plugin folder, since all your changes will be lost after plugin update.

To change one of the built-in templates, you should copy it to the folder of your theme first. For convenience, you can copy the whole “templates” folder from plugin folder to the folder of your theme.  Folder with templates may have other names than “templates”. Resulting paths to template files should look like:

/wp-content/themes/your-theme/templates/

Now you can edit imported templates. As it was mentioned above, the plugin will search for a template file in the theme folder first.

Creating custom templates

You can create your own templates for [su_posts] shortcode, which makes it incredibly powerful. Your own templates should be created in the folder with your active theme. For example, you can create a folder “posts-templates” in the folder with your active theme. Create my-loop.php file in this folder and place the following code in it:

<?php
if ( $su_posts->have_posts() ) :
while ( $su_posts->have_posts() ) :
$su_posts->the_post();
echo '<h2>' . get_the_title() . '</h2>';
the_excerpt();
endwhile;
else :
echo 'Posts not found';
endif;

Now you can use the following shortcode to display posts with custom template:

[su_posts template="posts-templates/my-loop.php"]