Parameters for yarpp_related() function

Hi @flofiwp,

1. I vaguely remember there used to be a list hosted elsewhere but it disappeared. So we’re looking through the code and creating some documentation for it.

2. You have 'title' => 2 which is the same as “Consider with extra weight” for titles. However, titles normally weigh in disproportionately less than the body or taxonomies because of how the MySQL full-text comparisons work. Eg if you set the match threshold to 1, and are only considering post titles, and two posts have the exact same post title, their relatedness score will probably be less than 1 (eg maybe 0.2) unless their titles are very long. So you might want to try putting even more weight on titles, like 4 or 5.

Here’s what we have for documentation so far (still in progress). Let me know if you still have questions with it:

——————————-

YARPP allows the advanced user with knowledge of PHP to customize the display of related posts using a custom templating mechanism.
Use the functions in includes/related_functions.php, notably:

* yarpp_related, which gets the HTML for the related posts and displays it
* yarpp_related_exist which checks any related content exists, or
* yarpp_get_related which returns the list of related posts (WP_Post objects)

Each of these functions will default to using the settings set on the YARPP admin page, but they can be overridden by using the first argument, $args. The following array keys can be passed in:

* limit int indicating how many related items to return. Eg 10 will return at most 10 related posts/pages/products etc.
* threshold float indicating the minimum level of “relatedness” in order for a post to be considered related. Eg 4 is reasonable if considered post bodies
* show_pass_post boolean indicating whether to include password-protected posts. Eg true will include password-protected posts.
* past_only boolean indicating whether to only include posts published before the reference post. Eg true means to only include posts published before the post for which we’re finding related content.
* weight array with keys title or body, (whose value is an int), or tax whose value is an array whose keys are taxonomy names (eg category or tag) and their values are ints. Eg array('title' => 2, 'body' => 1, 'tax' => array('category' => 1, 'taxonomy' => 2)). The int values are multipliers, indicating how heavily to weigh each criteria. 1 is normal weight, 2 is extra weight.
* exclude string|array list of term_taxonomy_ids. Any posts using any of those terms will never be included in related results. Eg "1,2,3" andarray(1,2,3)` both indicating that any posts using terms with term_taxonomy_id 1, 2 or 3 (regardless of whether they are categories, tags, or any custom taxonomy) will be excluded from YARPP’s related results.
* require_tax array whose keys are taxonomies (eg “category” or “tag”) and whose values are the number required to be considered related. eg array('category' => 2) means, in order for another post to be considered related, it must share 2 categories in common with the reference post
* recent string of [SQL interval](https://www.mysqltutorial.org/mysql-interval/). Only posts within that time interval will be considered. Eg "1 WEEK" or "2 DAYS"
* order string indicating a column on wp_posts to order by, then a comma, and whether to order in ascending (“ASC”) or descending (“DESC”). Eg post_title,ASC indicating to order by the post’s title, alphabetically (A to Z).
* post_type string|array a string of a single post type, or an array of multiple post types to consider. Eg "page", or array("post", "page", "wc_product")

yarpp_related, also uses the following:

* domain string suggesting who called this. Mostly for internal use.
* template string which theme/custom template to use. Built-in ones include “list”, “thumbnails”, or the name of a file in your active theme starting with yarpp-template-. Eg yarpp-template-videos.php.
* promote_yarpp boolean indicating whether to add “Powered by Yet Another Related Posts Plugin” below related posts.

Each function also accepts a $reference_ID, the ID of the post for which you want related posts. Defaults to using the $current_post.

Eg
Show related posts, using all the settings set in the YARPP settings page:

<?php  yarpp_related(); ?>

Show at most 4 related WooCommerce products based on their title and especially on their categories. Use the custom template
yarpp-related-wc-products.php which you added to your active theme.

<?php
yarpp_related(
    array(
        'limit' => 4,
        'weight' => array(
            'title' => 1,
            'tax' => array(
                'category' => 2
            )
        ),
        'post_type' => 'wc_product',
        'template' => 'yarpp-related-wc-products.php'
    )
);
?>

Check for posts related to post with ID 123, and loop through them in order to do some more custom logic.

$related_posts = yarpp_get_related(array(), 123);
if($related_posts){
    echo 'No related posts';
} else {
    foreach($related_posts as $post){
        // $post is a WP_Post object.
        echo $post->post_title;
    }
}