Working With Custom Hooks: OnCheckIn
In the CMS, checking in a content item in the Site Tree commits to history the working (checked out) version of the state of the edit form fields. Learn how to customize and extend this functionality in the custom hook.
In the CMS, checking in a content item in the Site Tree commits to history the working (checked out) version of the state of the edit form fields.
Users can trigger this action manually using the following methods:
- Clicking the Check In button in the toolbar above the edit form
- Using the right-click context menu in the Site Tree and selecting Check In
- Using the right-click context menu in reports results and selecting Check In
- Advancing a content item in a workflow that includes a check-in action
Considerations
You can use the before and after states to check the status of content on the transactional item, but it is usually best not to go directly to the Site Tree and access the same item.
You will need to think about how these hooks interact with your workflows and avoid taking actions that would put things in states they don’t belong in to avoid breaking the flow. Have your hooks work with content as closely as possible to the procedures of your users in order to keep your environment healthy. If they use workflow, use workflow in your hooks. If, instead of workflow, they manually check in pages and components, then feel free to take those same actions in your hooks.
Keep in mind that check in can be prevented by many things and cancel your script: such as required fields. If your associated components have strict security settings, many required content fields, or other requirements that could prevent check-in, you’ll need to account for that in your scripts.
Examples
Prevent Check In
One thing you can easily accomplish in a custom hook is prevent the check-in action from happening when something doesn’t meet the requirements of check-in.
By “requirements of check-in” we’re not referring to things like required content fields, which are handled by the system itself on schemas with required fields. In this case, we’re focusing on more complex requirements such as fields being filled in with specific types of data or associated content items (e.g., components, categories, assets, or databases) that need to be in a certain state in order for the page that contains them to go live.
As mentioned before, throwing an exception in your code will cancel the process of the custom hook, as if the user never took the action. In this example, an error is thrown when the page is not categorized. You will note that the error message is going to contain the stack trace for the error that you throw, so some extra padding is added to the message in this example to make sure the user sees why we are stopping their progress.
var pageCategories = page.AssociatedCategories(out outVar);
if(!pageCategories.Any())
{
throw new Exception(Environment.NewLine + "Please add categories to your page by going to the Categorize tab before checking in." + Environment.NewLine);
}
Check In Associated Components
When working with a large number of components in your site, it can sometimes feel tiresome to have to remember to check in all components associated with a page.
In this example, we’ll extend this custom hook to find all of the components on the page we are working on and check them in when we check in the page.
First, gather up a collection of the component fields on the page, which you can identify by their EnumElementType being IGX_COMPONENT (you can see the full list of types in the CSAPI documentation that is installed with the CMS software). Also, if you use AllElements method you will get components that are nested in list and group elements without having to manually dig for them. Then, collect the actual components that are placed in the fields by their ID. Make sure the attempt didn’t fail to return a component (it could have been deleted) and check to make sure that they are not already checked in before attempting to check the item in.
int outVar;
IEnumerable<IElement> pageComponents = page.AllElements().Where(e => e.Type == EnumElementType.IGX_COMPONENT);
var pubTargets = session.PublishingManager.Targets(out outVar);
if (pubTargets.Any() && pageComponents.Any())
{
foreach (var comp in pageComponents)
{
var componentItem = (comp.Value != "") ? session.Site.Page(comp.Value) : null;
if (componentItem != null && componentItem.CheckedOut)
{
componentItem.CheckIn(pubTargets, false);
}
}
}
There are no comments yet.