Working With Custom Hooks: OnCategoryRenamed
Taxonomy categories can be applied to content items in the CMS and are primarily used for querying, filtering, and sorting content on a website. We look at how this custom hook can be used to set paramaters around how and when a category is renamed.
Taxonomy categories can be applied to content items (pages, components, and assets) in the Taxonomy Management System. These categories are primarily used for querying, filtering, and sorting content within the context of a web site.
When categories are applied to Content Items, it enables the content to be sorted or filtered on a web page. Typically, you’ll see this functionality in facets like radio buttons, checkboxes, or dropdowns on a page that allow users to select a category of content to display in a set of results. In the CMS, the Schema of the page that is displaying the faceted list of categories has a Taxonomy Navigation Element that pulls in the child categories of a parent category, which is how these categories display as facets on the web page.
Changes to categories are published to a target immediately on the next publish, whether incremental or full.
In this article, we’ll examine how to use the OnCategoryRenamed custom hook to apply rules and structure to the action of renaming a category in the Taxonomy Management System.
How to Trigger the Hook
This method is triggered through the following actions:
- Right-clicking on a Category and selecting Rename from the Context Menu.
- Left-clicking on a Category and editing the content in the Title Field in the Category Tab.
- Triggering an API script that uses a Rename action on a Category.
When to Use This Custom Hook
CMS Administrators might be interested in setting up dynamic and detailed parameters around how and when a Category is renamed. For example, they may want to:
- Control who can rename a category (without taking away all taxonomy management privileges – see example directly below).
- Control parameters around pre-defined naming conventions.
- Trigger other affected content to update.
For example, in Users/Groups in the Administration Section of the CMS, Administrators can set permissions to limit who can rename Categories by navigating to the section titled Permissions on taxonomy system. Here, the permission can be set to allow or disallow a user/group to rename categories by checking or unchecking the box for “Allowed to Manage the Taxonomy System.” By unchecking this box, you take away the user’s ability to manage or edit taxonomy categories in any way. For Administrators aiming to limit a user’s ability to rename categories while maintaining their ability to work in the taxonomy system in other ways, they’ll need to turn to this custom hook.
Considerations
As always, avoid renaming a category in this hook to avoid creating infinite loops.
Categories are not renamed often, even in large systems, so this hook can often be used with minimal impact. Think about how often the action might be taken in your system before writing complex code in this hook.
Example
Assign Associated Components that Query the Category to Editors
In the process of building a website in the CMS, you will often have components that build content to share across pages that pull in a list of items by taxonomy category such as news stories, blog posts, or events. These make it easy to share content that is relevant to the page being built.
With long term CMS maintenance, it is often the case that categories will adjust and change as the content gets built over time. This can mean that categories move in the structure or change names. A user changing the name of a category might not remember that there is a component that references that category. To keep content organized and updated this script assists the user by attaching the component to the category and giving the components to the editor’s group if the category rename triggers.
First, the content strategy is to store the component IDs in a comma separated list in the External ID of the matching category. This could be manual or put in place by another hook elsewhere. Start by checking if there is content in that field. If there is, split that content on commas.
Iterate through that list of IDs, get the editor’s user group, and if an item exists with the ID and contains the old category name in its name, make sure it’s checked out and replace the old category name with the new name. Finally, assign the renamed component to the editor’s group so they can approve the new name.
The catch at the end will provide a log entry if there are any errors in the process and give us the category name that was attempted.
if (!string.IsNullOrWhiteSpace(category.ExternalID))
{
string[] catList = category.ExternalID.Split(',');
foreach(string cat in catList)
{
IUserGroup editorsGroup = session.UserManager.UserGroup("UserGroups/98");
try
{
IPage currentComp = session.Site.Page(cat);
bool isCatCheckedOut = currentComp.CheckedOut;
if (currentComp != null)
{
if (isCatCheckedOut)
{
currentComp.AssignGroup(editorsGroup, "Categroy has been renamed");
if (currentComp.Name.Contains(oldName))
{
currentComp.Name = currentComp.Name.Replace(oldName, newName);
}
}
else
{
currentComp.CheckOut(true);
currentComp.AssignGroup(editorsGroup, "Categroy has been renamed");
if (currentComp.Name.Contains(oldName))
{
currentComp.Name = currentComp.Name.Replace(oldName, newName);
}
}
}
}
catch
{
session.Info("Issue with Rename" + cat);
}
}
}
Ways to Extend the Functionality Further
There’s an inherent frailty to working with strings. Extra work could be done to check the strings and make sure they are actually formatted properly. You might want to log any items that didn’t have properly formatted strings. And overall, you may want to have other hooks that are enforcing the formatting when users manually work on categories, as they could change the string to a broken format.
The editor’s group is hardcoded in this script, as is sometimes the necessary case with groups. The only group that can be relied upon is the Administrators group, as it cannot be changed. That group generally contains users that don’t perform content changes though, as they are only there to adjust settings or develop. You may want to use different custom hooks to ensure that any hardcoded items you use in your scripts aren’t able to be removed without proper procedure.
There are no comments yet.