Archives

Archives / 2011 / January
  • Summary page of my recommended links and tools for SharePoint 2010 classes

    Tags: SharePoint 2010

    SNAGHTML130c0c5I've just published a page, which I plan to update regularly, containing links to web sites, tools, products, solutions, articles, posts, books etc. which I recommend and talk about during my SharePoint 2010 classes.

    You can find the page here: Class Links

    If I did promise you during my classes to add a link to it and have forgotten - drop me an e-mail and remind me.

  • SharePoint 2010 Ribbon Controls - Part 7 - The ToggleButton control

    Tags: SharePoint 2010

    Back with another SharePoint 2010 Server Ribbon Controls post, this time a shorter one, compared to previous posts. We'll take a look at the ToggleButton control.

    I know I said I'm going to talk about the DropDown in this post, but I'd reconsidered and take the easy ones first - since the DropDown control will be divided into several posts.

    What is a ToggleButton control?

    The ToggleButton control is very similar in behavior to the Button control with the difference that you can toggle the state of the button; it can either be on or off.

    The ToggleButton

    When the ToggleButton has the On state it has an alternate background color.

    Sample ToggleButton control

    This is how a ToggleButton can be implemented in a CustomAction:

    ToggleButton Id="Wictor.RibbonControls.Tab.ToggleButton1"
        TemplateAlias="section1"
        Alt="Alt Button text"
        Command="Wictor.RibbonControls.ToggleButtonCommand"
        QueryCommand="Wictor.RibbonControls.ToggleButtonQueryCommand"    
        Description="Description"
        LabelText="A ToggleButton"
        Sequence="10"
        Image16by16="/_layouts/Images/Wictor.RibbonControls/Wictor.RibbonControls.png"
        Image16by16Left="0"
        Image16by16Top="-32"
        Image16by16Class="ButtonClass16"
        Image32by32="/_layouts/Images/Wictor.RibbonControls/Wictor.RibbonControls.png"
        Image32by32Left="0"
        Image32by32Top="0"
        Image32by32Class="ButtonClass32"
        LabelCss="BtnLabelClass"
        ToolTipImage32by32="/_layouts/Images/Wictor.RibbonControls/Wictor.RibbonControls.png"
        ToolTipImage32by32Left="0"
        ToolTipImage32by32Top="0"
        ToolTipImage32by32Class="ButtonTTClass"
        ToolTipDescription="A nice and shiny ToggleButton"
        ToolTipHelpKeyWord="RibbonControls"
        ToolTipShortcutKey="ALT + B"
        ToolTipTitle="This is a ToggleButton"
        />

    ToggleButton control properties

    The ToggleButton is very similar to the Button control and also the properties are the same, so before proceeding read about the Button control. The properties documented below are only the ones differing from the Button control or not available for the Button control. The only property from the Button control that is not available in the Button control is the CommandType.

    Property Command

    Just as for a Button control the Command command is executed when someone clicks the ToggleButton. In the JavaScript method that handles the command the state (On or Off) can be retrieved for the ToggleButton. You check the value of the ToggleButton like this in a JavaScript Page Component:

    handleCommand: function (commandId, properties, sequence) {
        switch (commandId) {
            case 'Wictor.RibbonControls.ToggleButtonCommand':
                if(properties.On == true) {
                    alert('ToggleButton state is On');
                } 
                else {
                    alert('ToggleButton state is Off')
                }
                return true;
        }
    }

    Property QueryCommand

    The QueryCommand is invoked when the Tab is loaded and you can use it to set the initial state of the ToggleButton like this:

    handleCommand: function (commandId, properties, sequence) {
        switch (commandId) {
            case 'Wictor.RibbonControls.ToggleButtonQueryCommand':
                // set initial state to on
                properties.On = true;
                return true;
        }
    }

    Summary

    The ToggleButton is as you've seen very similar to the Ribbon control and it is a great alternative to the CheckBox control when you need to handle on/off states. Before diving into the advanced (menu) controls we'll take a look at the Spinner control in the next part.

  • SharePoint 2010 Ribbon Controls - Part 6 - The CheckBox control

    Tags: SharePoint 2010

    Welcome back to part 6 of my SharePoint 2010 Ribbon Controls series (full series index can be found here). This time we'll take a look at the CheckBox control.

    What is the CheckBox control?

    If you've not been hiding under a rock you should now what a CheckBox is - it's a box you can check. It can have two states - checked or not checked.

    CheckBoxes

    Sample CheckBox control

    A CheckBox can look like this when implemented in the Ribbon:

    CheckBox Id="Wictor.RibbonControls.CheckBoxes.CheckBox1"
        LabelText="Check here!"     Command="Wictor.RibbonControls.CheckBoxCommand"
        QueryCommand="Wictor.RibbonControls.CheckBoxQueryCommand"
        Sequence="10"
        TemplateAlias="section2"
        ToolTipDescription="To check or not to check, that's the question"
        ToolTipImage32by32="/_layouts/Images/Wictor.RibbonControls/Wictor.RibbonControls.png"
        ToolTipImage32by32Left="0"
        ToolTipImage32by32Top="0"
        ToolTipImage32by32Class="CBTTClass"
        ToolTipHelpKeyWord="RibbonControls"
        ToolTipShortcutKey="ALT + C"
        ToolTipTitle="Checkitycheck"/>

    CheckBox control properties

    The CheckBox is not that different than the previous controls I've shown you.

    Property TemplateAlias

    As earlier articles shown you it's important to specify a group template layout with a matching display mode for the TemplateAlias. A CheckBox can have DisplayModes set to only Medium or Small. Medium will show the CheckBox including the label (#1 in the image above) and small will only show the CheckBox with the label as tooltip (#2).

    Property LabelText

    This is the label of the CheckBox and written next to the CheckBox when Medium display mode is used.

    Property Alt

    Should be alternative text (never seen this one work though, and not found any trace of it in the generated source code...)

    Property ToolTip????

    See the TextBox control post for more information about tool tips.

    Property MenuItemId

    Used in menus (coming in later posts).

    Property Command

    As usual the Command indicates which command to run when any action is performed on the control - in this case when the CheckBox is clicked. To check if the CheckBox is checked you access the properties.On object which is a boolean (true for checked).

    Property QueryCommand

    The QueryCommand is executed when the tab is selected the first time and it is also fired directly after the Command command. You can use this to set the default value of the CheckBox using the properties.On object.

    A sample implementation of Command and QueryCommand could look like this in a Page Component:

    handleCommand: function (commandId, properties, sequence) {
        switch (commandId) {
            case 'Wictor.RibbonControls.CheckBoxCommand':
                if (properties.On) {
                    alert('Check!');
                }
                break;
            case 'Wictor.RibbonControls.CheckBoxQueryCommand':
                if (!this.checkBoxDefaultSet) {
                    properties.On = true;
                    this.checkBoxDefaultSet = true;
                }
                break;
        }
    },
    checkBoxDefaultSet: false,

    In this sample the QueryCommand uses a local (to the page component instance) variable to check if it is the first QueryCommand that is invoked, and not a QueryCommand succeeding a Command command. It always check the CheckBox when the tab is loaded. When a user checks the CheckBox an alert will be shown.

    Summary

    The CheckBox is a simple yet useful control when building Ribbon customizations. A similar control is the ToggleButton control, which will be discussed in later posts. Next post will be about the DropDown control. Until next time...

  • SharePoint 2010 Ribbon Controls - Part 5 - The Button control

    Tags: SharePoint 2010

    Now it's time for the SharePoint 2010 Ribbon Button Control in the Ribbon Control series (full series index can be found here),

    What is the Button control?

    The Button control needs no further description - it's a button on which the users can click to execute commands. Buttons can exist alone or in menus (which will be covered later in the series).

    Ribbon buttons

    Sample Button control

    A Button control could be implemented as follows:

    Button Id="Wictor.RibbonControls.Tab.Button1"
            TemplateAlias="section1"
            Alt="Alt Button text"
            Command="Wictor.RibbonControls.ButtonCommand"
            CommandType="General"
            LabelText="The Button"
            Sequence="10"
            Image16by16="/_layouts/Images/Wictor.RibbonControls/Wictor.RibbonControls.png"
            Image16by16Left="0"
            Image16by16Top="-32"
            Image16by16Class="ButtonClass16"
            Image32by32="/_layouts/Images/Wictor.RibbonControls/Wictor.RibbonControls.png"
            Image32by32Left="0"
            Image32by32Top="0"
            Image32by32Class="ButtonClass32"
            LabelCss="BtnLabelClass"
            ToolTipImage32by32="/_layouts/Images/Wictor.RibbonControls/Wictor.RibbonControls.png"
            ToolTipImage32by32Left="0"
            ToolTipImage32by32Top="0"
            ToolTipImage32by32Class="ButtonTTClass"
            ToolTipDescription="A nice and shiny button"
            ToolTipHelpKeyWord="RibbonControls"
            ToolTipShortcutKey="ALT + B"
            ToolTipTitle="This is a Button"
            />

    Button control properties

    As you can see from the code sample above the Button control allows for more customizations than the previous discussed controls.

    Property TemplateAlias

    As always with the Ribbon controls you have to make sure that you use a Group Template Layout with a DisplayMode that fits the control. The Button can have the Large, Medium and Small display modes, shown in the figure above as #1, #2 and #3 respectively. When a Button is used in menus, discussed later on in the series, more display modes can be used.

    Property LabelText

    This is the label of the Button and is shown in Large and Medium display modes.

    Property LabelCss

    Specifies a CSS selector class for the label of the Button control

    Property Alt

    Alternative text for the button.

    Property Image16by16????

    Used for Medium and Small display modes. See post about common control properties for more information.

    Property Image32by32????

    Used for the Large display mode. See post about common control properties for more information.

    Property ToolTip????

    See the TextBox control post for more information about tool tips.

    Property Command

    The Command specifies the command executed when the Button is clicked. You can use it as follows in the Page Component handleCommand method:

    handleCommand: function (commandId, properties, sequence) {
        switch (commandId) {
            case 'Wictor.RibbonControls.ButtonCommand':
                alert('Button: ' + properties['SourceControlId']);
                // Do some funky stuff here...
                return;
        }
    }

    The properties object contains three properties:

    • SourceControlId - The Id of the Button control clicked (good if you use the same command for several buttons)
    • MenuItemId - The MenuItemId (only used in Menus, see below)
    • CommandValue - The CommandValueId (only used in Menus, see below)

    Property Description

    This Description property is only used when the button is present in a menu and not in stand alone mode. The display mode must be set to Menu32 to show the Description.

    Property CommandType

    The CommandType can have the following values:

    • General - default value, if attribute is omitted - plain ol' button
    • OptionSelection - used in menus to create selectable options (now you're curious - but I've said menus later...)
    • IgnoredByMenu - also used in menus, a click on these does not close the menu

    Properties MenuItemId, CommandValueId

    A string identifier and a string command value only used in menus

    Summary

    That's all about Buttons - not that advanced but as you see they get more interesting in menus. Next post coming soon to a blog reader near you will be CheckBox control.

  • SharePoint 2010 Ribbon Controls - Part 4 - The TextBox Control

    Tags: SharePoint 2010

    Welcome back to another post in the SharePoint 2010 Ribbon Controls series (full series index available here). Now it is time to introduce the TextBox control, which can be used to allow users to enter text information in your Ribbon customzations.

    What is the TextBox control?

    If you're familiar with .NET development (WinForms or ASP.NET) then you already know what a TextBox is. It allows your users to enter and change text.

    Text boxes

    TextBoxes are often accompanied by Label controls which have the ForId set to the Id of the TextBox to enhance the user interface.

    Sample TextBox control

    A TextBox could be defined in XML like this:

    TextBox Id="Wictor.RibbonControls.Tab.TextBox"
        Command="Wictor.RibbonControls.TextBoxCommand"
        QueryCommand="Wictor.RibbonControls.QueryTextBoxCommand"
        TemplateAlias="section2"
        Width="100"
        MaxLength="20"
        Sequence="10"
        ToolTipImage32by32="/_layouts/Images/Wictor.RibbonControls/Wictor.RibbonControls.png"
        ToolTipImage32by32Left="0"
        ToolTipImage32by32Top="-48"
        ToolTipImage32by32Class="TextBoxTTClass"
        ToolTipDescription="A box where you can enter text"
        ToolTipHelpKeyWord="RibbonControls"
        ToolTipShortcutKey="J"
        ToolTipTitle="This is a textbox"
        ShowAsLabel="false"
        ImeEnabled="true"
        />

    TextBox control properties

    Part from the common properties such as Id and Sequence the following properties can be set:

    Property TemplateAlias

    As for most of the controls you have to know which DisplayModes a control can use. The TemplateAlias for the TextBox must be connected to a Layout row/section with a DisplayMode that has the Medium value.

    Property Width

    The Width property does exactly what it says - it sets the width of the TextBox (in pixels).

    Property MaxLength

    The MaxLength property sets the maximum number of characters allowed in the TextBox.

    Property ShowAsLabel

    ShowAsLabel is a boolean that controls if the TextBox should be rendered as a text box or just a Label. In the image above #1 is a standard TexBox but #2 is a TextBox with ShowAsLabel set to true. Kinda weird - you could use a Label control instead.

    Property ImeEnabled

    If the ImeEnabled is set to true then the Input Method Editor (IME) is set to an active state. Useful when working with Asian languages.

    Property QueryCommand

    The QueryCommand is invoked when Tab is getting focus or after a Command command. It is normally used to set the default value of the TextBox. You also need to use the QueryCommand to set the value in the text box if the ShowAsLabel property is set to true. This is how to set it using the handleCommand Page Component method:

    handleCommand: function (commandId, properties, sequence) {
        switch (commandId) {
            case 'Wictor.RibbonControls.QueryTextBoxCommand':
                if(null == properties['Value']) properties['Value'] = 'Default value';
                return;
        }
    }

    Property Command

    The Command is invoked when the control looses focus (such as selecting another control or pressing a button). You can use this to do calculations or directly store values. Directly after the Command invocation the QueryCommand is invoked. Here is a snippet that converts the value of a text box to upper case:

    handleCommand: function (commandId, properties, sequence) {
        switch (commandId) {
            case 'Wictor.RibbonControls.TextBoxCommand':
                properties['Value'] = properties['Value'].toUpperCase();
                return;
        }
    }

    Property ToolTipTitle

    The ToolTipTitle contains a string value for the tooltip of the TextBox. The image below show how tooltips looks like in the Ribbon. The ToolTipTitle is #1.

    Tooltip

    Property ToolTipDescription

    The ToolTipDescription represents the description of the tooltip. It's #2 in the image above.

    Property ToolTipImage32by32, ToolTipImage32by32Left, ToolTipImage32by32Top, ToolTipImage32by32Class

    These properties represents the icon shown in the tooltip (#3 in the image above). It must be a 32x32 pixel icon and works as icons previously described in the series.

    Property ToolTipShortcutKey

    The ToolTipShortcutKey (#4) represents the character/key for keyboard shortcuts.

    Property ToolTipHelpKeyword

    If you need to include help for your TextBox that takes more than a title or description, then you can use the built-in context sensitive help in SharePoint, which is a really cool feature, see #5 in the image above. Read more about how to configure context sensitive or custom help collections in SharePoint 2010 in the Customizing SharePoint 2010 Help post by the Microsoft SharePoint End-User Content Team. The value in this property must correspond to the Product property of the Help Collection in the custom help.

    Custom help

    Summary

    Using TextBox controls allows you to easily allow users to write input text in your Ribbon customizations; for example in a contextual aware Web Part Ribbon customization. In the next post I'll show you the Button control

  • SharePoint 2010 Ribbon Controls - Part 3 - The Label Control

    Tags: SharePoint 2010

    The first control in the SharePoint 2010 Ribbon Controls series (full series index available here) will be about the Label control.

    What is the Label control?

    The Label control is a simple control that allows you to add a Label to any of your Ribbon groups. Labels are most often used in combination with other controls such as text boxes and drop downs. You can using a label target another control so that if you click on the label then the other control gets focus. A Label can be a text, an icon or both.

    Label Controls

    As the image above shows Labels can have three forms:

    1. Just a text label
    2. A text label with an icon
    3. Just an icon

    Sample Label control

    This is how a Label control could be defined:

    Label 
      Id="Wictor.RibbonControls.Tab.Label"
      LabelText="Label Text"
      Image16by16="/_layouts/Images/Wictor.RibbonControls/Wictor.RibbonControls.png"
      Image16by16Left="0"
      Image16by16Top="-32"
      Image16by16Class="LabelClass"    
      TemplateAlias="section2"
      ForId="Wictor.RibbonControls.Tab.TextBox"
      Command="Wictor.RibbonControls.LabelComand"
      QueryCommand="Wictor.RibbonControls.LabelQueryCommand"
      Sequence="10"/>

    Label control properties

    The Label control have a few properties worth noticing, except the common ones.

    Property: LabelText

    The LabelText property is the text that is displayed in the label.

    Property: Image16by16, Image16by16Top, Image16by16Left, Image16by16Class

    A Label can have one16x16 pixel sized icon and/or CSS class.

    Property: TemplateAlias

    The TemplateAlias (one of the common properties) must be configured so that is connected to a section in the Group Template that has the DisplayMode of either Medium or Small. Any other Display Modes will cause your Ribbon customization to fail. The LabelText, TemplateAlias and icon determines the layout of the Label:

    • A Small DisplayMode must have an icon and will only show the icon (only text on a small Label will cause an error). Label #3 in the image above
    • A Medium sized icon must have a LabelText and optionally an icon. Label #1 and #2 in the image above.

    Property: ForId

    The ForId property is the Id of another Ribbon control. When the Label is selected the control specified by the ForId will get focus.

    Property: Command

    The Command property is never used by the Label control.

    Property: QueryCommand

    The QueryCommand property invokes the command when the Tab containing the control receives focus. This can be used to dynamically update the value of the LabelText. In a JavaScript Page Component you update the LabelText as follows, if the QueryCommand has the value of 'Wictor.RibbonControls.LabelQueryCommand':

    handleCommand: function (commandId, properties, sequence) {
        switch (commandId) {
            case 'Wictor.RibbonControls.LabelQueryCommand':
                properties['Value'] = 'Label changed';
                return;
        }
    }

    When the Tab receives focus the Label will change its LabelText to the value specified in the JavaScript.

    Summary

    That was the first one - the Label control. Next time we'll add a TextBox which will be connected to the Label using the ForId property.

  • SharePoint 2010 Ribbon Controls - Part 2 - Common Control Properties

    Tags: SharePoint 2010

    This first real post in the SharePoint 2010 Ribbon Controls series (full series index available here) will be about some of the common properties that most or all of the Ribbon controls shares. I assume that you have some basic knowledge of SharePoint 2010 Ribbon customization, if not check out one of my previous posts.

    What is a Ribbon control?

    A SharePoint 2010 Ribbon Control is the interactive parts of the Ribbon. Controls exits within a Group (B) within a Tab (A). The controls can be labels, buttons, drop downs, menus, galleries and more. You can add, remove or change default Ribbon controls or add completely new Tabs and Groups.

    Ribbon controls

    The default Ribbon interface is defined in CMDUI.xml which is located in the {SharePoint Root}\TEMPLATE\GLOBAL\XML. A good tip is to take a look at the default Ribbon configuration before making your own Tabs and Groups - but never ever change the CMDUI.xml file!

    In the image above you see some common controls;

    1. This is a MRUSplitButton control, which contains a submenu with different items
    2. This is a SplitButton, also with a submenu
    3. This is a ComboBox
    4. This is a ToggleButton

    In this series we will take a look at each one of those controls, to be exact I'll show you all available controls in the Ribbon.

    All SharePoint 2010 Ribbon customization is done through XML, there are a couple of ways to add them - statically or dynamically, but the XML are the same. The controls must be children of a Controls element within a CommandUIDefinition, Group or MenuSection element (all defined in the Server Ribbon Schema). Some are are more advanced than others.

    Common control properties

    All controls have a set of properties that works basically the same. Instead of repeating them for all posts in this series I will walk you through them once and for all before I go in to the specific control properties. Some of these properties will be repeated to discuss specifics for the respectively controls.

    Property: Id (required)

    The Id property of a control is one important and sensitive little guy. It's a string value and must be unique within your Ribbon customization. Not specifying it or not making it unique can make your whole customization fail without any good error messages.

    I prefer using a "namespace" style of control Id's so that I easily can find out where the control belongs. Preferably prepend the control id with the id of the Tab or Group.

    What's your Id?

    Property: Sequence

    The Sequence property states in what order the controls should appear in overflow sections. It's not required but if present it must be an integer.

    Property: TemplateAlias

    The TemplateAlias property is used to specify which template alias to use from the Group Template Layout. That is how the control is positioned, which section or row. This property must be a string value corresponding to one of the aliases defined in the group template layout.

    TemplateAlias

    Important here is to make sure that your control can handle the DisplayMode of the specified TemplateAlias.

    NOTE: Make sure that you always create your own Group Templates. Read AC's post about it here: http://www.andrewconnell.com/blog/archive/2010/10/10/always-create-your-own-group-templates-with-sharepoint-ribbon-customizations.aspx

    Property: ImageXXbyXX, ImageXXbyXXTop, ImageXXbyXXLeft, ImageXXbyXXClass

    These properties are used to specify an image/icon for a control, it is not used by all control types but you can expect them to be used on Labels and Buttons. Different controls use different sizes (the XX's in the header) - it's either 16x16 or 32x32. Which one used is defined by the DisplayMode of the template alias. The ImageXXbyXX specifies a URL to an image. ImageXXbyXXTop and ImageXXbyXXLeft is used when you use CSS sprites to select the position of the icon from the composite image (example below). The ImageXXbyXXClass is used to set a specific CSS class to the control - for instance if you prefer to use CSS to create the image layout.

    Stylish control

    Property: Command

    All controls have a Command property which specifies the command to run when for instance a button is pressed. This is a string defining the command. If you use declarative commands, that is defined in the XML using CommandUIHandler elements, then the CommandUIHandler with the corresponding Command attribute will be invoked. If you instead use page components then Command value is handled by the handleCommand JavaScript function of the page component. I will show you more about this in upcoming samples.

    Property: QueryCommand

    The QueryCommand works just the same as the Command property with the difference that it is invoked when the Tab is getting focus. The function is also invoked directly after the Command command. You can use this one to set values of the controls.

    Summary

    So now we've started this series for real. Keep on reading, next post will come shortly, and that one is about the Label control.

  • SharePoint 2010 Ribbon Controls - Part 1 - Summary

    Tags: SharePoint 2010

    Welcome to 2011, this will for sure be an exciting year! I thought I start this year off with a series of blog posts about the different controls that can be used in the SharePoint 2010 Ribbon. Hopefully a bit better than the current MSDN documentation.

    The series will discuss each control that are available for usage in the SharePoint 2010 Ribbon and show you through examples and code how to use them. I will even throw in one or more tips and tricks along the road.

    SNAGHTML173f702

    So if you're interested - watch my Twitter account (http://twitter.com/wictor) and/or follow my RSS feed (http://feeds2.feedburner.com/WictorWilen) for new posts in the series.

    Parts

    This post is a summary post that I will update with the correct links as the series progress.

    I don't know yet, but it will possibly be some follow-ups depending on your comments and questions. If you have them already - then don't hesitate to fire them away. Also expect some changes to the outline above...

AWS Tracker

About Wictor...

Wictor Wilén is a Director and SharePoint Architect working at Connecta AB. Wictor has achieved the Microsoft Certified Architect (MCA) - SharePoint 2010, Microsoft Certified Solutions Master (MCSM) - SharePoint  and Microsoft Certified Master (MCM) - SharePoint 2010 certifications. He has also been awarded Microsoft Most Valuable Professional (MVP) for four consecutive years.

And a word from our sponsors...

SharePoint 2010 Web Parts in Action