Australia's Leading Digital Marketing Experts. T. 1300 235 433  |  Aggregation Enquires Welcome

Create a Series Reading List with WordPress Shortcode

Create a Series Reading List with WordPress Shortcode

This article will show you how to include a list of posts in a series based on WordPress tags. An older version of this shortcode included both a series list and related list in the same function. However, because of the perceived attribute confusion and associated complexity we've sensibly split them into two.

A tag, not unlike a social hashtag, can often be unique to tie a specific sub-group of articles together. This article will tie these distinct hashtags into a reading list - not unlike an article split into chapters of a book.

WordPress tags must be the most misunderstood and underutilized feature of WordPress. They should normally be used to tie posts together into a sub-set of associated or connected articles. They're often used, however, in a haphazard way with tagged words that are rarely connected and seldom structured.

Since we don't have any series posts (yet) we'll bundle all the posts tagged with wp_query into a series (in reality the posts are better served by a related reading list). The shortcode of [series tags="108"] returns the following:

  1. Display a List of Child Pages With WordPress ShortcodeMay 28, 2017
  2. Display Future Scheduled Posts in WordPressJune 1, 2017
  3. Display the Total Number of Scheduled, Draft, or Published Posts (or by Author) with WordPress ShortcodeJune 24, 2017
  4. Display Random Posts in WordPressJune 27, 2017
  5. Create a Series Reading List with WordPress ShortcodeJuly 2, 2017
  6. WordPress Post & Page Dropdown MenuJuly 7, 2017

Scheduled (and unlinked) articles may be included in the list with an icon and text indicating their status. Shortcode of [series tags="108" status="publish,future"] returns the following list. The screenshot was taken when most articles were scheduled and, as such, this article shows as both a future article and the current page.

Create a Series Reading List with WordPress Shortcode

WordPress Shortcode

Copy and paste the WordPress function into your theme's functions.php file or, if you sensibly have one installed, your custom functions plugin. You may optionally download and install our plugin from the bottom of of the page.

1
<?php 
2
/*
3
 Display WordPress Post Series
4
 http://www.beliefmedia.com/wordpress-series
5
*/
6
 
7
function beliefmedia_series_posts($atts) {
8
 
9
  $atts = shortcode_atts(array(
10
    'tags' => false,
11
 
12
    /* Status */
13
    'status' => 'publish',
14
 
15
    /* Future Posts Image */
16
    'image' => '',
17
    'align' => '-2',
18
 
19
    /* Optional */
20
    'format' => false, /* jS F Y, g:iA */
21
    'description' => false,
22
    'remove' => false,
23
    'words' => 15,
24
    'number' => false,
25
    'numbered' => true,
26
 
27
    /* Rarely used .. */
28
    'author' => false,
29
    'category' => false,
30
    'orderby' => 'date',
31
    'order' => 'ASC',
32
 
33
    /* Style */
34
    'headingstyle' => false,
35
    'datestyle' => false,
36
    'textstyle' => false,
37
    'currentpagestyle' => false,
38
 
39
    /* Cache */
40
    'cache' => 3600 * 2,
41
 
42
  ), $atts);
43
 
44
 $transient = 'bmfp_' . md5(serialize($atts));
45
 $cachedposts = get_transient($transient);
46
 
47
 if ($cachedposts !== false) {
48
 return $cachedposts;
49
 
50
 } else {
51
 
52
    /* A tag is required.. */
53
    if ($atts['tags'] === false) return '
54
<ul>
55
<li>No series tag provided.</li>
56
</ul>
57
 
58
';
59
 
60
    global $post;
61
 
62
    /* Current page */
63
    $the_current_page = $post->ID;
64
 
65
    /* If Image empty use a HTML entity */
66
    if ($atts['image'] == '') $atts['clock'] = '&#9202';
67
 
68
    /* If styles aren't defined */
69
    if ($atts['headingstyle'] === false) $atts['headingstyle'] = 'font-weight: bold;';
70
    if ($atts['datestyle'] === false) $atts['datestyle'] = 'font-size: 0.9em;';
71
    if ($atts['textstyle'] === false) $atts['textstyle'] = 'font-size: 0.9em;';
72
    if ($atts['currentpagestyle'] === false) $atts['currentpagestyle'] = 'text-decoration: none; font-weight: normal;';
73
 
74
    /* Generally use this shortcode for series posts */
75
    $post_status = explode(',', $atts['status']);
76
 
77
    $args = array(
78
        'post_type' => 'post',
79
        'post_status' => $post_status,
80
        'orderby' => $atts['orderby'],
81
        'order' => $atts['order'],
82
    );
83
 
84
    /* Get user ID from login username */
85
    if ($atts['author'] !== false) {
86
 
87
      /* Array of authors */
88
      $atts['author'] = explode(',', $atts['author']);
89
 
90
        /* If not numeric, get ID */
91
        foreach ($atts['author'] AS $authors) {
92
          if (!is_numeric($authors)) {
93
            $author_ob = get_user_by( 'login', $authors );
94
            $author .= $author_ob->ID . ',';
95
          } else {
96
            $author .= $authors . ',';
97
          }
98
        }
99
 
100
     /* Return string of authors */
101
     $atts['author'] =  rtrim($author, ',');
102
    }
103
 
104
    /* Limit authors? */
105
    if ($atts['author'] !== false) $args['author'] = $atts['author'];
106
 
107
    /* Specific categories? */
108
    if ($atts['category'] !== false) $args['cat'] = $atts['category'];
109
 
110
    /* Specific tags? */
111
    if ($atts['tags'] !== false) $args['tag_id'] = $atts['tags'];
112
 
113
    /* Limit number of posts? */
114
    $args['posts_per_page'] = ($atts['number'] !== false) ? $atts['number'] : '-1';
115
 
116
    /* Query */
117
    $pages = new WP_query($args);
118
 
119
    /* Build result */
120
    if ( $pages->have_posts() ) :
121
 
122
         while ($pages->have_posts()) : $pages->the_post();
123
 
124
            /* By default your WP time format is used */
125
            $date = ($atts['format'] !== false) ? get_the_date($format = $atts['format']) : get_the_date();
126
 
127
            /* If displaying excerpt */
128
            if ($atts['description'] !== false) $excerpt = trim(str_replace($atts['remove'], '', get_the_excerpt()));
129
 
130
            /* Trim excerpt if required */
131
            if ( ($atts['words'] !== false) && ($atts['description']) ) $excerpt = wp_trim_words($excerpt, $num_words = $atts['words'], $more = null);
132
 
133
            /* The current Post Status */
134
            $poststatus = $pages->post->post_status;
135
 
136
            /* Don't link the current page */
137
            if (get_the_ID() == $the_current_page) {
138
              $output .= '
139
<li><span style="' . $atts['currentpagestyle'] . '">' . get_the_title() . '</span> — <span style="' . $atts['datestyle'] . '">' . $date . '</span>';
140
             } elseif ($poststatus == 'future') {
141
              $output .= '
142
<li><span style="' . $atts['headingstyle'] . '">' . get_the_title() . '</span> — <span style="' . $atts['datestyle'] . '">' . ($image = ($atts['image'] != '') ? '<img src="' . $atts['image'] . '" style="vertical-align: ' . $atts['align'] . 'px">' : $atts['clock']) . ' Scheduled: ' . $date . '</span>';
143
             } elseif ( (get_the_ID() != $the_current_page) && ($poststatus == 'publish') ) {
144
              $output .= '
145
<li><a href="' . get_permalink() . '" title="' . get_the_title() . '"><span style="' . $atts['headingstyle'] . '">' . get_the_title() . '</span></a> — <span style="' . $atts['datestyle'] . '">' . $date . '</span>';
146
             } else {
147
              $output .= '
148
<li><span style="' . $atts['headingstyle'] . '">' . get_the_title() . '</span> — <span style="' . $atts['datestyle'] . '">' . $date . '</span>';
149
            }
150
 
151
            /* Display excerpt if description required */
152
            if ($atts['description'] !== false) $output .= '<span style="' . $atts['textstyle'] . '">' . $excerpt  . '</span>';
153
            $output .= '</li>
154
 
155
';
156
 
157
        endwhile;
158
        $output = ($atts['numbered'] !== false) ? '
159
<ol>' . $output . '</ol>
160
 
161
' : '
162
<ul>' . $output . '</ul>
163
 
164
';
165
 
166
        /* Reset query */
167
        wp_reset_postdata();
168
 
169
    else :
170
 
171
        $output = '
172
<ul>
173
<li>No additional published articles in this series.</li>
174
</ul>
175
 
176
';
177
 
178
    endif;
179
 
180
   /* Set transient data */
181
   set_transient($transient, $output, $atts['cache']);
182
   return $output;
183
  }
184
}
185
add_shortcode('series', 'beliefmedia_series_posts');

