UCF Post List Shortcode

Provides a shortcode for displaying lists of posts.

Description

This plugin provides a shortcode for displaying lists of posts. It is written to work out-of-the-box for non-programmers, but is also extensible and customizable for developers.

Support for Advanced Custom Fields relationship fields is also available; e.g. you can query against a list of posts by one or more related posts: [ucf-post-list meta_key="your_relationship_field" meta_value="related-post-slug-1,related-post-slug-2"]

Installation

Manual Installation

1. Upload the plugin files (unzipped) to the /wp-content/plugins directory, or install the plugin through the WordPress plugins screen directly.
2. Activate the plugin through the "Plugins" screen in WordPress
3. Configure plugin settings from the WordPress admin under "Settings > UCF Post List".

WP CLI Installation

1. $ wp plugin install --activate https://github.com/UCF/UCF-Post-List-Shortcode/archive/master.zip. See WP-CLI Docs for more command options.
2. Configure plugin settings from the WordPress admin under "Settings > UCF Post List".

Usage

[ucf-post-list] Generates a basic unordered list of posts, using default get_posts() arguments.

Generally speaking, the [ucf-post-list] shortcode accepts most arguments for get_posts() and WP Query. Exceptions are noted below.

Unique Arguments

layout The name of the layout to use to display the list of posts. Defaults to "default", an unstyled, unordered list of posts.

list_title Heading text to display above the list of posts. No heading is displayed by default.

show_image True/false; whether or not an image for the post should be displayed. Only applicable on layouts that support images.

'show_excerpt' True/false; whether or not to display an excerpt of the post. If no excerpt exists, post content will be displayed instead. Defaults to false.

'excerpt_length' Any positive int; Max number of words to display for the excerpt. If set to 0, no limit is used. Defaults to 0. WordPress default excerpt size is 55 words.

posts_per_row The number of posts to display per row within the chosen layout. Only applicable on layouts that support column-based post lists.

display_search True/false; whether or not a search field that searches the list of posts should be displayed. Defaults to "false".

search_placeholder The placeholder text to display in the search field (when display_search is enabled).

list_id A unique identifier to assign to the post list. Useful for creating specialized post lists with custom styling or functionality. Defaults to a randomized numeric string.

tax_relation A relationship between each tax_query generated by the shortcode's arguments. See the WP_Query taxonomy parameters documentation for usage.

tax_TAXSLUG One or more terms to filter by within the given taxonomy. Any registered taxonomy can be used. Serves as a substitute for the "terms" tax_query argument for the taxonomy TAXSLUG.

tax_TAXSLUG__field Specify the field type used in tax_TAXSLUG. Serves as a substitute for the "field" tax_query argument for the taxonomy TAXSLUG.

tax_TAXSLUG__include_children True/False. Whether or not to include children for hierarchical taxonomies. Serves as a substitute for the "include_children" tax_query argument for the taxonomy TAXSLUG.

tax_TAXSLUG__operator Operator to test. Serves as a substitute for the "operator" tax_query argument for the taxonomy TAXSLUG.

meta_serialized_relation Custom argument for ACF relationship fields which defines the relation between reverse lookup posts. Serves as a substitute for the "relation" meta_query argument.

Unsupported Arguments

Caching parameters, "fields", and "suppress_filters" arguments are not supported in this shortcode.

In addition, "date_query" and "meta_query" are not yet supported.

Changelog

2.1.2

Enhancements:

• Added composer file.

2.1.1

Enhancements:

• Added adjustments to "card" layout styles:
  • Updated link underline styles for compatibility with Athena v1.1.1+
  • Updated wrapper link around card content to span the full height of its parent, eliminating unclickable dead space at the bottom of cards with little content
  • Updated .ucf-post-list-card-text to be wrapped in a <div> instead of <p> as a workaround for accessibility scans flagging that content for overuse of italics.
• Upgraded packages

2.1.0

Enhancements:

• Added new shortcode attributes, show_excerpt and excerpt_length, for toggling display of post excerpts and their lengths within supported layouts (currently, this includes the "card" layout.) Thanks @mikesetzer!
• Bumped required WordPress version and "tested to" version.
• Upgraded packages and required version of node for development.

2.0.8

Bug Fixes:

• Readds the default markup on layout filters to ensure backwards compatibility.

