[4.0] Support to set the location when saving a category through the API

[laoneo]

Summary of Changes

This PR adds the possibility to define the location of the category while saving it through the API. A location can be one of the following values:

• before
• after
• first-child
• last-child

If before or after is used it is advisable to also set the location_reference parameter which defines the sibling the category should be located.

Testing Instructions

Run the following curl command:

curl --location --request POST 'https://[your J4 website]/api/index.php/v1/content/categories' \
--header 'Content-Type: application/json' \
--header 'X-Joomla-Token: [your user token]' \
--data-raw '{
    "title": "test",
    "location": "first-child",
    "published": "1",
    "language": "*"
}'

Actual result BEFORE applying this Pull Request

The new category appears as last item in the list in the back end UI.

Expected result AFTER applying this Pull Request

The new category appears as first item in the list in the back end UI.

Documentation Changes Required

The new location and location_reference arguments need to be documented.

[laoneo]

@alikon , @khu5h1 can you guys give this one here a test too? Similar procedure as the other ones. Thanks!!

[alikon]

i guess we should do the same for endpoint POST {{base_path}}/api/index.php/v1/menus/{app}

[alikon]

I have tested this item ✅ successfully on b51641d

CS issue apart

---

_{This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/36318.}

[laoneo]

@alikon if accepted, then I can do also for menus.

[HLeithner]

While testing this it seems that api can by-pass the alias naming restrictions is this intended?

curl --location --request POST 'https://[domain]/api/index.php/v1/content/categories' \
--header 'Content-Type: application/json' \
--header 'X-Joomla-Token: [key]' \
--data-raw '{"location_reference":2,
    "title": "test before Uncategorised",
    "location": "before",
    "published": "1",
    "language": "*"
}

executing this command 2 times ends, in one item before and one (the second call) as last item... I know unrelated to this PR...

What the rest is working find but could we get some variable validation in this function because passing location and location_reference without input validation is wrong.

[laoneo]

Validation is done on the model level, so there is no reason to do it on the controller level as well. So if there is something missing on the validation side, it must be fixed in the model. But I casted to int in the controller to be double save.

[laoneo]

@HLeithner can you mark your test as successful please.

[HLeithner]

I have tested this item ✅ successfully on 323a846

---

_{This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/36318.}

[alikon]

I have tested this item ✅ successfully on 323a846

---

_{This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/36318.}

[alikon]

RTC

---

_{This comment was created with the J!Tracker Application at issues.joomla.org/tracker/joomla-cms/36318.}

[wilsonge]

Thanks!