ReOrder Posts within Categories

this plugin uses filters (posts_join, posts_where, and posts_orderby) to modify the front-end query for ordered posts and ensure the results are ordered as per your custom order.

However, get_posts function uses a ‘suppress_filters’ parameter which is set to true by default. You need to explicitly set it to false in your custom queries to ensure you retrieve yours posts in the right order.

By default the plugin allows you to order posts only within hierarchical taxonomies (categories). This is done as a means to ensure one doesn’t have spurious orders as allowing both tags and category ordering could lead to users trying to order a post in both and this would create issues which have not been tested by this author. Hence tread with caution if you enable this in your functions.php file,

add_filter('reorder_post_within_categories_and_tags', '__return__true');

Keep in mind that you will now see Pages as a post type to re-order, selecting such post types which do not have any categories associated with it.

Since v1.3.0 a new filter has been added that allows you to do that. Make sure you return a valid capability,

add_filter('reorder_post_within_categories_capability', 'enable_editors', 10,2);
function enable_editors($capability, $post_type){
    //you can filter based on the post type
    if('my-users-posts' == $post_type){
        $capability = 'publish_posts'; //Author role.
    }
    return $capability;
}

if an unknown capability is returned, the plugin will default back to ‘manage_categories’ which is an administrator’s capability.

You can now flag the custom sql table to be deleted when you disable the plugin from your dashboard with the following filter,
add_filter(‘reorder_post_within_categories_delete_custom_table’, ‘__return__true’)
note that this filter is fired when you disable the plugin in the dashboard. So make sure it is activated when you set this filter.

Yes, as of v2.0 newly published posts can be ranked first instead of last by default using the following filter,

add-filter('reorder_post_within_categories_new_post_first', 'rank_new_posts', 10, 3);
function rank_new_posts($is_first, $post, $term_id){
    $is_first = true;
    //you can filter by taxonomy term, or other post parameters.
    //WP_Post $post object being ranked;
    //$term_id for which the post is rank is being inserted.
    return $is_first;
}

NOTE: the post-type must already have a manual ranking for that category term for this hook to fire. TO ensure this, go to the post ReOrder admin page, select the category term and manually order a couple of post, this is enough to ensure this hook fires. Even if you have the manual ranking radio-toggle to ‘No’, this hook will still fire.

Yes. On v2+ of this plugin, the sortable cards are now displaying the thumbnail of each posts along with the title. The title text can be changed or added to in case you require additional meta fields to be displayed to help you manually rank your posts. To achieve this, hook the following filter,

add_filter ('reorder_posts_within_category_card_text', 'custom_card_text', 10,3 );
function custom_card_text($text, $post,$term_id){
  //the $text is set to the title fo the post by default.
  //$post is the WP_Post object.
  //$term_id is the taxonomy term being sorted.
  $text = '<div>'.$text.'</div><div>'.get_post_meta($post->ID, 'custom-field', true).'</div>';
  return $text;
}

Yes, by default the first time you manually sort your posts, they will be presented in the same order as your post table, namely by post data. There are 3 possible alternative default order you can set,
1.reverse chronological by hooking this filter,

add_filter('reorder_posts_within_category_initial_order', 'reverse_order', 10, 3);
function reverse_order($reverse, $post_type, $term_id){
  //$reverse is a boolean flag.
  //$post_type for the current posts being ranked.
  //$term_id of the taxonomy term for which the posts are being ranked.
  return true;
}

1. by alphabetical title order, using the following hook,

   add_filter(‘reorder_posts_within_category_initial_orderby’, ‘chronological_or_alphabetical_order’, 10, 3);
   function chronological_or_alphabetical_order($is_alpha, $post_type, $term_id){
   //$is_alpha is a boolean flag set to false by default.
   //$post_type for the current posts being ranked.
   //$term_id of the taxonomy term for which the posts are being ranked.
   return true;
   }

2. or by reverse alphabetical title order, using both of the above hooks,

   add_filter(‘reorder_posts_within_category_initial_order’, ‘reverse_order’, 10, 3);
   function reverse_order($reverse, $post_type, $term_id){
   //$reverse is a boolean flag.
   //$post_type for the current posts being ranked.
   //$term_id of the taxonomy term for which the posts are being ranked.
   return true;
   }
   add_filter(‘reorder_posts_within_category_initial_orderby’, ‘chronological_or_alphabetical_order’, 10, 3);
   function chronological_or_alphabetical_order($is_alpha, $post_type, $term_id){
   //$is_alpha is a boolean flag set to false by default.
   //$post_type for the current posts being ranked.
   //$term_id of the taxonomy term for which the posts are being ranked.
   return true;
   }

as of v2.4 it is now possible to programmatically rank the intial post order, see FAQ 11.

When you have a large number of posts in a category, the controls move when the limit of posts to display is reached.

This to reduce the load on the server. WP limits REST api posts to 100, and this is the base value used. However, the plugin uses a dynamic approach, based on a square grid, hence when your posts grid number of columns equates the number of rows, the slider will automatically adjust the non-dragged slider button to maintain that square.

