Working With Custom Hooks: OnCheckOutAsset
Checking out an asset in the Asset Tree is a common action and a necessary step in the editing process in the CMS. We explore how - and why - paramaters might be set on the action of checking out an asset using this custom hook.
Checking out an Asset Tree content item enables a user to take possession of the content item and edit it. There can only be one working copy of an item at any given time. Checked out copies of items cannot go live, their content must be checked in and marked for publish before they can be published to a live publishing target.
How To Trigger the Hook
This method is triggered through the following actions:
- Clicking the Check Out button in the toolbar above the edit form.
- Using the right-click context menu in the Asset Tree and selecting Check Out.
- Using the right-click context menu in reports results and selecting Check Out.
- Advancing a content item in a workflow that includes a check-out action.
- Performing a sync in Schema Designer on a content item and not selecting the option to “Sync pages without checking out”.
When to Use This Custom Hook
It is not very common to set parameters around the action of checking out an asset. When an asset is checked out, it signals the beginning stage of working on that content item so it’s hard to be sure what the motivations of the user are before they have started making changes.
That said, CMS Administrators might be interested in setting up parameters around how and when an asset is checked out to:
- Check out associated content items that must be worked on in tandem with the target content item.
- Prevent check out for protected items.
- Flag a thid party DAM system that changes are pending.
Considerations
If you use this hook to take actions on other items associated with the target content item, and those other content items are being worked on by users, the CMS won’t directly notify those users that the action has been taken. In this case, you may want to reach out to those users yourself. The platform has features that you can utilize to communicate with other users, like the new API notification system, emails, or logs.
Checking out is less impactful than checking in, since you can’t publish a content item that is checked out until you’ve checked it in again. However, you’ll still want to account for any settings you may have in place that would prevent a content item from being checked out.
Avoid using methods that check out content items within the check out hooks to limit chances of creating an infinite loop.
Example
Check out related assets
When an asset is being edited in the CMS, the user has the option to select Save As... to save a new version of the asset. For example, if a user is cropping or resizing an image, they’d save a new version of the image when they’re done making their changes. These two images would be related images.
In this example, consider that those related images might need to be updated in tandem to stay in sync, so when a user checks out one asset, we must also check out the related asset(s) and have everything assigned to the same user.
This example will require two parts, first you need to create a class outside of the hook to work with our related asset list outside the scope of the current item being worked on.
public class GlobalListHolder
{
public static List<IAsset> currentRelatedAssets = new List<IAsset>();
}
Once you have that data type to work with, you'll want to gather the data for the related items and convert them to a list inside the hook.
Ensure that the list exists and that it contains some items before looping through those items. Then, add them to the global list to track them with the transaction. This is essential, as the assets in the Asset Tree will not be checked out until the transaction is complete and you can’t terminate your conditionals, which would result in an infinite loop.
After you add the item to the list, check it out.
List<IAsset> relatedList = session.Site.RelatedAssets(contentItem as IAsset, out int count).ToList();
if (relatedList != null && relatedList.Any())
{
foreach (var item in relatedList)
{
if (!GlobalListHolder.currentRelatedAssets.Contains(item)) {
GlobalListHolder.currentRelatedAssets.Add(item); item.CheckOut(false);
}
}
}
Ways to Extend the Functionality Further
You may consider extending this function by adding code in the hook that notifies the user of the other content items that get checked out, otherwise they may be unaware that these related content items were checked out and assigned to them.
The RelatedAssets method returns a limited list of items that have been edited in the CMS and had new versions of them saved. Consider adding a different way of tracking which items are related to ensure that they are valuable to process together, such as adding them to a custom field on the asset when you link them.
There are no comments yet.