README

Query and display posts in WordPress.

Installation

Install via composer:

composer require grottopress/wordpress-posts

Usage

<?php
declare (strict_types = 1);

use GrottoPress\WordPress\Posts;

// Instantiate Posts
$posts = new Posts([
    'image' => [
        'size' => 'some-size', //could be array (eg: array(150,150)) or string (eg: 'post-thubnail')
        'margin' => '0 10px 0 0',
    ],
    'excerpt' => [
        'length' => 30, // number of words. use -1 for all
        'after' => [
            'types' => ['category', 'post_tag']
        ]
    ],
    'title' => [
        'position' => 'top' // either 'top' or 'side' of image
        'tag' => 'h1', // 'h2' by default,
        'before' => [
            'types' => ['share_link', 'tweet_link'],
        ],
        'after' => [
            'types' => ['author_name', 'published_date', 'comments_link'],
        ]
    ],
    'wp_query' => [ // WP_Query args
        // See https://codex.wordpress.org/Class_Reference/WP_Query
    ]
]);

// Display posts
echo $posts->render();

You may use the styles defined in dist/css in your theme (or plugin):

\add_action('wp_enqueue_scripts', function () {
    $css = \is_rtl() ? 'posts-rtl.css' : 'posts.css';

    \wp_enqueue_style(
        'wordpress-posts',
        \get_stylesheet_directory_uri()."/vendor/grottopress/wordpress-posts/dist/css/$css"
    );
});

Arguments

Full list of arguments, with their defaults, are as follows:

$args = [
    'class' => 'small', // Wrapper HTML classes
    'tag' => 'div', // Wrapper HTML tag. Use 'ul' for list posts.
    'layout' => 'stack', // 'stack' or 'grid'
    'text_offset' => 0, // Distance from image side to text (title, excerpt)
    'related_to' => 0, // Post ID. Use this for related posts
    'image' => [
        'size' => '',
        'align' => '', // 'left', 'right' or 'none'
        'margin' => '',
        'link' => true,
    ],
    'excerpt' => [
        'length' => 0, // Number of words. Use -1 for full excerpt, -2 for full content
        'paginate' => 1, // If showing full content, whether or not to paginate.
        'more_text' => \esc_html__('read more'),
        'after' => [
            'types' => [], // Info to display after content/excerpt
            'separator' => '|',
            'before' => '<small class="entry-meta after-content">',
            'after' => '</small>',
        ],
    ],
    'title' => [
        'tag' => 'h2',
        'position' => '', // Relative to image: 'top' or 'side'
        'length' => -1, // Number of words. Use -1 for full length
        'link' => true,
        'before' => [
            'types' => [], // Info to display before title
            'separator' => '|',
            'before' => '<small class="entry-meta before-title">',
            'after' => '</small>',
        ],
        'after' => [
            'types' => [], // Info to display after title
            'separator' => '|',
            'before' => '<small class="entry-meta after-title">',
            'after' => '</small>',
        ],
    ],
    'pagination' => [
        'position' => [], // 'top' and/or 'bottom'
        'key' => '', // URL query key to use for pagination. Defaults to 'pag'.
        'mid_size' => null,
        'end_size' => null,
        'prev_text' => \esc_html__('&larr; Previous'),
        'next_text' => \esc_html__('Next &rarr;'),
    ],
    'wp_query' => [ // WP_Query args
        // See https://codex.wordpress.org/Class_Reference/WP_Query
    ]
]

Posts info

The following are possible values you may supply to $args['title']['before']['types'], $args['title']['after']['types'] and $args['excerpt']['after']['types']:

avatar__<size> eg: avatar__40
updated_ago, updated_ago__actual, updated_ago__difference
published_ago, published_ago__actual, published_ago__difference
author_name
comments_link
updated_date
updated_time
published_date
published_time
category_list or category
tag_list or post_tag
edit_link
delete_link
tweet_button
sharethis_button
share_link
tweet_link
pin_link
linkedin_link
buffer_link
digg_link
tumblr_link
reddit_link
blogger_link
pocket_link
skype_link
viber_link
whatsapp_link
telegram_link
vk_link
The name of a filter hook. A function should then be defined and added to that filter. Function args: string $output, int $post_id, string $separator.
A post meta key. This would display a single meta value for that key.
A taxonomy name. This would display a list of all terms of that taxonomy the post was assigned to.

Social media icons

If you would like to show icons for social links, you need to install font awesome v5.

Development

Run tests with composer run test.

Contributing

Fork it
Switch to the master branch: git checkout master
Create your feature branch: git checkout -b my-new-feature
Make your changes, updating changelog and documentation as appropriate.
Commit your changes: git commit
Push to the branch: git push origin my-new-feature
Submit a new Pull Request against the GrottoPress:master branch.

grottopress / wordpress-posts

Maintainers

Details