Related Posts Pro for WordPress

An elegant related posts solution.

This documentation is intended for the Related Posts Pro for WordPress plugin. Please read it carefully.

Easiest method: Upload and Install

In WordPress the easies way of adding a new plugin is by the built-in plugin manager. Follow these steps to succesfully install this plugin:

  1. Save the related-posts-pro.zip plugin file somewhere on your computer.
  2. Log in to your WordPress backend area, it's usually yourdomain.com/wp-admin

     
  3. After logging in go to the plugin manager and click on the upload button and Install


     
  4. After successful installation all you need to do is activate the plugin

 

I highly recommend this method, it should work on 99% of all servers. If by any reason this method is not working, or it's not possible, then there is another way of installing a WordPress plugin.

Advanced method: Upload via ftp

You can upload the plugin folders directly to your sites plugin directory. If you don't know how to connect to your website via ftp, I recommend reading the following article: Filezilla tutorial

  1. After connecting to your server via ftp, you should search for your site's wordpress directory. It's usually located in a path like public_html/wp-content/plugins/ or www/wp-content/plugins/
  2. Unzip the related-posts-pro.zip file and copy the reladed-posts-pro folder to the servers plugin directory


     
  3. After succesfully copying the related-posts-pro directory you will still need to activate the plugin. Log in to your sites backend. (see step 2. in previous chapter)
  4. Open up the plugin manager and click on the Activate link under the plugin name


     

That's it! After activation you should use be able to use the plugin.

Multisite installation

Works the same way as non-multisite installation. Please read the previous chapters.

You got this far, nice. Now you need to create a Related Posts Pro instance to see something.

But why do I need to create instances, why not just configure?

This way you can have multiple Related Posts Pro widgets around your site, with different layouts and behaviour if you want to.

Create an instance

By clicking on the newly visible Related Posts Pro menu item on your backend, you will be able to create a new Related Posts Pro instance. You can name it whatever you want.

After clicking the Add button, you should see the new instance below the form.

By clicking on the settings icon, you can modify the overall behaviour and layout of that instance.

Placing the instance to the frontend

By default, the new instance will immediately show on the frontend below every post content. You can turn it off or you can select different places for this instance on the Layout options panel under the Output options tab.

As you can see, there are lot of options available, but you don't need to deal with all of them, since the default values are set for the most common usage.

On the output options panel you can see the following:

These options define where the instance is placed. By default the plugin is hidden from any content type. Probably the best way to start is to enable the "Show plugin under content" option. You can also set to show above content, on pages, on homepage and on archive pages.

Please be aware, that in some cases the plugin might not show correctly, because the final layout can be affected by other plugins or the template as well. In that case, the shortcode should be used instead of these options.

Output placement

It is possible to select to which content types do you want to output the plugin. By general the posts and pages are enabled.

You can also select custom post types if you have any.

Please note, that in very rare cases some post types are not filtered by the "the_content" filter. This means that the plugin will not show even if you select that custom post type. On those cases you will need to insert the shortcode directly to the template.

Using the shortcode

If you prefer to place the instance manually instead (or you are having issues), you can use the shortcode provided for each instance.

There are two ways of using the shortcode:

  1. In post/page/custom post content
  2. In the template

Placing the shortcode to the content

When you go to the post editor you should see a new button, with the following caption: RPP

After clicking on that button a drop-down menu will appear, where you can select which Related Posts Pro instance you want to insert.

You can use each shortcode as many times as you want.

Placing the shortcode into the template

Before editing your template, always make a backup first! You might also want to consult with the theme developer before making changes, he might give you an advice how to proceed.

For editing the files you will need an ftp powered text editor, like Notepad++, Pspad Editor or Sublime Text

After setting up the ftp credentials with your favorite editor, you should start searching for the active template files. The usual location is public_html/wp-content/themes/{theme-name}/

The structure of each template is different, you can check the default theme hierarchy for more information.

Open up the file you want to edit and place the shortcode you were provided on the top of the RPP instance options panel: (select and copy)

<?php echo do_shortcode('[wpdreams_rpp id=0]'); ?>

After placing this code to the template file, save it, clear every cache you might have and refresh the page - you should be able to see the RPP instance on the desired location.

 

There are 3 possible layout modes for the plugin:

You can change the layou mode on the layout options panel.

Each layout type is very different from others. Go ahead and try them!

Isotopic layout

Based on the famous jQuery isotope plugin. It gives you a full list of items with a very nice responsive and filtering animation. Fits most with low amount of items (<20).

Slick layout

