Command Buttons

From Sense/Net Wiki
Jump to: navigation, search
  •  
  •  
  •  
  •  
  • 100%
  • 6.0
  • Enterprise
  • Community
  • Planned

Overview

The Command Buttons control is a user control that displays buttons that control the saving and versioning of Content presented with Content Views.

Command Buttons control

Details

Command Buttons appear at the bottom of Generic Content Views. By default it shows some common buttons like Save Draft and Done Editing depending on the state of the content that is edited/created. For example if a new content is created the Done Editing and Cancel buttons are visible, when a non-versioned content is edited the Save Draft, Done Editing and Cancel buttons are shown.

Buttons visible by default

By default only two buttons are visible: Save and Cancel. The Save button is actually two different buttons visible in two different states:

  • if the content is checked out to the user the button with ID Save is shown.
  • if the content is checked in the button with ID CheckoutSaveCheckin is visible.

This way it is customize the button captions in different states. In the default installation however the captions of these buttons are the same and they say Save in English. The Command Buttons control is able to handle some other buttons if defined in the layout - see Buttons defined by design section.

Buttons defined by design

Different buttons are visible in different content states. Every content can be in one of the following states depending on the content's versioning and approving modes:

  • A (Approved): the content is published (and approved)
  • L (Locked): the content is checked out to a user, others cannot se last modifications, only last approved or last draft versions
  • D (Draft): the content is not checked out to anyone but its not yet published - it's a draft version (state available only in major & minor versioning)
  • P (Pending): the content is ready to be published but is not yet approved (state available only when approvable)
  • R (Rejected): the content was marked ready to be published but has been rejected (state available only when approvable)

The following buttons are available:

  • Checkout & Save ("Save Draft")
    • visible in the following content states: A,D,P,R - when Checkout action is allowed
    • performs a Checkout action on the content
    • content gets into state L
  • Checkout & Save & Checkin ("Done Editing")
    • visible in the following content states: A - when Save action is allowed
    • performs a Save action on the content
    • content gets into state A or D
  • Save ("Save Draft")
    • visible in the following content states: L - when Save action is allowed
    • performs a Save action on the content
    • content gets into state L
  • Save & Checkin ("Done Editing")
    • visible in the following content states: L - when Checkin action is allowed
    • performs a Checkin action on the content
    • content gets into state '
  • Publish ("Publish")
    • visible in the following content states: D - when Publish action is allowed
    • performs a Publish action on the content
    • content gets into state A or P
  • Cancel ("Cancel")
    • visible in all states
    • performs no action on the content
    • content remains in its previous state

Content View and Command Buttons

You don't have to configure anything when using the Command Buttons in a Content View: just place the following markup in the Content View and the Command Buttons control will use the Content View's Content for operations when any button is clicked:

<%@ Control Language="C#" AutoEventWireup="true" Inherits="SenseNet.Portal.UI.SingleContentView" %>
 
<div class="sn-panel sn-buttons">
  <sn:CommandButtons ID="CommandButtons1" runat="server" />
</div>

