Command Panel: Adding commands manually

[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 seen how we can automatically generate commands based on the Views that we add to the Control Panel class. In many scenarios, this feature will fit perfectly with our requirements and it will save us some time.

 

There are, however, cases when we need to have a better control over the command panels and the commands inside of them. Let us take a look at the built-in Blogs module for an example of such scenario.

On the first image we see the blogs module and its command panels when the module is in “All blogs” mode. On the second image we see the different command panels that are visible when we are in a “Single blog mode” or in other words, when we enter one of the blogs.

 

Obviously, the command panels change based on some condition (displaying all blogs or single blog). This is achieved by adding command panels and commands manually and in this article we are going to explore this approach.

 

Standard command panels

There are four different ways in which you can create command panels:

• Automatically generate commands in the default command panel
• Manually create command panels and commands - standard command panels
• Create command panels from User Controls
• Create command panels from Composite (Custom) Controls

You are also free to combine these approaches. For example, you could create several commands automatically and then also load additional command panel as a User Control. In this article we are going to explore the second approach - manually creating standard command panels.

 

First thing we need to do is ensure that commands are not being generated automatically.

 

*** BEGIN NOTE ***

 

By default, base CommandPanel and ProviderCommandPanel classes will generate commands automatically.

 

*** END NOTE ***

 

In order to turn off the automatic command generation we have to construct the base ControlPanel or ProviderControlPanel class with the false value sent as the autoGenerateViewCommand argument. For example, in our sample contacts module we have done so in following manner:
  Now, that we have turned off the automatic command generation, no commands will be created from the Views we add in the CreateViews method. So the following code will only add the Views to the View hierarchy, but will not create the commands for those Views: In order to create standard command panels, we will need to override CreateStandardCommandPanels method in our Control Panel class. Following example demonstrates the use of this approach in already mentioned Blogs module:

The first interesting thing about this method are the parameters we are receiving:

• string viewMode
  This is the name of the currently loaded view.
• List<CommandItem> commandsInfo
  Represents the list of all commands that currently exist in all command panels of our control panel (remember that control panel can hold one or more command panels)
• List<Telerik.Web.ICommandPanel> list
  Represents the list of all command panels of our control panel

So the very simple explanation of the CreateStandardCommandPanels method in the example above would go like this:

 

If the current view is BlogsView or BlogsPermissionsView create a command panel for the all blogs mode and add several commands to it - at the end add the newly created command panel to the list of all command panels which we have received through the list parameter. On the other hand, if the current view is any other view except BlogsView or BlogsPermissionsView create three different command panels, add some commands to them and finally add all three newly created command panels to the list of all command panels we have received through the list parameter.

Creating a standard command panel

Before we explain the details of the implementation in the sample code we’ve seen, we should understand following concept:

• Control panel can have one or more command panels
• Command panel can have one or more commands
• Control panel cannot have commands, only command panels which contain commands

Having this understanding, we know that before we can add commands, we need to create a command panel. One can create command panel in following manner:

Now, that we have created a new instance of the CommandPanel class, we can add any number of commands to its CommandCollection. While we can create a new CommandItem and add it to the collection, a simpler way is to call one of the AddCommand overloaded methods of the CommandPanel class.

 

The signatures of the AddCommand methods are rather simple as the following example suggests:

which is calling the following method of the CommandPanel class:

Let us briefly describe the parameters of this method:

• string commandName
  Name of the command which should correspond to the name of the View that command will open. So for example, if we are making command for the “ProductNewView”, the name of the Command should be “ProductNewView”.
• List<string> commandRoute
  The correct route to the View - meaning that you should pass a collection of the View names in a proper order (hierarchy) to the View you wish to open with this command. Notice that we are using a helper method ControlUtils.SliceRoute here, which you can use in your implementations as well.
• string parameter
  Any parameter you may wish to send to the View command will open.
• string parentId
  Id of the parent which you may wish to send to the View command will open.
• string commandArgs
  This parameter is not implemented in Sitefinity 3.6, but will be used in Sitefinity 4.0
• string title
  Title of the command that will appear in the command panel
• string description
  Description of the command that will appear in the command panel
• string cssClass
  Css class of the command that will be used to style the command

Conclusion

We have seen a different approach for adding command panels and commands, which does involve a bit more effort, but also offers us greater control over commands that automatic command generation. In the next two articles we are going to cover even more flexible approaches, where we are able to completely define the look and feel of command panels in so much that we will design them through user controls or composite controls.