Adding a new Location to a Content item
Full code
We have seen earlier how you can create a Location for a newly created Content. It is of course also possible to add a new Location to an existing Content.
This is the required code. As you can see, both the ContentService and the LocationService are involved. Errors are handled the usual way, by intercepting the Exceptions the used methods may throw.
Like we do when creating a new Content item, we need to get a new LocationCreateStruct. We will use it to set our new Location's properties. The new Location's parent ID is provided as a parameter to LocationService::newLocationCreateStruct
In this example, we use the default values for the various LocationCreateStruct properties. We could of course have set custom values, like setting the Location as hidden ($location->hidden = true), or changed the remoteId ($location->remoteId = $myRemoteId).
To add a Location to a Content item, we need to specify the Content, using a ContentInfo object. We load one using ContentService::loadContentInfo(), using the Content ID as the argument.
We finally use LocationService::createLocation(), providing the ContentInfo obtained above, together with our LocationCreateStruct. The method returns the newly created Location Value Object.
Hide/Unhide Location
We mentioned earlier that a Location's visibility could be set while creating the Location, using the hidden property of the LocationCreateStruct. Changing a Location's visibility may have a large impact in the Repository: doing so will affect the Location's subtree visibility. For this reason, a LocationUpdateStruct doesn't let you toggle this property. You need to use the LocationService to do so.
There are two methods for this: LocationService::hideLocation, and LocationService::unhideLocation(). Both expect the LocationInfo as their argument, and return the modified Location Value Object.
The explanation above is valid for most Repository objects. Modification of properties that affect other parts of the system will require that you use a custom service method.
Deleting a Location
Deleting Locations can be done in two ways: delete, or trash.
LocationService::deleteLocation() will permanently delete the Location, as well as all its descendants. Content that has only one Location will be permanently deleted as well. Those with more than one won't be, as they are still referenced by at least one Location.
TrashService::trash() will send the Location as well as all its descendants to the Trash, where they can be found and restored until the Trash is emptied. Content isn't affected at all, since it is still referenced by the trash items.
The TrashService can be used to list, restore and delete Locations that were previously sent to Trash using TrashService::trash().
Setting a content item's main Location
This is done using the ContentService, by updating the ContentInfo with a ContentUpdateStruct that sets the new main location:
Credits to Gareth Arnott for the snippet.