UMS Post Picker - Web Technologies

This plugin is utilized to pull posts from a source site and display them within a target site using shortcodes, taxonomy criteria, and other options. This plugin is maintained by the UMS Web Development Team, except for specific templates which are maintained by the UMS Web Technologies Team. An ideal use of this tool would be to display news (or events, other custom post type) posts in other sites to avoid duplicating content across multiple sites.

Let’s take a USM example where news post images, titles, and dates from the source site are displayed inside a carousel in the target site. The post titles are liked to the full post of each:

Create the News Posts in the News Site

Make sure that you use consistent shape / aspect ratio for the feature image attached to each post in the source site. Consistency of title length is another factor that may affect a carousel presentation of the posts (due to limited space in carousel slides).

Create the Page in the Target Site

Create the page where you want to display the news posts (or excerpts).

Activate Plugins: Carousel Block + UMS Post Picker in the Target Site

Your Web Administrator may need to assist with enabling these plugins on your site.

Add the “Carousel Block” to the Page in its Desired Location on the Page

Using the Gutenberg inserter, add the “Carousel Slider” block to the page.

Use Shortcode Block to Create each Slide

Using the “+” (Add Slide) option to add the “Shortcode” block, as shown below:

The shortcode used in this example utilizes a custom USM template, sources the news posts from site_id 19, uses the “full” image size, pulls posts with a specific tag and uses the “limit” and “offset” options to show only one post per image, based on the first one it finds…:

[ums-post-picker site_id=19 limit=1 offset="0" template="usm_post_with_image" media_size="medium" taxonomy_terms="post_tag:zach" options="showDate:1"]

Shortcodes Details Explained

This plugin provides a shortcode for listing posts of all type and from any WordPress network sub-site.

The shortcode is ums-post-picker and It has the following parameters:

Parameter	Description
`site_id`	The sub-site ID to pull content from. Note that if you are using posts from a custom post type provided by a plugin, then the sub-site using this shortcode must have that plugin enabled, even if it is not being used. Default: none (The current sub-site ID where the shortcode is being used will be applied)
`template`	The template to use when displaying post content. Templates can be specific to custom post type or generic and applicable to all post types. See table below for a list of valid options (coming soon). Default: `default-template` (which falls back on `post_link_list`).
`post_type`	The type of WordPress post to search. You can use this to specify a custom post type. Default: `post` (Native WordPress Posts)
`limit`	Show, at most, this many posts. Default: `50`
`offset`	Skip this many posts and start after that. This is used for a form of pagination. Default: `0`
`order_by`	The post field to order posts by. See WordPress WP_Query developer documentation for a list of valid field names. Default: `date`
`order`	The sort order. Valid options are `ASC` and `DESC`. Default: `DESC`
`taxonomy_terms`	A list of taxonomies and terms to match. The format is: `taxonomy_terms="taxonomy_name:term_slug"` You can list more than 1 term by separating them with commas: `taxonomy_terms="taxonomy_name:term_slug_1,term_slug_2"` You can search across multiple taxonomies by separating them with semicolons: `taxonomy_terms="taxonomy_name1:term_slug_1,term_slug_2;taxonomy_name2:term_slug_3,term_slug_4"` Built-In Taxonomies: `category` – Post Categories `post_tag` – WordPress Tags, used by some other types as well Other post types (such as UMS Academic Programs and UMS Scholarships) have their own taxonomies that can be used with this shortcode as well. Consult their documentation or ask the Web Development Team for a list. Valid terms for each taxonomy are the slugs of each taxonomy option/term as defined within WordPress. Edit a term in WordPress to view the `slug` version of the name. Default: (none)
`taxonomy_logic`	Specifies the boolean logic when searching across multiple taxonomies. Values can be `AND` (default) or `OR`. Default: `AND` Note that the logic for terms within each taxonomy is always `IN` (which for our purposes means `OR`).
`feat_img`	Set to `true` to show only posts with a featured image, `false` for posts without a featured image, or `optional` for either. Default: `optional`
`meta_key`	Enter a meta key to query on.
`meta_value`	Enter the value for the meta key above.
`omit_past_posts`	Set to `true` to show only current posts. Default: `false`
`debug`	If set to 1 then extra debug information link will be shown along with the results. This is intended for developer use only. Default: `0`

Template Specific Parameters

The shortcode parameters listed below are provided for template use only, and their actual implementation is dependent upon the template being used. The documentation here is provided only as suggested use for template designers. The default value of these parameters is always null unless otherwise noted. It is up to the template designer to check for null and give them a default value if so desired.

Parameter	Description
`if_none`	The content to display when there are no matching programs.
`classes`	The CSS class name(s) to add to the wrapper element around the post list.
`post_delimiter`	HTML content to to insert between posts
`mode`	Can be used to designate a subtle change to output within the same template.
`media_size`	To be used as an argument for WordPress image link generator functions
`show_read_more`	Set to 1 or 0 to display or hide the “Read More” link
`options`	Arbitrary options list. Use this to extend your template with options that are not included in the list of supported shortcode parameters. If the option you would like is potentially applicable to other templates as well please make the case for its inclusion in the supported parameters list to the Web Development Team before falling back on this to avoid having to refactor your template code (and changing implemented shortcodes in content) later. The Post Picker plugin will parse this argument and place the results in `$parsedOptions`. As an example, it would convert `options="key:value;keyOnly;key2:value"` into a PHP array containing: `['key' => 'value', 'keyOnly' => true, 'key2' => 'value']`

