Documentation

1. Description

“My locked items” is a usual Sheer UI portlet. Its purpose is to show the Items locked by the currently logged in User. It provides a convenient interface to check in your locked Items from inside the portlet. It saves you from browsing a large content tree and looking for Items that you locked and want to check in.

known issues: The My Locked Items portlet for Sitecore 5.2 sometimes tanks the performance of a Sitecore installation, when going from development to production, where one have more content. If you are affected by this issue, be sure to remove it.

No special skills are required to work with this portlet. After installing the package and restarting the Client, you should open the Content Editor, switch to the Overview mode, add content using the Portal panel and select this portlet. Please be sure to add the appropriate entries into the web.config file as described in the Readme section of the installation wizard.

2. Installation Guide

The “My locked items” portlet is distributed as a standard Sitecore package. Please refer to the ' Installing Modules and Packages ' article if you are not familiar with the standard Packager tool of Sitecore. After the package installation, please restart the Sitecore Client.

Add the following entries to the web.config:

<handler type="CheckedIn.Handlers, myitems" method="OnItemDeleted"/>
as a handler to the item:deleting section
<handler type="CheckedIn.Handlers, myitems" method="OnItemAdded"/>
as a handler to the item:saved section
<processor mode="on" type="CheckedIn.MyItemMessages,MyItems" />
to the <dispatch> section
<reference>/bin/myitems.dll</reference>
to the <ui>/<references> section

3. User Manual

Once you have successfully installed the package and restarted the Client, open the Content Editor, switch to the Overview Viewer and select Add content in the Portal pane. The portlets displayed by default in the Overview Viewer have the Default checkbox checked in the appropriate Item in the Core database. The Default checkbox is not checked for the ‘My Locked Items’ portlet, therefore you need to open the portlet manually.

The “My locked items” portlet provides you with information about Items locked by the current User. It shows the complete list of such Items, starting from /sitecore/content. There are several options available for managing locked Items:

You can open an Item in the Content Editor by double clicking on it.
The Refresh button runs through the cache and outputs its contents (read more about cache functionality in the Architectural notes section).
The Reload button clears the cache, rescans the content tree, and rebuilds the cache appropriately.
The Check In button unlocks the selected Item.
The Check In All button unlocks all the Items and clears the cache.

The portlet also contains event handlers in order to keep up to date with which Items are locked. The handlers are installed along with the portlet itself. The notes below describe how these handlers work:

When a new Item is created, its initial English version is automatically locked by the current User. The appropriate handler listens for this event and displays the new Item in the portlet.
When an Item is deleted, the Item is moved to the Recycle bin database and is deleted from the Master database. These changes are also reflected in the portlet (the list is refreshed). Afterwards, you can restore the Item from the Recycle bin, and if it was deleted in the locked state, it will appear in the Locked Items list again.
When you check an Item in or out via the Content Editor in a usual way, the locked Items list is refreshed as well, keeping you up to date with your locked Items. The Architectural Notes section describes how this functionality is implemented.

4. Architectural Notes

The first time the portlet is loaded, it scans the whole content tree starting from the /sitecore/content Item. It examines the __Lock field, which contains the information about the owner of the lock, and places a pointer to each Item locked by the current User in its cache.

The cache is implemented as a hash table: the key of the record is the User’s ID, the value is the list of Items locked by this User. Thus, each User has a separate context cache. The cache object is static, which means that the information is stored for the whole period of your work in the Sitecore Client.

The portlet includes handlers which listen to events which modify an Item’s lock state. The handlers update the cache accordingly. This mean that the portlet does not to scan the content tree each time it is refreshed, it automatically updates when the “lock” state of an Item is modified.

When a new Item is created in the content tree, its initial English version is locked by the creating User by default. The portlet includes an item:saved event handler which scans all the versions of the created Item and adds the locked ones to the User’s cache. The portlet listens for the item:saved event, and not the item:added event, because at the time that the item:added event is raised the __Lock field has not yet been set.

When a locked Item is deleted, it must be removed from the cache of locked Items, because it is considered unlocked in this case. Thus, the appropriate handler is assigned to the item:deleting event, which removes the Item from cache, and refreshes the overall list. The portlet listens for item:deleting rather than item:deleted, because after the item:deleted event, the Item itself doesn’t exist in the master database.

Finally, the portlet must modify the cache when an Item is checked out or in. For this purpose, we create a new processor class and plug it into the <dispatch> pipeline. This class contains two methods that handle appropriate messages (item:checkin / item:checkout). Items that have been ‘checked in’ are removed from the cache, while Items that have been ‘checked out’ are added to the cache.