If you wish to display more posts, reduce your window zoom level (ctrl+mouse scroll on firefox/chrome), this will force the number of columns to expand and therefore the js script will allow more posts to be loaded until the rows match the columns.

When you have a custom query to display a set of posts on the front-end which combines multiple post-types under a single taxonomy term, then the plugin needs to be told which post-type to use to rank the results. It will fire a filter which you need to hook,

apply_filters('reorderpwc_filter_multiple_post_type', 'ranking_post_type',10,2);
function ranking_post_type($type, $wp_query){
  //use WP_Query object to figure is this is your query,
  //then return the post-type the to use to rank the results.
  //if no type is returned the posts will be ranked by date.
  return $type;
}

There are several reasons why this might happen,

1. You are using a custom query get_posts()…
If you are displaying your posts using a custom query with the function get_posts() you should be aware that it sets the attribute ‘suppress_filters’ to true by default (see the codex page). The ranked order is applied using filters on the query, hence you need to explictly set this attribute to false to get your results ranked properly.

2. Your theme or custom query explictly set the ‘orderby’ query attribute. **
If your **query explicitly sets the ‘orderby’ attribute, and the override checkbox is checked (see screenshot #5), then the plugin will override your query and rank the results as per your manual order. However, if you uncheck the ovverride setting (ie override is set to false), your query will be ordered as per the orderby directive. However, you can programmatically override the orderby directive with the following hook should you need finer control,

add_filter('rpwc2_allow_custom_sort_orderby_override', 'override_orderby_sorting', 10,5);
function  override_orderby_sorting($override, $wp_query, $taxonomy, $term_id, $type){
    //check this is the correct query
    if($wp_query....){
      $override = true;
    }
    return $override;
}

** 3. You are displaying a taxonomy archive page. **
If your query is a taxonomy archive query for a given term, then WordPress core query does not specify the post_type by default see this bug). This forces the plugin to seek which post_type is associated with this taxonomy. In the event that you are using this taxonomy to classify multiple post types this will lead to the plugin choosing the first type it encounters with available posts for the queried term, and this may give spurious results. A hook is provided for you to correctly filter the post_type and ensure the right results,

add_filter('reorderpwc_filter_multiple_post_type', 'filter_my_ranked_post_type', 10, 4);
function filter_my_ranked_post_type($type, $post_types, $taxonomy, $wp_query){
  /* String $type post type to filter.
  *  String $post_types post types associated with taxonomy.
  *  String $taxonomy being queried.
  *  WP_Query $wp_query query object. */
  if('my-custom-tax' == $taxonomy && in_array('my-custom-post',$post_types)) $type = 'my-custom-post';
  return $type;
}

If you are migrating from another plugin in which you have painstakingly sorted your posts, or you need have the intial order of posts based on some other criteria (some date or other meta field value), then you can use the following filter to pass the required rank,

add_filter('rpwc2_filter_default_ranking', 'custom_intial_order', 10, 4);
function custom_intial_order($ranking, $term_id, $taxonomy, $post_type){
  //$ranking an array containing a list of post IDs in their default order.
  //$term_id the current term being reordered.
  //$taxonomy the taxonomy to which the term belongs.
  //$post_type the post type being reordered.
  //check if this is the correct taxonomy/post type you wish to reorder.
  if('my-custom-post' != $post_type || 'my-category'!=$taxonomy ) return $ranking;
  //load you default order programmatically... says as $new_order from your DB
  $filtered_order = array()
  foreach($new_order as $post_id){
    //check the post ID is actually in the ranking.
    if(in_array($post_id, $new_order)) filtered_order[]=$post_id;
  }
  return $filtered_order;
}

in version 2.6.1, an additional filter is introduced to allow different post status to appear in the initial rank,

add_filter('rpwc2_initial_rank_posts_status', 'allow_draft_in_initial_order',10,3);
function allow_draft_in_initial_order($status, $post_type, $term_id){
  //allow draft post to be ranked initially.  By default $status=array('private','publish','future').
  if('post'==$post_type){
    $status[]='draft';
  }
  return $status;
}

this will only affect the posts in the admin dashboard reorder page.

Yes! By default all posts moved to draft/pending status are removed from the manual ranking. However, you can hook the following filter and control which draft or pending posts should appear in the manual ranking in the amdin dashboard,

add_filter('rpwc2_rank_draft_posts', 'allow_draft_posts_in_ranking', 10, 5);
function allow_draft_posts_in_ranking($allow, $new_status, $old_status, $term_id, $post){
  //$new_status of the post being saved.
  //$old_status of the post being saved.
  //$term_id term for which the post is being ranked.
  //WP_Post object being saved.
  if(new_status == 'pending' && $term_id == 5){ //allow pending posts for term id 5 to be ranked.
    $allow = true;
  }
  return $allow;
}

