Pages::sort() unexpected result

[kixe]

Short description of the issue

Unexpected result using $pages->sort($page, $newSort);

Expected behavior

If I set a sort value of a page I would expect a setting of a zero based position relativ to the page siblings independent from the absolute sort value.

For handling pages the absolute sort value is not of interest, the index (position) is the important value and therefore the index position should be changed using this function.

Actual behavior

Example 1

$page->sort // int 4
$page->index // int 0
$page->siblings()->each('sort'); // array(4, 7, 11);
$pages->sort($page, 2); // int 1
$page->index // int 0 (instead of expected 2)

3 page siblings having the sort values 4, 7, and 11. If I assign a sort value 2 to the page with the former sort value 7 I would expect the page moves to the end (last index number under 3 siblings), but currently it moves in the opposit direction and will be the first one related to its 2 siblings.
To get the expected result the sort value could be anything bigger than 12.

Example 2

$page->sort // int 4
$page->index // int 4
$page->siblings()->each('sort'); // array(0, 1, 2, 3, 4, 5, 6);
$pages->sort($page, 5); // int 3
$page->index // int 4 (instead of expected 5)

There will be no noticeable change, because there is a gap at sort position 4 now. To get the expected result the sort value should be set to 6 while pushing the page with sort 6 to sort 7.

Note: Currently there is no core function to set $page->index

Optional: Suggestion for a possible fix

some input/ inspiration
https://processwire.com/talk/topic/15908-page-sorting-and-moving-via-api/
https://github.com/kixe/PageSortMove

Setup/Environment

• ProcessWire version: 3.0.57

[ryancramerdesign]

Hi @kixe the sort() method you are referring to is there specifically to deal with the actual page sort values, whatever they may be (what you've referred to as the absolute sort value). There can be gaps and this is expected. PW doesn't re-save every page sibling to re-number the sorts every time a page is sorted or deleted because that would not be scalable, nor necessary to maintain the intended order. The sort() method provides the needed method for core movements of manually sorted pages. If it was operating as an index() method, that would be a different method and a more expensive operation. Though the sort() method does provide the ability to rebuild the sort index if/when you want it, by using the 2nd argument as boolean true. I think this would provide the index numbering you are looking for? However, I would suggest using the $pages->insertBefore() and $pages->insertAfter() methods for page movements rather than trying to manipulate the sort values directly.

[kixe]

I agree that it is not necessary re-saving every page sibling to maintain the intended order and I have no problems with gaps. I don't care about the absolute sort value, it is not of interest. I played a bit around and finally could get/ set easily what I want via API in max. 2 or 3 steps. So finally this is not such a big problem. I just want to point out unexpected results. It would help to explain the functions behaviour more clearly in the docs.

The API documentation should be updated anyway since it is faulty because $page->sort as a setter doesn't behave same as $pages->sort()

in http://processwire.com/api/ref/pages/sort/

// set $page to have sort=5, moving any 5+ sort pages ahead
$pages->sort($page, 5); // works as expected

// same as above using alternate syntax
$page->sort = 5; // WILL NOT moving any 5+ sort pages ahead it just changes the sort value. 'sort' is not forced to be unique.
$pages->sort($page); // WILL NOT set anything. This is a getter, not a setter. Similar to $page->sort

[ryancramerdesign]

Thanks, you are right that example is completely incorrect. I have updated the phpdoc, and it'll appear at the page you linked when I update the version being used there.