Adding a new Location to a Content
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, 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, 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 have 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().