When any button is clicked, the Command Buttons control calls a Content View event, CommandButtonsAction with cancellable event arguments, that enable developers to customize the executed action when a button is clicked (see #Example/Tutorials section for details).

Properties

  • LayoutControlPath: (optional) the control containing the buttons' layout. By default it is /Root/System/SystemPlugins/Controls/CommandButtons.ascx.
  • HideButtons: (optional) the list of button IDs to be hidden separated by space or comma or semicolon. These buttons will never be rendered.
  • CheckInControlPath: (optional) the control containing the layour for checkin comments. By default it is /Root/Global/contentviews/CheckInDialog.ascx.
  • CheckoutSaveCaption: (optional) caption for the Checkout & Save button.
  • SaveCaption: (optional) caption for the Save button.
  • SaveCheckinCaption: (optional) caption for the Save & Checkin button.
  • CheckoutSaveCheckinCaption: caption for the Checkout & Save & Checkin button.
  • PublishCaption: caption for the Publish button.
  • CancelCaption: caption for the Cancel button.

You can use string resources for the captions as well, see examples.

Example/Tutorials

Displaying all buttons

By default only Save and Cancel buttons are displayed. To display all the buttons that were implemented by desing use the following layout (you can find the default layout at /Root/System/SystemPlugins/Controls/CommandButtons.ascx - but you can also create a custom layout, see other examples):

<%@ Control Language="C#" AutoEventWireup="true" Inherits="System.Web.UI.UserControl" %>
 
<!-- visible in states: A,D,P,R -->
<asp:Button CssClass="sn-button sn-submit" ID="CheckoutSave" runat="server"
    Text="<%$ Resources:Controls,SaveDraft %>" 
    ToolTip="<%$ Resources:Controls,CheckoutAndSave %>" />
 
<!-- visible in states: L -->
<asp:Button CssClass="sn-button sn-submit" ID="Save" runat="server"
    Text="<%$ Resources:Controls,SaveDraft %>" 
    ToolTip="<%$ Resources:Controls,Save %>" />
 
<!-- visible in states: A -->
<asp:Button CssClass="sn-button sn-submit" ID="CheckoutSaveCheckin" runat="server"
    Text="<%$ Resources:Controls,DoneEditing %>" 
    ToolTip="<%$ Resources:Controls,CheckoutAndSaveAndCheckin %>" />
 
<!-- visible in states: L -->
<asp:Button CssClass="sn-button sn-submit" ID="SaveCheckin" runat="server"
    Text="<%$ Resources:Controls,DoneEditing %>" 
    ToolTip="<%$ Resources:Controls,SaveAndCheckin %>" />
 
<!-- visible in states: D -->
<asp:Button CssClass="sn-button sn-submit" ID="Publish" runat="server"
    Text="<%$ Resources:Controls,Publish %>" 
    ToolTip="<%$ Resources:Controls,SaveAndPublish %>" />
 
<!-- visible in states: A,L,D,P,R -->
<asp:Button CssClass="sn-button sn-submit" ID="Cancel" runat="server"
    Text="<%$ Resources:Controls,Cancel %>"  />

Changing button captions

You can override the default button captions using the corresponding caption property. Plain text values and string resources can also be used:

  <sn:CommandButtons ID="CommandButtons1" runat="server" SaveCaption="<%$ Resources:ExpenseClaim, NewClaim%>" />

Customizing the look of buttons

The declaration of the CommandButtons control in the default contentviews looks like this:

  <sn:CommandButtons ID="CommandButtons1" runat="server" LayoutControlPath="/Root/System/SystemPlugins/Controls/CommandButtons.ascx" />

You may change LayoutControlPath to your own CommandButton control. Use the control IDs defined in the original ascx to keep original functioning unchanged. Besides that you may change any attributes of the control, or even change the button control to any kind of control implementing the IButtonControl interface (ie a LinkButton):

<asp:LinkButton ID="Cancel" runat="server"
    Text="Undo my changes"  />

Defining your own ascx allows you to change the whole layout of the default command buttons, for example:

Original layout ReferenceWikiCommandButtons.png
Custom layout CommandButtons custom layout.PNG

If you don't want a button to be visible in any scenario, simply erase it's declaration from the ascx.

Custom event handling

When a button is clicked, a Content View event is called, the CommandButtonsAction, that can be used from code to customize executed action for button click. The following code is an example for cancelling the default action and executing custom logic when the Content is saved:

    protected override void CreatChildControls()
    {
	var content = Content.Load("/Root/Global");
	var contentView = ContentView.Create(content, Page, ViewMode.InlineEdit);
	contentView.CommandButtonsAction += new EventHandler<CommandButtonsEventArgs>(contentView_CommandButtonsAction);
    }
    protected void contentView_CommandButtonsAction(object sender, CommandButtonsEventArgs e)
    {
	switch (e.ButtonType)
	{
	    case CommandButtonType.CheckoutSave:
	    case CommandButtonType.CheckoutSaveCheckin:
	    case CommandButtonType.Publish:
	    case CommandButtonType.Save:
	    case CommandButtonType.SaveCheckin:
	        e.Cancel = true;
	        e.ContentView.Content.DisplayName = "aaa";
	        e.ContentView.Content.Save();
	        break;
	}
    }

Note, that when the e.Cancel property is not set, the Command Buttons control will save the Content using its built-in default logic after the custom code has been executed.

Customizing behavior

Every defined button calls a virtual method. The behavior of buttons can easily be customized by overriding these methods:

public class MyCommandButtons : CommandButtons
{
    protected override void DoCheckoutSaveCheckin()
    {
        // custom action comes here
    }
}

Also don't forget to include your own custom MyCommandButtons instead of the default in the contentview (configure my tagprefix in the webconfig):

  <my:MyCommandButtons ID="CommandButtons1" runat="server" layoutControlPath="/Root/System/SystemPlugins/Controls/CommandButtons.ascx" />

Defining your own custom buttons

Add your custom button's code to the referred CommandButtons.ascx:

<asp:Button ID="MyButton" runat="server"
    Text="My custom button"  />

Define your custom logic in an overridden class:

public class MyCommandButtons : CommandButtons
{
    public IButtonControl MyButton
    {
        get
        {
            return base.LayoutControl.FindControl("MyButton") as IButtonControl;
        }
    }
    protected override void AssociateEventHandlers()
    {
        if (MyButton != null)
            MyButton.Click += new EventHandler(MyButton_Click);
 
        base.AssociateEventHandlers();
    }
    protected void MyButton_Click(object sender, EventArgs e)
    {
        // custom event handler comes here
        bool cancelled;
        this.ContentView.OnCommandButtonsAction(sender, "myButtonClicked", out cancelled);
        if (!cancelled) 
        {
            // custom logic comes here
        }
    }
}

Also don't forget to include your own custom MyCommandButtons instead of the default in the contentview (configure my tagprefix in the webconfig):

  <my:MyCommandButtons ID="CommandButtons1" runat="server" layoutControlPath="/Root/System/SystemPlugins/Controls/CommandButtons.ascx" />

Related links

References