Based on another very nice jQuery plugin called Slick'n Slide. This is a one row layout and fits any number of items well. It support swipe animations very nicely.

Transitioning layout

Based on codrops item transitions article. A very neat layout using purely CSS3 animations. Also support mobile swipe effects.

The behaviour of the plugin defines how it reacts to it's environment. You can make basic customisations like results count as well as advanced customisations like caching.

Result items

Items are the result of the "search" done by the plugin, based on the input parameters. The items output behaviour can be customiszed mainly on the General options panel.

Override - Global

You can override the items globally and locally as well. Global override means that for each post the result items will be overriden with the defined content, and local override means the same, but for only one specific post.

This gives you more control over the plugin in situations where you only want to show specific content in all cases or only in one specific case.

The override source determines where the overridden content is derived from.

Override for certain post - Local

Under the post editor you should see a new metabox called Related Posts Pro Settings.

If you don't, then you don't have an RPP instance created yet (previous section) or you have the metabox disabled by default. You can enable it by clicking on the Screen options on the top-right corner of the page.

Now, you should be able to see the new metabox under the post content editor.

Custom content

It is possible to define custom content for each post globally and locally, just like the override options. These items can be used then as a source for filling and overriding. You can search custom content from the blog or create your own as well.

By clicking on the magnifier will bring up the latest 100 content from your website. You can enter a search term as well, if you are looking for a specific post. By clicking on the "+" in the content box will add it to the selected custom content bar.

You can add/remove as many items as you want. By dragging them around will change their order. The first item will have the highest relevance value and the last item will have the lowest.

If you want to create your own custom content then all you need to do is fill out the required fields on the "Add Custom Content" panel and click on the add button.

The Title, URL and Content are required fields, the others are only optional.

With relevance options you can define how the plugin should treat certain conditions and aspects of the content. The Relevance options panel offers you a great deal to optimize this behaviour.

Where to look for similarities?

By default the plugin will try to look for similar content by examining and comparing the content, excerpt and the title of each post/page/custom post type. You can also add custom fields, if you feel that there is valuable content hiding in them.

How are these fields compared?

By default every field is compared to every field. So the current posts title will be compared to all other posts title, content, excerpt. This is done with every selected field.

In other words, the fields are not exclusively compared to each other. Luckily there is an option for that. If you only want to have compared the titles vs titles, content vs content etc.. then you have to turn on the Keep each field exclusive? option.

After the change the plugin will compare titles with titles, content with content, etc..

Relevance values

Relevance values are integer values, which define the importance of each field. The higher the value, the important the field is.

You should leave these values as they are first. After you done some tests expecting other results, then you should only start changing them.

In my advice values 1-10 for each field are the best, but of course you can use higher numbers as well.

Please use positive integer values only!

Keyword options

These options can change the plugin behaviour and performance a lot, please be careful!

Keywords are extracted from each field (title, content ...) individually. You can however change how these keywords are extracted.

Before processing the text for keywords, all extra spaces and non-letter characters are removed!

These keyword options does not affect the post title, because the title field is usually very short and it requires a special configuration for correct keyword extraction.

Keyword restriction file

As you can see on the previous image, you can specify the path to a restriction text file, which contains words, which are restricted from keyword usage. These are mostly NSFW phrases or very common phrases. The default keyword restriction file location is wp-content/plugins/related-posts-pro/restricted.txt

You can create or modify the existing keywords.txt file, but each word in the file must be separated by space character!

Content options determine, what kind of content do you want to see on the output, and which aspects of it should be outputted.

The content options are availabel on the Content Options panel. By default the plugin returns posts and pages, but you can also return custom post types if you want to.

Formatting options

Usually the post content comes with lots of html tags in it, and sometimes with shortcodes in it.  You can choose whether you want to strip these tags or keep them.

There is an order of operations for these options. It means that first of all the content is checked for shortcodes and depending on the settings they will be stripped or ran, and then the HTML is stripped from the result if enabled.

You can specify which HTML tags you want to keep in the content. Only the opening tags are needed with no separator, for example:

Unspecified tags will be stripped, but their content remains.

Custom format Options

These options let's you to add custom field values and other content to the title, description, date and author fields. It is especially useful if you want to display extra information on these fields, like product price, user post count etc.. Everything that is stored in a custom field can be outputted.

Everything between "{ }" is treated as a custom field, except for the default values:{titlefield} {contentfield} {authorfield} {datefield}.

For example showing the product price in title with WooCommerce you can use the following pattern:

{titlefield} - {_price}$

Output: Test product - 4$

Advanced Content Options

