Sitecore Best Practice #8 - Put your toolbar in context

28 June 2011
Adam Najmanowicz
Frink_Cognifide_2016_HeaderImages_0117
This best practice helps developers put only relevant buttons on the context toolbar, thereby limiting the editor's confusion when editing modules.

One thing we got wrong in our first iteration was to put an Edit Frame over pretty much everything. While this is initially tempting – it gives the illusion of everything being editable – it is, still a bad practice if you do not use the Sitecore 6.4 Page Editor commands properly.

Unnecessary edit frame

Basically, when our developers learned about Edit Frame, we had the Edit Frame around just about every module, meaning that the authors needed to click the North-West arrow every time to edit the module..

This best practice describes why that approach is no longer necessary .

What is the Sitecore Best Practice 8 about?

Relevancy. When you click on a module, Sitecore displays the toolbar with buttons relevant to the current context. The minimal set of buttons for module that contains external items should be:
  • edit module properties (e.g. select the item the module displays)
  • edit the displayed item
  • publish the item within the module

Why should I do it?

Authors do not necessarily understand that the item and the rendered module are different. We need to present them with buttons that clearly indicate that editing the item linked in a module is not the same as editing the page it is displayed on (e.g. a Person item being edited in the "Contact us" module). If the author is presented with a set of buttons that clearly distinguishes between editing module properties and editing selected item content within it, in a single toolbar, they are likely to understand the metaphor clearly. Consequently, you can enable the in-place editing and avoid making them go elsewhere to publish the item.

Demo scenario

for the in-place editing, we have no need for edit frame:

Item editing

If module displays data from external item, e.g. it could have a button for publishing external item changes. Potentially we can add buttons for chaging the item orders or adding new items to the data source if needed.

Proper module support

  Adding a new module to a page should present a datasource selection dialog if a module is indeed just displaying an item from a data source.

 Associated Content Selection

How do I implement it in my project?

You will find a sample actions needed to ascertain how to add a button to your module based on your custom functionality.

One-time project configuration

   Adding a Publish button: 1. In App_Config/Commands.config, add the following line:
<command name="webedit:publishrelateditem"
         type="Cognifide.SiteCore.Framework.Facilities.PublishRelatedItemCommand,
               Cognifide.SiteCore.Framework" />
2. Open database core in Content Editor, navigate to node /sitecore/content/Applications/WebEdit/Custom Experience Buttons. Add a new button using template /sitecore/templates/System/WebEdit/WebEdit Button. Under Data heading, set Header to "Publish", Icon to "network/32x32/earth2.png", Click to "webedit:publishrelateditem" and Tooltip to "Publish Related Item". Publish your changes.

Button configuration

Programmer guidelines

1. Use Datasource whenever you create a module/control that displays data from external item. BaseUserControl will automatically setup Datasource on any Sitecore controls that you use.
2. Add a Publish button to you template if it uses Datasource to refer to an external item. Those settings are available under Editor Options heading when you open you Template in Content Editor.

 

 3. Use the FieldControl classes. There are several available:
  • <sc:Image>
  • <sc:Link>
  • <sc:Text>
  • <sc:Date>
  • <sc:FieldFieldRenderer> The last one, FieldRenderer, automatically adjusts to the type of the field it is pointing to. Each of those controls require setting the Field property and either DataSource (accepts item path) or Item (accepts and Sitecore API Item). By default, controls derived from BaseUserControl will setup DataSource automatically.

Thanks to Leszek Ciesielski for his help with the Sitecore Best Practice #8.