WordPress.org

Developing with YARPP

Custom post types

To make YARPP support your custom post type, the attribute yarpp_support must be set to true on the custom post type when it is registered. It will then be available on options on the YARPP settings page.

If you would like to programmatically control which post types are considered in an automatically-displayed related posts display, use the yarpp_map_post_types filter.

Custom displays

Developers can call YARPP's powerful relatedness algorithm from anywhere in their own code. Some examples and more details are in my slides from my WordCamp Birmingham talk.

yarpp_related(array(
    // Pool options: these determine the "pool" of entities which are considered
    'post_type' => array('post', 'page', ...),
    'show_pass_post' => false, // show password-protected posts
    'past_only' => false, // show only posts which were published before the reference post
    'exclude' => array(), // a list of term_taxonomy_ids. entities with any of these terms will be excluded from consideration.
    'recent' => false, // to limit to entries published recently, set to something like '15 day', '20 week', or '12 month'.

    // Relatedness options: these determine how "relatedness" is computed
    // Weights are used to construct the "match score" between candidates and the reference post
    'weight' => array(
        'body' => 1,
        'title' => 2, // larger weights mean this criteria will be weighted more heavily
        'tax' => array(
            'post_tag' => 1,
            ... // put any taxonomies you want to consider here with their weights
        )
    ),
    // Specify taxonomies and a number here to require that a certain number be shared:
    'require_tax' => array(
        'post_tag' => 1 // for example, this requires all results to have at least one 'post_tag' in common.
    ),
    // The threshold which must be met by the "match score"
    'threshold' => 5,

    // Display options:
    'template' => , // either the name of a file in your active theme or the boolean false to use the builtin template
    'limit' => 5, // maximum number of results
    'order' => 'score DESC'
),
$reference_ID, // second argument: (optional) the post ID. If not included, it will use the current post.
true); // third argument: (optional) true to echo the HTML block; false to return it

Options which are not specified will default to those specified in the YARPP settings page. Additionally, if you are using the builtin template rather than specifying a custom template file in template, the following arguments can be used to override the various parts of the builtin template: before_title, after_title, before_post, after_post, before_related, after_related, no_results, excerpt_length.

If you need to use related entries programmatically or to know whether they exist, you can use the functions yarpp_get_related($args, $reference_ID) and yarpp_related_exist($args, $reference_ID). yarpp_get_related returns an array of post objects, just like the WordPress function get_posts. yarpp_related_exist returns a boolean for whether any such related entries exist. For each function, $args takes the same arguments as those shown for yarpp_related above, except for the various display and template options.

Note that custom YARPP queries using the functions mentioned here are not cached in the built-in YARPP caching system. Thus, if you notice any performance hits, you may need to write your own code to cache the results.

Custom taxonomy support

Any taxonomy, including custom taxonomies, may be specified in the weight or require_tax arguments in a custom display as above. term_taxonomy_ids specified in the exclude argument may be of any taxonomy.

If you would like to choose custom taxonomies to choose in the YARPP settings UI, either to exclude certain terms or to consider them in the relatedness formula via the UI, the taxonomy must (a) have either the show_ui or yarpp_support attribute set to true and (b) must apply to either the post types post or page or both.

Localizations

YARPP is currently localized in the following languages:

• Egyptian Arabic (ar_EG) by Bishoy Antoun of cdmazika.com.
• Standard Arabic (ar) by led
• Belarussian (by_BY) by Fat Cow
• Bulgarian (bg_BG) by Flash Gallery
• Simplified Chinese (zh_CN) by Jor Wang of jorwang.com
• Traditional Chinese (Taiwan, zh_TW) by Pseric
• Croatian (hr) by GoCroatia.com
• Czech (cs_CZ) by Zdenek Hejl
• Dutch (nl_NL) by Sybrand van der Werf
• Estonian (est_EST) by JOURNAL
• Farsi/Persian (fa_IR) by Moshen Derakhshan
• French (fr_FR) by Lionel Chollet
• Georgian (ge_KA) by Kasia Ciszewski of Find My Hosting
• German (de_DE) by Michael Kalina of 3th.be and Nils Armgart of movie-blog.de.ms
• Cypriot Greek (el_CY) by Aristidis Tonikidis of akouseto.gr
• Greek (el_EL) by Aristidis Tonikidis of akouseto.gr
• Gujrati (gu_IN) by Vikas Arora
• Hebrew (he_IL) by Mickey Zelansky of simpleidea.us and Hadas Kotek
• Hindi (hi_IN) by Outshine Solutions
• Italian (it_IT) by Gianni Diurno of gidibao.net
• Irish (gb_IR) by Ray Gren
• Bahasa Indonesia (id_ID) by Hendry Lee of Kelayang
• Japanese (ja) by myself
• Kazakh (kk_KZ) by DachaDecor
• Korean (ko_KR) by Jong-In Kim
• Latvian (lv_LV) by Mike
• Lithuanian (lt_LT) by Karolis Vyčius and Mantas Malcius
• Norwegian (nb_NO) by Tom Arne Sundtjønn
• Polish (pl_PL) by Perfecta
• (European) Portuguese (pt_PT) by Stefan Mueller of fernstadium-net
• Brazilian Portuguese (pt_BR) by Rafael Fischmann of macmagazine.br
• Romanian (ro_RO) by Uhren Shop
• Russian (ru_RU) by Marat Latypov of