Command Panel: Adding commands manually

Command Panel: Adding commands manually

Posted on March 24, 2009 0 Comments

The content you're reading is getting on in years
This post is on the older side and its content may be out of date.
Be sure to visit our blogs homepage for our latest news, updates and information.

[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:
 
/// <summary> 
/// Initializes a new instance of the <see cref="ContactsControlPanel"/> class. 
/// </summary> 
public ContactsControlPanel() : base(false
 
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:
/// <summary> 
/// Loads configured views. 
/// </summary> 
protected override void CreateViews() 
            AddView<ContactsItemsView>(null"AllContacts""CommandPanel_ContactsItems_Desc""all", Messages.ResourceManager); 
            AddView<PermissionsView<ContactsControlPanel>>(null"Permissions""CommandPanel_Permissions_Desc""globalPerm", Messages.ResourceManager); 
 
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:

        /// <summary> 
        /// When overridden this method returns a list of standard Command Panels. 
        /// </summary> 
        /// <param name="viewMode">The view mode.</param> 
        /// <param name="commandsInfo">A list of <see cref="CommandItem">ControlPanel.CommandItem</see> objects.</param> 
        /// <param name="list">A list of Command Panels for this Control Panel. This list can be used to add and remove Command Panels.</param> 
        /// <remarks> 
        /// This method will automatically create Command Panels 
        /// based on the information passed with CommandItem classes. 
        /// One command panel will be created per each 
        /// unique panel name specified in the collection of command items. 
        /// Command panels will appear in the order they were created. 
        /// </remarks> 
        protected override void CreateStandardCommandPanels(string viewMode, List<CommandItem> commandsInfo, List<Telerik.Web.ICommandPanel> list) 
        { 
            switch (viewMode) 
            { 
                case "BlogsView"
                case "BlogsPermissionsView"
                    Cms.Web.UI.Backend.CommandPanel blogsCommandPanel = new Cms.Web.UI.Backend.CommandPanel(); 
                    blogsCommandPanel.Title = Messages.ExploreBlogsMogule; 
                    blogsCommandPanel.AddCommand("BlogsView", ControlUtils.SliceRoute(GetControlPanelRoute(), this.Name), null, Messages.AllBlogs, Messages.AllBlogsDescription, "all"); 
                    blogsCommandPanel.AddCommand("BlogsPermissionsView", ControlUtils.SliceRoute(GetControlPanelRoute(), this.Name), null, Messages.Permissions, Messages.PermissionsDescription, "globalPerm"); 
                    list.Add(blogsCommandPanel); 
                    break
                default
                    // helper command panel 
                    Cms.Web.UI.Backend.CommandPanel helperCommandPanel = new Cms.Web.UI.Backend.CommandPanel(); 
                    helperCommandPanel.AddCommand("BlogsView""BlogsControlPanel"nullnull, Messages.AllBlogs, null"backWrapp"); 
                    list.Add(helperCommandPanel); 
                    // posts command panel 
                    Cms.Web.UI.Backend.CommandPanel postsCommandPanel = new Cms.Web.UI.Backend.CommandPanel(); 
                    postsCommandPanel.Title = Messages.ExploreThisBlog; 
                    postsCommandPanel.AddCommand("PostsView", ControlUtils.SliceRoute(GetControlPanelRoute(), this.Name), nullthis.ParentId.ToString(), null, Messages.Posts, null"all"); 
                    if(this.Manager.Provider.AllowComments) 
                        postsCommandPanel.AddCommand("BlogCommentsView", ControlUtils.SliceRoute(GetControlPanelRoute(), this.Name), nullthis.ParentId.ToString(), null, Messages.Comments, null"all"); 
                    postsCommandPanel.AddCommand("BlogCategoriesView", ControlUtils.SliceRoute(GetControlPanelRoute(), this.Name), nullthis.ParentId.ToString(), null, Messages.Categories, null"all"); 
                    postsCommandPanel.AddCommand("BlogTagsView", ControlUtils.SliceRoute(GetControlPanelRoute(), this.Name), nullthis.ParentId.ToString(), null, Messages.Tags, null"all"); 
                    list.Add(postsCommandPanel); 
                    // blog settings command panel 
                    Cms.Web.UI.Backend.CommandPanel blogSettingsPanel = new Cms.Web.UI.Backend.CommandPanel(); 
                    blogSettingsPanel.Title = Messages.BlogSettingsTitle; 
                    blogSettingsPanel.AddCommand("BlogsSettingsView""BlogsControlPanel.BlogSettingsView"nullthis.ParentId.ToString(), Messages.BlogSettingsTitle, null"settings"); 
                    list.Add(blogSettingsPanel); 
                    break
            } 
        } 
 
        private List<string> GetControlPanelRoute() 
        { 
            List<string> controlPanelRoute = ControlUtils.ParseRoute(ControlUtils.GetCurrentRoute()); 
            if(controlPanelRoute.Count == 0) 
                controlPanelRoute.Add(this.Name); 
            return controlPanelRoute; 
        } 
 
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:

Cms.Web.UI.Backend.CommandPanel blogsCommandPanel = new Cms.Web.UI.Backend.CommandPanel(); 
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:

postsCommandPanel.AddCommand("BlogCategoriesView", ControlUtils.SliceRoute(GetControlPanelRoute(), this.Name), nullthis.ParentId.ToString(), null, Messages.Categories, null"all"); 
which is calling the following method of the CommandPanel class:

public virtual void AddCommand(string commandName, List<string> commandRoute, string parameter, string parentId, string commandArgs, string title, string description, string cssClass) 
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.
progress-logo

The Progress Team

View all posts from The Progress Team on the Progress blog. Connect with us about all things application development and deployment, data integration and digital business.

Comments

Comments are disabled in preview mode.
Topics

Sitefinity Training and Certification Now Available.

Let our experts teach you how to use Sitefinity's best-in-class features to deliver compelling digital experiences.

Learn More
Latest Stories
in Your Inbox

Subscribe to get all the news, info and tutorials you need to build better business apps and sites

Loading animation