These options provide even more customisability for the output. Ba cautious when changing them, they greatly affect the overall plugin layout.

There is also a possibility to change the default fields and prevent the content and title filters from running.

These filters are general hook points for many plugins and templates. I recommend leaving these settings ON. 

The plugin has a robust built in image image parser and two different image processors.

As you can see it is possible to change the image width/height (it's in pixels) and the image background for transparent images.

You should always check/change the image size if you made drastical changes on the theme options, they might not fit correctly.

There are 6 different image sources

You can assign one of these image sources to a primary and 4 alternative image sources. If no image was found from the primary image source, then the alternative sources will be checked.

Timthumb or not

After succesfully retrieving an image from one of the sources the plugin will check which image processor engine is selected. By default it's the TimThumb. It's a very powerful and safe choice, however it may use a little bit more CPU power when it parses through the results, because the images are parsed when the page is loaded.

The built-in image parser will however block the site loading if used on many images. Use the TimThumb option and change only when  you are having great difficulities with it.

By default the filtering buttons are enabled. They are used to filter the results by post type and category. This is handy if you are having many categories and multiple post types active at the same time. A good example is having a webshop like WooCommerce items and blog entries in the same RPP widget.

This section is about filter buttons layout. These options does not affect the default output of the items.

You can find the filter buttons settings under the layout settings panel.

Visibility and caption

If you however decided not to use one or both of these filters, you can easily turn them off. You can also change the labels if you don't like them.

Combining the filters

By default the filters are in an inclusive relationship, meaning that if the user filters a post type and then a category on the frontend, then the plugin will include both of these circumstances for filtering. (as an AND logic)

However, it is possible to change this relationship to exclusive, by turning off the Combine filters option. In this case only the last used filter will be taken into account. So it doesn't matter if the user filtered the results by a post type, if he now filters by a category, the previous post type filter will be disregarded (and vice versa) and all the post types will be shown. It's basically an exclusive OR logic.

Post type filter

If you whish to show other post types than Post and Page, then you can select which ones do you want.

Once again, this does not affect the results list, only the filter. To see results from post types, you need to go to the advanced options panel.

Categories and Taxonomies filter

You can also select which categories to exclude and which taxonomies to include in the filters.

The plugin will only show categories and taxonomies that are available in the results.

There is a real time search filter available for the plugin. It allows the user to filter through the outputted results.

It is also possible to sort the results by relevance and title. This gives the user more control over the content.

You can easily edit the caption of each button.

Default sorting options

In case you need to change the default sorting and the sorting order you can do that on the same tab.

Let's start by examining the overall layout of the plugin for better understanding. These phrases are going to be used in many options regarding the theme.

This is the general layout of the plugin.

The template options are pretty straigthforward and mostly understendable without further explanation. I will however explain some of the options in each upcoming chapter.

The theme Chooser

The theme chooser is the first visible option on the theme options panel. It allows you to choose from a set of over 65 pre-defined templates.

Preview

You can preview the changes in the template of the plugin by clicking on the show button on the box located on the right bottom side of the page. 

You can change the background to your frontend background value for better visual experience.

After clicking on the show button, the preview are will move upwards and load the current defined theme options.

After changing a few things on the theme options panel you can refresh the preview window to preview the changes.

Container Layout

The container element is the placeholder, holding the contents all together. Everything is inside this container element. It is possible to change various things on this element on the theme options panel.

Some options explained

Search box Layout

The search filter box layout is allowing the user to filter the results by a search phrase.

Some options explained

Filter Sort buttons layout

You can hide the Arrow with the Show the arrow option.

Navigation Buttons

Proper navigation layout can greatly increase the user experience. When changing these, you should try to make them similar to Filter/Sorting buttons.

If you are planning to upload custom icons, then please use the size 18x18 pixels for best results. Be also aware that coloring these icons are not possible.

Isotopic, Slick and Transitioning layout

There is no point to cover each layout in a different chapter as they are not so different styling-wise. On these layout settings you can change the output items properties.

In transitioning layout you can't choose the width of the item, since it's automatical, but you can shoose from different animations.

Content Typography

The font-related options on this panel are absolutely straightforward, however, there are two options that may be unclear:

Custom CSS

This is a standard custom CSS field. Avoid however the use of the " and ' characters if possible.

Please not that some of these options are intended for experienced users. Please change them with caution.

Cache options

There is a built in cache for the plugin to make consecutive page loads much faster.

The cache expiration is set to 3600 seconts aka 1 hour. You can adjust the cache duration to your own needs. A usual good value is the frequency of your blug update. If you are updating your blog dialy, then a 24 hour aka. 86400 seconds cache duration is optimal. 

Autoplay

Autoplay is the function that triggers the next button periodically.

It's not really an advanced option, however entering incorrect values in the interval box may break the plugin temporary.

Autoplay is interrupted when the mouse enters the plugin container. When the mouse leaves it restarts.

Fulltext options

By default the plugin tries to use the fulltext search mode for the SQL queries if the posts table uses the MyIsam database engine.

On small databases it's more of a preference then a performance option. You can read more about Fulltext search here.

If you are having issues with the results, you can try to turn off the fulltext lookup feature.

Advanced Output Hooks

This feature is nice if you don't want to touch the current theme/plugin code and you are aware of the filters/actions placed in the theme.

Some themes and plugins, like Woocommerce are using actions to give the users and developer an access point to certain points of the plugin. These access points are the hooks, or in other words actions and filters.

This plugin can access these hooks and output itself where the hooks are called. Copy and paste the action/filter name to the corresponding textare to have the plugin outputted on that hook.

Excluding categories and taxonomies

You can exclude posts and custom post types belonging to a certain category or taxonomy term. Use the drag and drop lists to select which categories or terms you want to exclude.

Excluding posts by ID

The last option on the Advanced options panel. The IDs must be separated by a comma ",". This option applies to every post type and page.

This section is for developers only.

Actions list

/* The actions list for the Related posts pro plugin */

/* 1. Functional actions */

    // No possible functional actions yet

/* 2. Layout Actions */

    Parameters:
        $id (int) - the id of the related post instance
        $content_array (array of Objects) - contains all the items (posts,pages,..) for output
        $options (array) - contains all the options for the current Related posts pro instance

    // Before the container output
    do_action('rpp_before_output', $id, $content_array, $options);

    // Before the title output
    do_action('rpp_before_title', $id, $rpp_related_posts, $options);

    // After the title output
    do_action('rpp_after_title', $id, $rpp_related_posts, $options);

    // Before sort/filter buttons
    do_action('rpp_before_buttons', $id, $rpp_related_posts, $options);

    // After sort/filter buttons
    do_action('rpp_after_buttons', $id, $rpp_related_posts, $options);

    // Before the search box
    do_action('rpp_before_searchbox', $id, $rpp_related_posts, $options);

    // After the search box
    do_action('rpp_after_searchbox', $id, $rpp_related_posts, $options);

    // Before item wrapper container
    do_action('rpp_before_item_wrapper', $id, $rpp_related_posts, $options);

    // After item wrapper container
    do_action('rpp_after_item_wrapper', $id, $rpp_related_posts, $options);

    // Before each item's (post's) outer container
    do_action('rpp_before_item_outer', $id, $rpp_related_posts, $options);

    // After each item's (post's) outer container
    do_action('rpp_after_item_outer', $id, $rpp_related_posts, $options);

    // Before each item's (post's) inner container
    do_action('rpp_before_item_inner', $id, $rpp_related_posts, $options);

    // After each item's (post's) inner container
    do_action('rpp_after_item_inner', $id, $rpp_related_posts, $options);

Filters list

/* The filters list for the Related posts pro plugin */

/* 1. Item content related filters */

    Params
        $item (reference) - a reference to the item object

    // Item before post-processing
    apply_filters( 'rpp_item_before_postprocessing', $item );

    // Item after post-processing
    apply_filters( 'rpp_item_after_postprocessing', $item );

/* 2. Keywords related filters */

    Params
        $keywords (array) - array of keywords used in the search for related content

    apply_filters('rpp_keywords', $keywords);

You can also find these lists in the plugins/related-posts-pro/actions.txt and filters.txt files.

In some cases it is neccessary to change a few thing to get the maximum compatibility. The Compatibility settings submenu provides some very basic, yet very powerful optimalisations.

Load Inline styles?

This option does exactly what it says. Instead of writing the dynamically generated CSS files to the header it outputs it as inline styles. It's useful, if for some reason the styles are not saving.

Minify the stylesheet files when saving?

It will do a very basic minification of the CSS files after saving them. Please note, that after activating this option you will need to open each Related Posts Pro instance and save it again, to apply the minifications.

Javascript source

There are countless plugins written for WordPress and many of them uses jQuery. It's not uncommon, that sometimes it gets messed up and suddenly nothing will work. For these reasons there are implemented 4 levels of javascript security and minifications, to eleminate this problem:

By default the plugin uses the minified-scoped version to ensure the highest possible compatibility.