Full Example:

This example shows all possible parameters. You do not need to provide a parameter if it isn’t applicable to your content or if the default value is acceptable. This example is split over multiple lines for the sake of readability but would be consolidated to a single line within WordPress. Lastly, because it tries to show every possible parameter, which is not a realistic application, it is unlikely to work as written. The writer of this documentation is well aware of the irony that exists in this short-code example.

[ ums-post-picker
    site_id="5"
    template="post_link_list"
    post_type="academic_programs"
    limit="5"
    offset="0"
    order_by="title"
    order="ASC"
    taxonomy_terms="ums_academic_programs_area_of_study:nursing,comp_sci;post_tag:pilotprogram"
    taxonomy_logic="AND"
    debug="0"
    if_none="Please check back later."
    classes="related_programs_list"
    post_delimiter="<hr>"
    mode="divs"
    media_size="full"
    show_read_more="1"
    options="no_excerpt;footer:Call 1 (858) 651-5050 for more information."
]

Current Templates

List as of 22-APR-2024.

Template Name	Maintainer	Description
Default Template	Web Development Team	The template used when none is provided. It simply calls upon `post_link_list` making that the effective default.
Accordion Excerpts	Web Development Team	This template outputs a list of posts in an accordion format, with the post title as the accordion header and the post excerpt, or substring of post content if excerpt does not exist, as the accordion body. `last_updated` can be added to the options field for the last modified date to be included in accordion body below content. `title_link` can be added to the options field to make the title displayed in accordion header link to the full post. Checking the Read More checkbox will include a read more link to full post in accordion body at end of content.`default_open` can be added to the options field to make all accordion sections open by default, or `default_open_first` to open just the first one in the set. Use `accordion_excerpts` in shortcode.
Post Link List	Web Development Team	Produces a simple list of post titles which are links to the post’s page. This is an unordered list by default. Use the `mode` parameter to specify `ul`, `ol`, or `divs` Use `post_link_list` in shortcode.
Post With Image	Web Technologies Team	The post thumbnail/featured image (if present), linked title, & content excerpt. This template is incomplete and produces ugly results. Revisions from Web Tech Web Designers welcome. Supported Parameters: – `media_size` – The size of the image. Default `thumbnail` – `show_read_more` – If set to `1` then a “Read More” link will be shown after the excerpt. Default: `0` Supported Options: – `footer` – Specify text to appear after the post excerpt. – `no_excerpt` – If present then the post excerpt will be omitted. Options Example: `options="no_excerpt;footer:Call 1 (858) 651-5050 for details."` Use `post_with_image` in shortcode.
Full Post	Web Technologies Team	This template is used for sharing blocks between sites, it does this by pulling the full post. Ideally, blocks in the source site will be maintained through the use of posts with tags. Use `full_post` in shortcode.
UMS Scholarships	Web Development Team	This is a proof of concept template for display all of the data associated with custom post types. It is still being developed and will be documented when/if it is complete. Use `ums_scholarships` in shortcode.
UMS Post Summary	Web Technologies Team	The post thumbnail/featured image (if present), linked title, & date. This template creates a card-style element for each post that it pulls. Created to be used in the WP Carousel for USM News Carousels. Note: Due to how Events Calendars stores and retrieves data on Additional Fields, the fields that display in this template must be pulled through the get_post_meta() function. As such, the user must specify the IDs for these fields when using the shortcode. The template is currently set to use the correct IDs if the user does not specify any, but this should ultimately be removed and only show the Additional Fields if the user specifies IDs for them. Supported Parameters: – `media_size` – The size of the image. Default `thumbnail` Supported Options: – `showDate` – Set to ‘1’ to show date, leave empty to hide date. – `footer` – Specify text to appear after the post excerpt. Options Example: `options="showDate:1;footer:Call 1 (858) 651-5050 for details."` Use `ums_post_summary` in shortcode.
UMS Eevent Summary	Web Technologies Team	The post thumbnail/featured image (if present), linked title, date, Campus / Online Event custom field. This template creates a card-style element for each post that it pulls. Created to be used in the WP Carousel for USM Events Carousels. Events posts should be created using The Events Calendar. Supported Parameters: – `media_size` – The size of the image. Default `thumbnail` – `omit_past_posts` – If `true`, events that have already ended will not display. Default `false` Supported Options: – `campusID` – ID for the ‘Campus’ additional field within Events Calendar. – `onlineID` – ID for the ‘Online Event’ additional field within Events calendar. Options Example: `options="campusID:6;onlineID:7"` Use `ums_event_summary` in shortcode.
UMS Event Summary List	Web Technologies Team	The post featured linked image (if present) is optional (simply omit media_size from the shortcode), linked title, event start date / schedule details. This template creates a list containing each post’s details that it pulls. Used to display event lists from any site. Events posts should be created using The Events Calendar and EC should be activated in the site where this feature is utilized. Supported Parameters: – `media_size` – The size of the image. – `omit_past_posts` – If `true`, events that have already ended will not display. Default `false` Supported Options: – similar to the options listed in `post_with_image`. Use `ums_event_summary_list` in shortcode.