If you require shortcode to work in a sidebar widget, you'll have to enable the functionality with a filter. If you're using our custom functions plugin, you'll have that feature enabled by default.

Shortcode Attributes

While there are a quite a few attributes, very few are required other than tags.

tags

The only required attribute is tags. While a comma-delimited list of tags is permitted, it's best-practice to only use a specific tags that will tie your content together.

status

By default the posts returned will have a status of publish. To include future posts (to give readers an indication of the rest of the scheduled series), use status="publish,future".

image

If the image value is empty, we'll use the HTML entity to render a clock (⏲).

align

The align attribute is used to position the image defined above. Use it if the image doesn't center correctly.

description

To render an excerpt under each post, use description="1".

format

After the title we'll print the date. If you want to use anything other than the default WP formatting (defined by you in your control panel), format the date with PHP's date() formatting.

remove

If you're required to remove leading text from the description excerpt, use remove="the text".

words

The excerpt is truncated to 15 words by default. Alter it with words="25".

number

In almost all circumstances you will return the series in a numbered list. To use an unordered list, use number="1".

headingstyle

The headingstyle is the default style applied to your post title. Defaults to font-weight: bold;.

datestyle

The datestyle is the default style applied to your post date. Defaults to font-size: 0.9em;.

textstyle

The textstyle is the default style applied to your post description (excerpt). Defaults to font-size: 0.9em;.

currentpagestyle

The currentpagestyle is the default style applied to the current page title. Defaults to text-decoration: none; font-weight: normal;.

cache

To avoid repeated queries we'll cache the results for 2 hours by default. If you don't plan on regular updates to your series, increase this value.

Considerations

  • Using a textbox or some other means of formatting you can jazz up the result a little.

  • Our blind shortcode will hide the series until clicked. It won't result in the same page-view conversions, but it will clear up the clutter.
  • While the shortcode can be used to return any number and type of post, this isn't the intended use. Instead, we've built purpose shortcodes to reduce the complexity.

Download


Title: Create a Series Reading List (WP Plugin)
Description: Create a Series Reading List with WordPress Shortcode. Renders a WP series of posts based on tag.
  Download • Version 0.2, 2.6K, zip, Category: WordPress Plugins (General)
WordPress Shortcodes, (1.9K)    

Download our 650-page guide on Finance Marketing. We'll show you exactly how we generate Billions in volume for our clients.

  AUS Eastern Standard Time (Virginia)

  Want to have a chat?
 

Like this article?

Share on facebook
Share on Facebook
Share on twitter
Share on Twitter
Share on linkedin
Share on Linkdin
Share on pinterest
Share on Pinterest

Leave a comment