Knowledge Base

Working With Custom Hooks: OnEmptyRecycleFolder

When a user deletes an item from the Site Tree it is moved to the Recycle Folder. A CMS administrator may want to have scripts developed for this hook to prevent important content from being removed from the site tree or deleted permanently.

When a user deletes an item from the Site Tree it is moved to the Recycle Folder. As the content item is moved to the Recycle Folder, it is automatically unmarked for publish. If multiple content items are deleted at once, they will retain the same structure they were in when they were in the Site Tree. For example, if a folder full of items is deleted they will still be in that folder after they move to the Recycle Folder. The Recycle Folder holds items indefinitely until a user or service deletes the items permanently, either individually or by emptying the folder.

A CMS administrator might be interested in having scripts developed for this hook to prevent removal of important items that might have accidentally found their way to the recycle folder, to do audits on the items to see if they left any links or relics of content behind that should be adjusted, or to add extra logging or notifications about the items before they are permanently removed.

This action can be triggered using the following methods:

  • Right-clicking on the Recycle Folder in the Site Tree and selecting Empty Recycle Folder from the context menu.
  • Invoking a custom script that uses the EmptyRecycleFolder method in the CSAPI.


This hook is only triggered on a full empty of the Recycle Folder, not for the deletion of individual items in the Recycle Folder. If you are concerned about individual/manual deletions from the folder you can use the OnBeforeDelete hook to see if the user is attempting to delete something from the Recycle Folder by testing the ancestry of the chosen item.


Prevent unarchived content items from permanent deletion

In this example, an organization wishes to prevent the permanent deletion of content items from the system. This is commonly the case for organizations who might need to undergo an audit or receive an information retrieval request.

Let’s assume you are running an archival task as part of your content removal process for items from the CMS and that this is a mandated process for your content. Certain types of content items must be archived before they can be permanently deleted from the CMS. As part of this process, a hidden and read only (so that it is only checked by the automated process and not an individual) checkbox has been added to all schemas that need to adhere to the process called Archived. When an item is archived the box on the content item is checked.

Starting with the Recycle Folder object that is provided in the hook, collect all the content items in the folder and loop through them. Find the Archived checkbox element on the content items and, as long as it is there and marked as true, proceed. If it is not marked as true, throw an exception.

As always, any exception thrown prevents the entire process from finishing. Make sure you throw a message that informs the user why they couldn’t finish the task.

int outVar;

IEnumerable<IPage> recItems = recycleFolder.Descendants(out outVar);

foreach(IPage item in recItems)


  IElement archived = item.Element("Archived");

  if(archived != null && archived.Value != "true")


    throw new System.ArgumentException("Item " + item.Id + " has not been archived.");



This script could be enhanced in the following ways: 

Stopping the empty recycle folder action from taking place may prove a bottleneck for users and slow down their progress – it can also just be annoying. You might consider enhancing this custom hook by adding a script to automatically archive the content items that need to archived prior to deletion, but are not yet archived. Another option is to send unarchived items to a separate folder for review at a later date, then complete the full recycle action on the remaining items in the folder that are approved for permanent deletion.

  • Published: January 2, 2023
  • LAST UPDATED: September 18, 2023
  • Comments: 0

Please login to comment


There are no comments yet.