LibrarySites.Banner

All About Insert Options in the Sitecore ASP.NET CMS

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.

Introduction

Insert options:

  • Increase CMS usability by limiting lists to relevant options rather than presenting a list of every type of data the user could possibly insert
  • Help you enforce an information architecture, which increases consistency
  • Let you write presentation components that can predict the types of data available on the system

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.

Types of Insert Options

There are three types of items that you can configure as insert options:

  • Data Templates
  • Branch Templates
  • Command Templates

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.

Defining Effective Insert Options

You can use the following approaches to define the insert options available to CMS users:

  • Assign insert options to items and data templates
  • Implement and select insert rules
  • Configure insert options rules
  • Implement uiGetMasters pipeline processors

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:

  1. Select the individual item or the standard values definition item for a data template for which to assign insert options.
  2. Select the Configure tab, and then click Assign in the Insert Options group. The Insert Options dialog appears.

    Assign Insert Options

  3. Add data templates, branch templates, and command templates from the tree on the left to the list on the right or remove insert options from the list on the right.
  4. Click OK. The Insert Options dialog disappears and you return to 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:

  1. Select the individual item or the standard values definition item for a data template for which to assign insert options.
  2. Select the Configure tab, and then click Assign in the Insert Options group. The Insert Options dialog appears.
  3. Click Insert Rules under Options at the left (by default, no insert rules are available for selection).

    Assign Insert Rules

  4. Add insert rules from the tree on the left to the list on the right or remove insert rules from the list on the right.
  5. Click OK. The Insert Options dialog disappears and you return to 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:

  1. Create a class that derives from the Sitecore.Data.Masters.InsertRule abstract base class.
  2. Implement the Expand() method to complete the contract defined by that base class by manipulating the list of insert options defined in the argument passed to that method.
  3. Under the /Sitecore/System/Settings/Insert Rules item, create an insert rule definition item using the /System/Branches/Insert Rule data template.

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.

  • Insert rules apply to individual items and types of items, which can have a minor performance advantage over insert options rules. Insert options rules run for all items.
  • CMS users with appropriate access rights can use the Insert Options dialog to apply insert rules to individual items.
  • Insert options rules capitalize on the existing rules engine infrastructure, meaning you can use a variety of pre-existing rule conditions to determine effective insert options rather than coding logic as insert rules require.
  • By default, insert options rules do not enable you to remove effective insert options; they only enable you to add effective insert options. To implement an action that enables you to use insert options rules to remove effective insert options, see the blog post Implement a Rule Action to Remove an Insert Option in the Sitecore ASP.NET CMS.

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:

  • GetItemMasters: Retrieves insert options assigned to the selected item
  • GetInsertRules: Applies insert options assigned to the selected item
  • RunRules: Invokes the rules engine to apply insert options rules
  • CheckSecurity: Removes insert options for which the context user does not have access rights

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:

  1. Select the data template in the Content Editor.
  2. Select the Security tab, and then click Assign in the Security group. The Security Settings dialog appears.

    Security Settings dialog

  3. Click Add. The Select an Account dialog appears.

    Select an Account dialog

  4. Select the user or role, and then click OK. The Select an Account dialog disappears and you return to the Security Settings dialog.
  5. Select the X next to Item for the Show in Insert access right, and then click OK.

    Security Settings dialog after denying insert

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.