2.0.7

Enhancements

• Added late enqueuing of JS assets, and moved all scripts to the document footer. ucf_post_list_search_script() has been modified to return empty contents and add inline initialization of typeaheads via wp_add_inline_script() instead of returning a <script> tag directly.
• Renamed Typeahead and Handlebars script handles for consistency with other plugins
• Added constants for static CSS/JS URL paths
• Removed redundant has_filter() checks when displaying post list layouts
• Added absolute dirs for required files in main plugin file
• Removed ID attr on .ucf-post-search-form wrapper elem, as it's not necessary
• Upgraded packages
• Added plugin version cache-busting to plugin CSS and JS (excluding CDN'd assets)

Bug fixes

• Updated UCF_Post_List_Config::format_option_num_or_null() to actually cast non-null values to int instead of trying to force addition on a potentially non-numeric value

2.0.6

Bug fix

• Updated version and added Github Plugin URI

2.0.5

Bug fix Updated random_int to rand for backwards compatibility

2.0.4

Enhancements

• Adds the option to apply filters to the shortcode attributes that are available per layout.

2.0.3

Enhancements

• Added new $size attr to UCF_Post_List_Common::get_image_or_fallback, which allows you to specify the image size to retrieve. This defaults to large to accommodate for sites that depend on the function previously (incorrectly) returning full-sized images, while still avoiding returning huge images at least.
• Added UCF_Post_List_Common::get_image_srcset, which returns a srcset attribute to use for post list layouts that support thumbnails. The srcset generated will still depend on the uploaded image size not being enormous, but should still help reduce requested filesizes overall, particularly for mobile devices.
• Updated the card layout to use a srcset attribute.

Other

• Fixed typo for tax_TAXSLUG__field param in readme

2.0.2

Bug fixes

• Updated formatting callback for post_parent param from a boolean to integer.

2.0.1

Enhancements

• Added 'count' layout, which displays the total number of requested posts

Bug fixes

• Fixed a formatting issue that prevented multiple taxonomy term values from being passed to the tax_TAXSLUG attribute

2.0.0

Enhancements

• Updated layout hooks to use filters instead of actions for greater flexibility. Layout hooks now have default values. Note that these changes are incompatible with layout hooks available in v1.0.0 of the plugin.

1.0.0

• Initial release

Upgrade Notice

n/a

Installation Requirements

Prior to v2.0.7, jQuery was required in the document head. From v2.0.7 onward, jQuery is still required, but does not specifically have to be in the document head.

Development

Note that compiled, minified css and js files are included within the repo. Changes to these files should be tracked via git (so that users installing the plugin using traditional installation methods will have a working plugin out-of-the-box.)

Enabling debug mode in your wp-config.php file is recommended during development to help catch warnings and bugs.

Requirements

• node v16+
• gulp-cli

Instructions

1. Clone the UCF-Post-List-Shortcode repo into your local development environment, within your WordPress installation's plugins/ directory: git clone https://github.com/UCF/UCF-Post-List-Shortcode.git

2. cd into the new UCF-Post-List-Shortcode directory, and run npm install to install required packages for development into node_modules/ within the repo

3. Optional: If you'd like to enable BrowserSync for local development, or make other changes to this project's default gulp configuration, copy gulp-config.template.json, make any desired changes, and save as gulp-config.json.

   To enable BrowserSync, set sync to true and assign syncTarget the base URL of a site on your local WordPress instance that will use this plugin, such as http://localhost/wordpress/my-site/. Your syncTarget value will vary depending on your local host setup.

   The full list of modifiable config values can be viewed in gulpfile.js (see config variable).

4. Run gulp default to process front-end assets.

5. If you haven't already done so, create a new WordPress site on your development environment to test this plugin against.

6. Activate this plugin on your development WordPress site.

7. Configure plugin settings from the WordPress admin under "UCF Post List".

8. Run gulp watch to continuously watch changes to scss and js files. If you enabled BrowserSync in gulp-config.json, it will also reload your browser when plugin files change.

Other Notes

• This plugin's README.md file is automatically generated. Please only make modifications to the README.txt file, and make sure the gulp readme command has been run before committing README changes. See the contributing guidelines for more information.

Contributing

Want to submit a bug report or feature request? Check out our contributing guidelines for more information. We'd love to hear from you!