Provides a shortcode for displaying lists of posts.
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"]
- Upload the plugin files (unzipped) to the
/wp-content/plugins
directory, or install the plugin through the WordPress plugins screen directly. - Activate the plugin through the "Plugins" screen in WordPress
- Configure plugin settings from the WordPress admin under "Settings > UCF Post List".
$ wp plugin install --activate https://github.com/UCF/UCF-Post-List-Shortcode/archive/master.zip
. See WP-CLI Docs for more command options.- Configure plugin settings from the WordPress admin under "Settings > UCF Post List".
[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.
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.
Caching parameters, "fields", and "suppress_filters" arguments are not supported in this shortcode.
In addition, "date_query" and "meta_query" are not yet supported.
Enhancements:
- Added composer file.
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
Enhancements:
- Added new shortcode attributes,
show_excerpt
andexcerpt_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.
Bug Fixes:
- Readds the default markup on layout filters to ensure backwards compatibility.
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 viawp_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 toint
instead of trying to force addition on a potentially non-numeric value
Bug fix
- Updated version and added Github Plugin URI
Bug fix Updated random_int to rand for backwards compatibility
Enhancements
- Adds the option to apply filters to the shortcode attributes that are available per layout.
Enhancements
- Added new
$size
attr toUCF_Post_List_Common::get_image_or_fallback
, which allows you to specify the image size to retrieve. This defaults tolarge
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
Bug fixes
- Updated formatting callback for
post_parent
param from a boolean to integer.
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
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.
- Initial release
n/a
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.
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.
- node v16+
- gulp-cli
-
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
-
cd
into the new UCF-Post-List-Shortcode directory, and runnpm install
to install required packages for development intonode_modules/
within the repo -
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 asgulp-config.json
.To enable BrowserSync, set
sync
totrue
and assignsyncTarget
the base URL of a site on your local WordPress instance that will use this plugin, such ashttp://localhost/wordpress/my-site/
. YoursyncTarget
value will vary depending on your local host setup.The full list of modifiable config values can be viewed in
gulpfile.js
(seeconfig
variable). -
Run
gulp default
to process front-end assets. -
If you haven't already done so, create a new WordPress site on your development environment to test this plugin against.
-
Activate this plugin on your development WordPress site.
-
Configure plugin settings from the WordPress admin under "UCF Post List".
-
Run
gulp watch
to continuously watch changes to scss and js files. If you enabled BrowserSync ingulp-config.json
, it will also reload your browser when plugin files change.
- 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.
Want to submit a bug report or feature request? Check out our contributing guidelines for more information. We'd love to hear from you!