NOTE: this will only affect the admin dashboard queries. Your draft posts will appear in the admin re-order pages but will not appear in the front-end queries, as only published posts will be retrieved by your queries.
If you need to have draft/pending posts in the intial ranking, see FAQ #11.

Yes, there is a filter that allows you to control those too,
add_filter(‘rpwc2_rank_published_posts’, ‘disable_future_posts_in_ranking’, 10, 5);
function allow_draft_posts_in_ranking($allow, $new_status, $old_status, $term_id, $post){
//$new_status of the post being saved.
//$old_status of the post being saved.
//$term_id term for which the post is being ranked.
//WP_Post object being saved.
if(new_status == ‘future’ && $term_id == 5){ //do not allow future posts for term id 5 to be ranked.
$allow = false;
}
return $allow;
}
NOTE: note that this will effect front-end mixed-queries trying to display both future (and/or private) and ‘publish’ed posts.

as of v2.6.1, the intial sorted posts includes future and provate posts which you can remove using,

add_filter('rpwc2_initial_rank_posts_status', 'disable_future_in_initial_order',10,3);
function allow_draft_in_initial_order($status, $post_type, $term_id){
  //allow draft post to be ranked initially.  By default $status=array('private','publish','future').
  if('post'==$post_type){
    $status=array('publish','private');
  }
  return $status;
}

NOTE: in all 3 cases, you may use the reset button (see screenshot #3) on the reorder admin page to get the filters to change the order.

In v2.7 a new filter has been added to do just that, allowing you to override the sorting of anually ranked posts,

add_filter('rpwc2_manual_sort_override', 'override_manual_sorting', 10,5);
function  override_manual_sorting($apply_sorting, $wp_query, $taxonomy, $term_id, $type){
    //$apply_sorting a boolean to filter, true by default, which will apply the manual sorting.
    //the current queried $taxonomy with $term_id for post_type $type.
    // $wp_query is the WP_Querry objet
    //check some parameters a
    if(....){
      $apply_sorting = false; //do not sort using the manual ranking.
    }
    return $apply_sorting;
}

use the WordPress core functions,

get_the_posts_navigation(),
or get_previous_posts_link() and get_next_posts_link().

Unlike the the posts navigation links, the function get_adjacent_post() can be called outside a paged query, and will not return the correct post IDs in your manual sorted posts.

as of v2.8, a new function is provided to expose this functionality, however you will need to provide the post ID, the taxonomy term and the post type which identifies this post as being part of a manually sorted list of posts for that term.

 $adj = get_adjacent_rpwc2_posts($post_id, $term_id, $post_type, $taxonomy);
 //if the post is part of a manually ranked list,
 $adj->prev_post; //this is the previous post ID, null is the post is the first in the list.
 $adj->next_post; //this is the next post ID, null is the post is the last in the list.

The old plugin (v1.X) used a custom table to stored the manual order of posts. This legacy data will be imported into the new plugin when you upgrade. However, it is important that you delete the old table once you have successfully imported your ranking data.

How so I know if the data was successfully imported?
Go to your posts reorder admin pages, for each manually sorted term, check that your posts are in the correct order and that none are missing. If the lists of posts are correct (the right number of posts in the right order), then move the 2nd posts to the first position and back to the 2nd position. This will automatically save the ranked list into your database usign the latest format. Repeat for all manually sorted terms. Once they are all saved with the new format, you will need to delete the legacy table.

If you have spurious post listings then it is possible the imported data has been corrupted, you can reset it using the provided reset button, however, if the list of posts is still showing erroneous results then you will need to reset the manual ranking for that term one you have deleted the legacy table, and manually re-order your posts.

How do I delete the legacy data? **
In your dashboard, navigate to the Settings->Reorder Posts page, scroll to the bottom of the page and proceed to the delete the legacy table under the section title: **’Delete old custom table from plugin v1.x’.

v2.11 introduced the get_rpwc2_order() function to do this.

//the function returns an array of post IDs for a given post type and term ID
$ranking = get_rpwc2_order($post_type, $term_id);
//the ranking will refelct the manual sort order that was saved in the admin reOrder page.
$zero_based_rank = array_search($post_ID, $ranking);

As of v2.13 this is now possible thanks to the contribution from @robrecord. You will need to add the ‘inherit’ post status to the allowed status to make it work using the following filters in your functions.php file,

add_filter(
    'rpwc2_initial_rank_posts_allowed_statuses',
    function ($statuses) {
        $statuses[] = 'inherit';
        return $statuses;
    }
);

add_filter(
    'rpwc2_initial_rank_posts_status',
    function ($status, $post_type, $term_id) {
        if ('attachment' === $post_type) {
            $status[] = 'inherit';
        }
        return $status;
    },
    10,
    3
);

Sure, if you enable WP_DEBUG and WPGURUS_DEBUG in your wp-config.php file,

define('WP_DEBUG', true);
define('WPGURUS_DEBUG', true);

the plugin will printout debug messages, along with the final SQL query for your manually ranked posts. This is useful in order to determine if another plugin is also filtering your posts queries and overriding the ranking of the resuls.