Insert options

Abstract

Overview of insert options and how they are used.

Effective insert options control the types of items users can insert under existing items. Sitecore determines effective insert options for an item from the assigned insert options. You can programmatically manipulate effective insert options for an individual item or for all items based on a data template by assigning insert rules to the item or the standard values of the data template. You can manipulate effective insert options for all items by removing, replacing, or adding processors in the insert options pipeline.

Sitecore administrators and developers configure insert options to:

  • Help users create appropriate types of items under existing items. This increases usability by limiting lists to relevant options rather than presenting a list of every type of data the user could possibly insert.

  • Restrict the types of items users can create under existing items. This helps you enforce an information architecture, which improves consistency.

  • Allow different users to create different types of items under existing items.

  • Help users create a number of items with a single action in the user interface.

  • Create items programmatically, for example, by invoking a wizard. It also lets you write presentation components that can predict the types of data available in the system.

The following table describes the insert options available.

Insert options

Description

Effective Insert Options

Effective insert options include the list of data templates, branch templates, and command templates that a user can use to insert new items under the selected item. For more information, see Assigned insert options versus effective insert options.

Assigned Insert Options

You can assign insert options in the standard values of a data template. Assigned insert options can include data templates, branch templates, command templates, and insert rules. For more information, see Assigned insert options versus effective insert options.

Important

Whenever possible, assign insert options in standard values instead of assigning insert options to individual items.

Insert Rules

Administrators can assign insert rules in insert options to dynamically redefine effective insert options for the user at runtime. Developers can implement custom insert rules for administrators to select.

Insert Options rules

Administrators can implement insert options rules to define effective insert options, providing user interfaces to select rule parameters. Unlike insert rules that apply to specific items, insert options rules apply to all items, though conditions typically limit their application. .

The uiGetMasters pipeline

Sitecore constructs the list of effective insert options by invoking the uiGetMasters pipeline defined in the web.config file. The uiGetMasters pipeline defines the list of data templates, command templates, and branch templates available to the user for inserting new items.

The uiGetMasters pipeline uses the following process to determine effective insert options for an item:

  1. Add each of the item's assigned insert options to which the context user has read access to the list of effective insert options.

  2. Apply any insert rules associated with the item to the list of effective insert options.

  3. Apply insert options rules to the list of effective insert options.

  4. Remove any items to which the context user does not have the insert:show access right.

Developers can add custom processors to the uiGetMasters pipeline containing logic to determine effective insert options for the user at runtime. Unlike insert rules, which apply only to the items that reference those rules, the uiGetMasters pipeline applies to all items.