Control Panel: Automatic Command Generation

[This post is part of the developer's manual preview published on this blog. You can find temporary TOC here.]

 

In the previous article we have touched on the benefits of deriving our Control Panel class from the base Telerik.Cms.Web.UI.Backend.ControlPanel class. The first built-in feature we are going to examine is the automatic command generation.

 

What are commands?

In the new Sitefinity backend architecture, commands are hyperlinks with URLs that represent an instruction to the module that current View should be changed. For example, if Generic Content module displays a list of all content items, hyperlink which would make Generic Content module to display the View for creating a new content item would be a command.

 

It is a common scenario in module development that children views of the root View (Control Panel) should have corresponding commands always present in the module. The first level Views generally represent different tasks that can be accomplished with the module and therefore user should be able to navigate among them regardless of the currently displayed View.

 

Let us take a look how this approach works in practice, by examining the Generic Content module.

 

As we can see from the figure above, we have four commands available and they will stay available regardless if we are creating new content item or setting permissions for the new role.

 

It was this common pattern that has encouraged us to provide a simple and effortless way to automatically generate automatic commands for the first level children of the module.

 

Enabling and disabling automatic command generation

Before we dig into the specifics, we should cover the process of enabling or disabling Control Panel automatic command generation.

 

By default, Control Panel will generate commands automatically for you. An overloaded constructor is available, however, which allows you to turn this feature off when instantiating control panel. In the following example, the ficticious ContactsControlPanel class is disabling automatic command generation by passing the false as an argument to its base constructor.

 

  If we decide to use automatic command generation our constructor could look like this:

Or even better, we take advantage of the ControlPanel’s default behavior:

 

 

 

How are the commands generated?

The commands for the root view are generated from its child views collection. If we are to carefully to examine the various overloads of the AddView method, we can notice that there are often arguments that have very little to do with the View itself. So, let us take a look at the following sample:
 

You can take a look at the following screenshot to see how would Sitefinity automatically generate commands based on these Views.

 

If we take a look at the actual signature of the AddView method that we were calling, the principle becomes crystal clear.

 

By comparing the previous sample and resulting screenshot, we can see following:

• "title" argument will be used to declare the HyperLink text
• "description" argument will be used to declare the short description beneath the HyperLink
• "viewCommandCssClass" argument will be used to declare the css class of the LI element representing the given command in the list of commands

 

*** NOTE ***

 

Sitefinity will also automatically set CssClass of the command representing current mode to “sfSel”, which is styled in the current theme, but of course, you are free to modify its declaration as you see fit.

 

*** END NOTE ***

 

Localization of automatically generated commands

The last parameter of the previously examined AddView<T> method strongly suggests the possibility of localization. Title and Description localization of automatically generated commands is indeed possible, so let us examine how it works.

 

We have seen in our previous sample that title and description arguments were taken literally and displayed as typed. The reason for this lays in the fact that we have provided null for the last argument, namely ResourcesManager. If you provide an actual ResourceManager object for this argument, Sitefinity will this recognize as your desire to have localized commands and therefore will:

 

Treat title and description arguments as resource file keys and not literal text to be displayed.

 

Let us take a closer look at this approach that comes from our built-in News module:
 

News module is using automatic command generation, yet obviously the HyperLinks in the command panel do not state “CommandPanel_NewsItems_Title” or similar nonsense. These strings are in this sample treated as keys of the localization resource file, since we have provided the instance of ResourceManager as the last argument in each of the calls to the AddView<T> method.