TPG Get Posts Documentation

TPG Get Posts Usage

 

Overview

To use it, just put the following into the HTML of any page or post, use as many times as you like on the same page:

WARNING: If you copy/paste the commands, the function may not work. Often the hidden <code> and <pre> are copied into the page and only show in the html edit view of the WP editor. If this happens, type the entire command in to avoid introducing hidden characters.

[tpg_get_posts]

this is equivalent to:

[tpg_get_posts fields="title ,byline,content,metadata" numberposts=5
field_classes="post_title=tpg-title-class,post_content=tpg-content-class,
post_metadata=tpg-metadata-class, post_byline=tpg-byline-class" ]

This default usage will return the last 5 posts in reverse chronological order. It will display the post similarly to a standard post, honoring the more tag to produce a teaser. Meta data showing post date, author, modified date, comments, categories and tags is also displayed.

If the post was created with a more tag inserted, the teaser is shown with a link to "read more". See the option show entire if the entire post is to be shown. The excerpt is can be shown with the show_excerpt option.

A common usage is to show post on a page that have a common tag(s):

[tpg_get_posts tag="tag1, tag2,tag3"]

or to show specific posts on the home page:

[tpg_get_posts cat="homepage" numberposts=2]

To Do:

  1. add template tag...until then to incorporate TPG Get Posts into a template try using<?php echo do_shortcode('[tpg_get_posts]'); ?>

As of version 3.6, all functions are available in the free pluging. The premium version is no longer needed. But please consider making a donation.

  • magazine layout option which displays the post header and text next to the post thumbnail
  • the short code can be added to a text widget
  • extended cat__and, cat__not_in and cat__in and other taxonmy
  • extensive formatting of the by line and meta-data line
  • allow pagination
  • sticky post support
  • Options

    Based on the get_posts template tag, all of the possible parameters associated with this plugin are documented in the WP_Query class to which fetches posts. See the parameters section of the WP_Query documentation for a list of parameters that this function accepts.

    Note that if the parameter expects an array, then it must be handled explicitly in the parameter interface. If that is not listed here, then it is not accepted.

    Selection parameters are:

    tag
    This allows for the selection of posts by tag (slug).
    tag_id
    This allows for the selection of posts by tag id.
    author__in
    This allows for the selection by authors by id. With the premimun extension, you may select multiple authors by entering author__in="12,34,6".
    author__not_in
    This allows for the exclusion of authors by id. With the premimun extension, you may select multiple authors by entering author__not_in="12,34,6".
    cat
    A comma separated list of cateory names,slugs or ids.
    These are OR logic comparisons. Examples: cat='4', cat='5,3,4', cat='news,events,5' cat='news'. The category name is the name and not the slug. The coversion routine will look for id, slug and then category. To accomodate complex taxonomonies and where a category name is repeated as a sub category use either slug or id. Slugs and id''s are unique where a category name can be repeated.
    cat_link
    Setting this option to cat_link="false" will suppress the wrapping of the categories with the hyperlink tag and the category will not be a link. Default is "true".
    numberposts
    Specify the maximum number of posts to select. The default is 5.
    offset
    Specify the number of posts to skip. This is a standard option to WP_Query. If offset=3 is entered, the post will start showing at the 4 post. The default is 0, show all.
    posts_per_page
    Specify the number of posts to show on page and enable pagination. The numberposts option is ignored when this is specified. See the page_next_text and page_prev_text to set the text. If paging on front page, see fp_pagination option.
    fp_pagination
    This option is used in conjunction with the post_per_page option. If the pagination is on a static front page, set fp_pagination='true'.
    post_parent__in
    This allows for the selection of posts by parent id. With the premimun extension, you may select multiple parent ids by entering post_parent__in="12,34,6".
    post_parent__not_in
    This allows for the exclusion of posts by parent id. With the premimun extension, you may exclude multiple parent ids by entering post_parent__not_in="12,34,6".
    post__in
    This allows for the selection of posts by id. With the premimun extension, you may select multiple ids by entering post__in="12,34,6".
    post__not_in
    This allows for the exclusion of posts by id. With the premimun extension, you may exclude multiple ids by entering post__not_in="12,34,6".
    post_type
    This allows for the selection custom post types. With the premimun extension, you may select multiple posts types by entering post_type="CustTyp1,CustTyp2". The post type can be found by editing a custom post and checking the permalink which is below the post title. The custom post type immediately follows the domain name.
    post_status
    This allows for the selection by post status. With the premimun extension, you may select multiple posts statuses by entering post_status="published,draft".
    ignore_sticky_posts
    Set to false, ignore_sticky_posts='false', to show sticky posts in selection. By default the sticky posts only show on the home page. By setting the option, the plugin will show sticky posts on any page. The sticky posts are added to the beginning of the post list. If you have requested 4 posts and you have 2 sticky, then 6 posts will be shown on the first page.
    category__and
    A comma separated list of either categories or category_names may be used in this paramter. The values passed here will replace any value in the cat_name or cat tag. Posts must have be in all the categories (AND logic).
    category__in
    A comma separated list of either categories or category_names may be used in this paramter. The values passed here will replace any value in the cat_name or cat tag. Post may be in any of the categories (OR logic) and child posts are not pulled.
    category__not_in
    A comma separated list of either categories or category_names may be used in this paramter. The values passed here will replace any value in the cat_name or cat tag. Excludes posts in the listed categories.
    tag__and
    A comma separated list of tag_ids may be used in this paramter. Posts must have be in all the tag_ids (AND logic).
    tag__in
    A comma separated list of tag_ids may be used in this paramter. Posts may be in any of the tag_ids (OR logic).
    'tag__not_in
    A comma separated list of tag_ids may be used in this paramter. Excludes posts with the listed tag_ids.
    tag_slug__and
    A comma separated list of slugs may be used in this paramter. Posts must have be in all the slugs (AND logic).
    tag_slug__in
    A comma separated list of slugs may be used in this paramter. Posts may be in any of the slugs (OR logic).
    query_by_date
    Boolean value: true activates this option. This allows for the selection of post for the last x (a number) periods (day, month, year). It has two sub-commands: qbd_num and qbd_period. Example: query_by_date="true" qbd_num"3" qbd_period="month" This will select the posts enter in the previous 3 months.

    At this time, the following two commands have had limited testing.

    tax_query
    Used to pass the custom taxonomy selection to the plugin. Because the tax_query accepts nested arrays, the syntax is more complex than other parms and values are passed in json format. An example using json format:

    tax_query='{"relation":"AND","0":{"taxonomy":"movie_genre","field":"slug","terms":("action","comedy")},"1":{"taxonomy":"actor","field":"id","terms":(103,115,206),"operator":"NOT IN"}}'

    **Note: that json requires the strings to be enclosed with double quotes, so single quotes are required to wrap the tag value. Also json uses [] to define arrays without keys, but that conflicts with the shortcode syntax. To work around this, () are substitued in the json string and converted before decoding to an array.
    meta_query
    Because the meta_query accepts nested arrays, the syntax is more complex than other parms and values are passed in json format. An example using json format:

    meta_query='({"key":"color","value":"blue","compare":"NOT LIKE"},{"key":"price","value":(20,100),"type":"numeric","compare":"BETWEEN"})'

    **Note: that json requires the strings to be enclosed with double quotes, so single quotes are required to wrap the tag value. Also json uses [] to define arrays without keys, but that conflicts with the shortcode syntax. To work around this, () are substitued in the json string and converted before decoding to an array.

    Layout/format control parameters:

    fields
    This is a comma separated list of fields to be displayed. The default is "title, byline, content, metadata". If only a list of titles is desired, remove the othe parms from the list and no content will be returned, ie fields="title".
    field_classes
    This is a special list which assigns a class to a post field. It is formatted in a key=value sequence separated by a comma. The key defines a section of the post while the value is the name of a class to which will be provided via a tag wrapped around the field. The default classes are listed below. The class can be assigned any value and the css set up in a user defined style sheet. The key fields cannot be changed.

    The following is a list of the default field classes which can be overridden:

    • post_title=tpg-title-class
    • post_content=tpg-content-class
    • post_metadata=tpg-metadata-class
    • post_byline=tpg-byline-class
    • post_thumbnail=tpg-thumbnail-class
    • thumbnail_align=alignleft
    • post_excerpt=tpg-excerpt-class
    • mag_content=tpg-mag-class
    • fi_content=tpg-fi-class
    • ul_class=tpg-ul-class
    • pagination=tpg-pagination-class
    • page-next=tpg-next
    • page-prev=tpg-prev
    • more_link=more-link
    fi_layout
    This option fi_layout="true" in conjunction with the thumbnail_size="medium" option display the post in a "featured image" format where the featured image is placed above the title. The fields option can control what text to display.
    The thumbnail_size is required when displaying the thumbnail/featured image.
    mag_layout
    This option mag_layout="true" in conjunction with the thumbnail_size="thumbnail" option places the thumbnail at the beginning of the post items so it can float left and have the title and content beside the image. The standard "post layout" puts the title above the image and only the content wraps around the the image.
    The thumbnail_size is required when displaying the thumbnail/featured image.
    more_link_text
    This option changes the text to display when the more tag is used to produce a teaser. Enter as more_link_text="My Custom Text". Default is "(read more...)".
    page_next
    The option page_next="true" will show just the Previous and Next link instead of the pagination index. The default is false.
    page_prev_text
    Set the text for the previous link. Default is "« Previous".
    page_next_text
    Set the text for the next link. Defautl is "Next »".
    shorten_title
    This option shorten_title="c15" or shorten_title="w15" specifies that the title will be shortened to 15 characters. The "c" indicates to cut at the character while the "w" indicates that only whole words in the first 15 characters are included.
    shorten_content
    Using the more tag is generally a better option, but is is provided for consistency. This option shorten_content="c150" or shorten_content="w150" specifies that the content will be shortened to 150 characters, excluding the "read more..." text. The "c" indicates to cut at the character while the "w" indicates that only whole words in the first 150 characters are included. The "read more" tag is processed first, then this process is applied, so a read more tag can cause the text to be shorter than the specified length if placed in the post before the first x characters.
    Also note that this command does not check for embedded tags. It trims the content when the limit is reached and is not aware of html tags. Thus tags can be broken. It should only be be used with content that is very controlled. Using the read-more tag is safer.
    show_entire
    This option show_entire="true" will show the entire post, not just the teaser.It ignores the more tag in the post content. Default is "false".
    show_excerpt
    This option show_excerpt="true" will use the custom excerpt, if it exists, instead of the post content. It will use the entire excerpt entry. Default is "false".
    tag_link
    Setting this option to tag_link="false" will suppress the wrapping of the tags with the hyperlink tag and the tag will not be a link. Default is "true".
    text_ellipsis
    This parameter allows you to set the ellipsis displayed after shortened text. it defaults to text_ellipsis=' ...' but can be set to anything or nothing text_ellipsis=''.
    thumbnail_size
    Enter "none", thumbnail", "medium", "large" or"full" as the option value and if the thumbnail has been entered, it is used. Example thumbnail_size="medium". Default is "thumbnail". Your theme may provide additional options for thumbnail sizes.
    thumbnail_only
    This option thumbnail_only="true" will only show the thumbnail as a link to the post page. Use in conjunction with the thumbnail_size to set the size of the image. Default is "false"
    thumbnail_link
    This option thumbnail_link="true" is the default and will wrap a thumbnail with the link to the post. Setting to false will remove the link assigned to the image and selecting on the image will do nothing.
    thumbnail_title
    For this option thumbnail_title="false" is the default. To have a text attritue set for the thumbnail enter "post" or "image". The "post" value will pull the post title as the image text attribute and "image" will pull the image title for the value of the text attribute.
    title_tag
    This parameter controls the formatting of the title line. The default is to make post titles h2, which is consistent with the regular post markup. title_tag="p" will apply the paragraph markup to the title instead of the h2 markup. Note: do not include the <>.
    title_link
    Setting this option to title_link="false" will suppress the wrapping of the title with the hyperlink tag and the title will not be a link. Default is "true".
    ul-class
    This is the class assigned to the bullet list. When this class is provided, the output is returned as an unordered list.

    To exclude posts, see examples.

    Deprecated - use filters

    cf
    Invoke the user Custom Functions by passing the codes for each exit to be invoked, ie cf='ppre,ppst,pre,pst,t,b,c,m'. The model function php file is provided in the /ext files folder and instructions are in the comments. ppre => before the invoking of the plugin ppst => upon completion of plugin, just before returning results pre => before each post pst => after each post t,b,c,m => after title,byline,content,metadata -- this allows final editing
    cfp
    Custom functions parameters. This is an optional string that is passed to the custom functions routine. It must be parsed by the custom function and is defined by the user.

    Styling

    To over-ride the default styling, create a css file in your theme root folder named user-get-posts-style.css. When the plugin is loaded, the standard style sheet is loaded and then the user defined style sheet is loaded, if it exists. Any tags in the user style-sheet will override the standard style.

    By saving your custom user defined style sheet in the theme folder it will not be deleted with an upgrade to the plugin. This is a change from version 1.x

    There are two ways to alter the styling:

    1. In the user stylesheet, redefine the styles which are listed below. The simplest approach is to copy the styles from tpg_get_posts-style.css and modify them as needed.

      tpg-title-class
      class of the post title division
      tpg-byline-class
      class of the post byline
      tpg-content-class
      class for the body of the post
      tpg-metadata-class
      class for the metadata
      tpg-excerpt-class
      class for the excerpt
      tpg-thumbnail-class
      class for the thumbnail division

    2. If you need to pass different formatting to different pages, then the short-code must include the list of new classes. The list must include all the default parameters, even if not altered:

      The default classes are post_title=tpg-title-class, post_content=tpg-content-class, post_metadata=tpg-metadata-class, post_byline=tpg-byline-class as shown in the following short-code:

      [tpg_get_posts show_entire="false" fields="title, content, metadata" numberposts=5
      field_classes="post_title=tpg-title-class, post_content=tpg-content-class,
       post_metadata=tpg-metadata-class,post_byline=tpg-byline-class"  ]

      Premium Formatting Control Template
      The Premium plugin allows for the formatting of the by line and the meta line. For example, you can change the byline from showing the default of author, post date to just author or author, last maint date, last maint time.

      Within each line, there are several post tags which can be displayed and each tag can be formatted.
      Format Line Parms
      The format line is a comma separated string with the first value being the separator for the formatted string and then a list of the tags or tokens. The general format is: sep,meta_tag,meta_tag....
      Valid tags:
    • auth - author name
    • cat - list of categories assigned to post
    • cmt - comment, with format control for no, 1 or many comments
    • dp - date posted
    • dm - date of last maintenance
    • tag - list of tags assigned to post
    • tm - time of last maintenance
    • tp - time of posting
    • byline_fmt
      default byline_fmt=" ,auth,dp"
      metaline_fmt
      default metaline_fmt="  |  ,cmt,cat,tag"

      The following format options allow customization of the individual fields in the byline or metaline.

      Note: if you wish to use a comma in the the formatting, use the code &#44; The parsing routine uses commas to parse the format options, so the html code must be used to circumvent the parser.

      auth_fmt
      default: auth_fmt=",By ," (separator,b4 text,after text)
      cat_fmt
      default: cat_fmt="&#44; ,Filed under: ," (separator,b4 text,after text)
      cmt_fmt
      default: cmt_fmt=" No Comments », 1 Comment », Comments »" (nocmt,1-cmt, multi-cmt)
      dp_fmt
      default: dp_fmt="F j&#44; Y, on ," (date format,b4 text,after text)
      dm_fmt
      default: dm_fmt="F j&#44; Y, on: ," (date format,b4 text,after text)
      tag_fmt
      default: tag_fmt="&#44; ,Tags: ," (separator,b4 text,after text)
      tm_fmt
      default: tm_fmt="H:m:s, ," (time format,b4 text,after text)
      tp_fmt
      default: tp_fmt="H:m:s, ," (time format,b4 text,after text)

    Filters:

    The filter process allows for the filters to be implemented in 2 ways:

    1. Globally as a standard filter
    2. Individual call in tpg_get_posts

    The global filter is given a priority value of 10 and the call through the short-code is given a priority value of 15. This allows the short-code call to override the global call, it that it is called after the global call.

    Example code

    Create a custom function. This can be placed in the theme functions file or it can be put in a file named
    "user-get-posts-custom-functions" which is placed in the root of the theme.

    function my_custom_title_filter( $title, $post) {
            $title = "Custom Title Filter Works";
            return $title;
        }

    To set the function to process on all titles (global title filter) use the following code and add below the function definition:
    'add_filter( "tgp_filter_title", "my_custom_title_filter", 10, 2 );

    To run the filter for a specific call of tpg_get_posts add the filter parameter to the short-code:
    [tpg_get_posts filter_title="my_custom_title_filter"]>

    The query filter only passes one argument, the query arguments array:

    function my_custom_filter_query( $args) {
             *** set the $args array ***
            return $args;
        }
    [tpg_get_posts filter_title="my_custom_filter_query"]>

    The available filters are:
    (replace <function_name> with your custom function name)

      filter_query
      filter_query="<function_name>" - this function only accepts one argument, the query parameters array. This filter allows the wp_query parameters to be modified before the query is run.
      filter_title
      filter_title="<function_name>"
      filter_byline
      filter_byline="<function_name>"
      filter_content
      filter_content="<function_name>"
      filter_metadata
      filter_metadata="<function_name>"
      filter_thumbnail
      filter_thumbnail="<function_name>"

    Examples:

    Shows 5 posts with the tag "tag1" or "tag2" ordered by title. Display the post title and content teaser.

    [tpg_get_posts tag="tag1,tag2" numberposts=5 orderby="title"]

    Shows 2 posts with the category name of "Events" or "News" ordered by title. Display the post title and the entire content.

    [tpg_get_posts cat="Events,News" numberposts=2 orderby="title" show_entire="true"]

    Shows a bullet list of post titles. The title will be wrapped in a tag with a class of "tpg-ul-class". The title will provide a link to the post. The title can be formatted with a css style .tpg-ul-class h2 {}.

    [tpg_get_posts tag="tag5" fields="title"  ul_class="tpg-ul-class"]

    To exclude a category within a selected category, you must use the category id for the selection. The minus sign in front of the cateory id tells the query to exlude a category. So this shortcode will select all the posts in category 15 and then eliminate all the post that are also in category 4.

    [tpg_get_posts cat="15,-4" ]

    The magazine layout is available in the premium version. The layout will float the thumbnail to the left and position the title and byline to the right. The fields parm controls which elements to show.

    [tpg_get_posts cat="25" fields="title, byline"  numberposts=1 mag_layout="true" thumbnail_size="thumbnail"]

    Pagination. Show 5 posts per page with the pagination index at the end of the posts.

    [tpg_get_posts cat="cat1" posts_per_page=5
    		 field_classes="pagination=tpg-pagination-class my-theme-pagination-class"]

    If paging on a static front page use:

    [tpg_get_posts cat="cat1" posts_per_page=5
    		 field_classes="pagination=tpg-pagination-class
    		 my-theme-pagination-class" fp_pagination="true"]

    Formats the byline with author, date and time and the date format is defined in the dm_fmt option to produce 'last changed on: Month day, YYYY'.

    [tpg_get_posts category__in="Events" byline_fmt"auth,dm,tm", dm_fmt="F j&#44; Y, last changed on: ,"]

    How to Use:

    If you wish to have a subset of posts appear on a specific page. The simplest approach is to specify a unique category and select it for the post you want to appear. You can have multiple categories for a post, so this will not alter your existing website structure.

    For instance, suppose you want to show 2 posts on your home page, but not everything you post, only those dealing with high profile events. The following steps should do this:

    1. Create a new category "homepage"
    2. For each post that is to appear on the home page, select the category "homepage"
    3. On your home page, enter the following shortcode where you want the posts inserted:
      [tpg_get_posts cat="homepage" numberposts=2]

    That should do it!

    Comments are closed.