The "uiGetMasters" processor, "insert rule" or "insert options rule" thread on the Sitecore Developer Network (SDN) forums prompted me to write this blog post about insert options in the Sitecore ASP.NET web Content Management System (CMS). Insert options control the types of items that CMS users can insert beneath existing items. For more information about insert options, including instructions to implement and configure insert options, see The Sitecore Data Definition Reference and The Sitecore Data Definition Cookbook. For more in this series of deep dives into Sitecore technologies, see the blog post All About the Sitecore ASP.NET CMS.
Versions of Sitecore CMS prior to 6.0 included a construct named masters. Sitecore CMS 6.0 introduced branch templates, described further in this blog post, and standard values, which provide values for fields until a user overrides those values. For more information about standard values, see The Sitecore Data Definition Reference. These newer features made masters obsolete. Where it appears in Sitecore APIs, configuration, or otherwise, the term masters in general refers to insert options.
There are three types of items that you can configure as insert options:
Of these, data templates are the most common. CMS users can use insert options to create a single item based on a data template.
Branch templates enable CMS users to create a number of items in a predefined structure. The branch template definition defines that structure. Branch template definitions can contain values for any fields in the items, which Sitecore copies to items created from those branch templates. When creating items from a branch template, Sitecore replaces the token $name in the names of the items in the branch template definition with the name entered by the user in response to the prompt Sitecore displays whenever a user chooses to use an insert option. Sitecore replaces additional tokens in those fields and in the standard values for the data templates as specified in The Sitecore Data Definition Cookbook.
Command templates initiate commands to create one or more items programmatically. You can use a command template to invoke a wizard that gathers information from the user before creating items. For more information about wizards, see the blog post Run Scheduled Agents Interactively in the Sitecore ASP.NET CMS.
You can use the following approaches to define the insert options available to CMS users:
You can assign insert options declaratively by choosing the data templates, branch templates, and command templates that CMS users can invoke. While you can assign insert options to individual items, to minimize administration and maximize consistency, you should assign insert options in the standard values for data templates to control insert options for all items based on those templates. To assign insert options in the Content Editor:
To reset insert options for an individual item to those defined by the standard values of the data template associated with that item, select the Configure tab, and then click Reset in the Insert Options group.
You can use insert rules to add or remove insert options from the list assigned to an item or the standard values of its data template. To assign insert rules in the Content Editor:
The Sitecore Data Definition Cookbook provides detailed instructions to define insert rules and provides an example. In short, to make an additional insert rule available in the Insert Options dialog:
Insert options rules use the rules engine to add effective insert options under specific conditions. For more information about the rules engine, see The Sitecore Rules Engine Cookbook.
Insert options rules differ from insert rules in a few possible ways that could make them advantageous or disadvantageous depending on your requirements.
Sitecore (specifically, the GetMasters() method in the Sitecore.Data.Masters.Masters static class) invokes the uiGetMasters pipeline defined in the Web.config file to determine effective insert options at runtime. For more information about pipelines, see the blog post All About Pipelines in the Sitecore ASP.NET CMS. To control how Sitecore determines insert options, you can add, remove, and replace processors in the uiGetMasters pipeline. Processors in the uiGetMasters pipeline accept an argument based on the Sitecore.Pipelines.GetMasters.GetMastersArgs class. As of Sitecore CMS 6.5 rev. 111230, the uiGetMasters pipeline contains the following processors:
Sitecore invokes these processors in the order in which they appear in this list based on their order in the Web.config file.
In most cases, you can use insert rules, insert options rules, or a uiGetMasters pipeline processor to achieve the same manipulation of insert options. A uiGetMasters pipeline processor may be most appropriate where the logic for determining effective insert options applies to all items, if the configuration of that logic is relatively stable, and if you do not need a browser-based user interface to configure that logic.
The CheckSecurity processor evaluates the insert:show access right (labeled Show in Insert and represented by the InsertShow static property of the Sitecore.Security.AccessControl.AccessRight class) to determine whether each insert option should appear for the context user. By default, a user that has the item:create access right (labeled Create and represented by the ItemCreate static property of the Sitecore.Security.AccessControl.AccessRight class) for an item can use any insert option available for that item. To control which users can use each insert option, you can restrict the item:show access right in the definition item for the data template, branch template, or command template activated by that insert option. For example, to prevent members of a specific role from inserting items using a specific data template:
The Insert from Template command appears with insert options for users with appropriate access rights, but is not technically an insert option. For instructions to control access to this command, see the blog post Control Access to the Insert from Template Command in the Sitecore ASP.NET CMS.