+1-888-365-2779
Try Now
More in this section
Categories
Bloggers
Blogs RSS feed

Control Panel: Automatic Command Generation

by Ivan Osmak

[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.

 

using Telerik.Cms.Web.UI.Backend; 
using ViewSamples; 
 
/// <summary> 
/// ContactsControlPanel - root view of the Contacts module 
/// </summary> 
public class ContactsControlPanel : ControlPanel<ContactsControlPanel> 
    public ContactsControlPanel() 
        : base(false
    { 
 
    } 
 
    /// <summary> 
    /// We add the views to the control panel. The two views we are adding are so called "container" views, since 
    /// they do not have user interface and display their default child view. 
    /// </summary> 
    protected override void CreateViews() 
    { 
        AddView<ContactsView>("Contacts""Contacts""From here you can manage all the contacts.""all"null); 
        AddView<DepartmentsView>("Departments""Departments""From here you can manage all the departments""all"null); 
        AddView<MyProjectView<ContactsControlPanel>>("MyView""My View""My View description""all"null); 
    } 
 
  If we decide to use automatic command generation our constructor could look like this:

public ContactsControlPanel() 
        : base(true
 
 

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

 

public ContactsControlPanel() 
 
 
 

 

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:
 
/// <summary> 
    /// We add the views to the control panel. The two views we are adding are so called "container" views, since 
    /// they do not have user interface and display their default child view. 
    /// </summary> 
    protected override void CreateViews() 
    { 
        AddView<ContactsView>("Contacts""Contacts""From here you can manage all the contacts.""all"null); 
        AddView<DepartmentsView>( "Departments""Departments""From here you can manage all the departments""all"null); 
        AddView<MyProjectView<ContactsControlPanel>>("MyView""My View""My View description""all"null); 
    } 
 

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.

 

public void AddView<TView>( string viewName, string title, string description, string viewCommandCssClass, ResourceManager resources) where TView : Control, new(); 

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:
 
protected override void CreateViews() 
        { 
            AddView<NewsItemsView>( null"CommandPanel_NewsItems_Title""CommandPanel_NewsItems_Desc""all", Messages.ResourceManager); 
            AddView<NewsCategoriesView>(null"Categories""CommandPanel_Categories_Desc""cat", Messages.ResourceManager); 
            AddView<NewsTagsView>(null"Tags""CommandPanel_Tags_Desc""tags", Messages.ResourceManager); 
            if(this.Manager.Provider.AllowComments) 
                AddView<NewsCommentsView>(null"Comments""CommentsDescription""comments", Messages.ResourceManager); 
            AddView<NewsPermissionsView>(null"Permissions""CommandPanel_Permissions_Desc""globalPerm", Messages.ResourceManager); 
        } 
 

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.


3 comments

Leave a comment
  1. Romi Feb 26, 2009
    Hi Team,
    Could you sugest for next version to add some Eventhandlers as optional to addView methods or create other class that allow to add. Actually is my big problem because this new architecture works with many hyperlinks.  
  2. Ivan Feb 26, 2009
    Hi Romi,

    we do have some plans to enhance the commands, but if you read the architecture overview (http://blogs.sitefinity.com/Ivan/Posts/09-02-19/Sitefinity_3_6_new_backend_architecture_-_Architectural_overview.aspx) again you will see why did we opt for this approach. Introducing the event handlers and modes would defy the whole purpose of the new architecture and we would be back at the square one - tightly coupled modules which are hard to extend or derive from.

    Please, let me know in more detail what exactly is the problem with having "many hyperlinks" and I'll see if we can suggest some solution.
  3. Ivan Feb 26, 2009
    Romi,

    one more thing I've forgot to mention - in the articles that I'll write soon:
    - Creating command panel from User Control and
    - Creating command panel from Custom Control
    I'll demonstrate how you can create completely custom command panels and don't have to rely on any of our built in functionality.

    However, if you decide to take this approach, you should have a really good reason for doing so and have a clear plan on how will you make your modules maintainable and extensible.

    Leave a comment