The definition of a CustomAction element requires the declaration of a feature element manifest, based on the XML structure, as illustrated in The CustomAction element structure.

<CustomAction
  RequiredAdmin = "Delegated | Farm | Machine"
  ControlAssembly = "Text"
  ControlClass = "Text"
  ControlSrc = "Text"
  Description = "Text"
  FeatureId = "Text"
  GroupId = "Text"
  Id = "Text"
  ImageUrl = "Text"
  Location = "Text"
  RegistrationId = "Text"
  RegistrationType = "Text"
  RequireSiteAdministrator = "TRUE" | "FALSE"
  Rights = "Text"
  RootWebOnly = "TRUE" | "FALSE"
  ScriptSrc = "Text"
  ScriptBlock = "Text"
  Sequence = "Integer"
  ShowInLists = "TRUE" | "FALSE"
  ShowInReadOnlyContentTypes = "TRUE" | "FALSE"
  ShowInSealedContentTypes = "TRUE" | "FALSE"
  Title = "Text"
  UIVersion = "Integer">
    <UrlAction />
    <CommandUIExtension />
</CustomAction>

The CustomAction element is made of a set of attributes and accepts a couple of optional child elements. Table 12-1 describes each available attribute.

In addition, a CustomAction tag can contain some child elements:

The basic and most-used attributes are those for defining the ID, the title, the location (where you want the action to appear), and the registration type, together with the registration ID. For example, if you want your action to be displayed when the end user clicks the contextual menu of a document (also called the Edit Control Block [ECB] menu), you can define a custom action for the document libraries of a site like the one illustrated in A CustomAction targeting the ECB menu of items in a document library.

<CustomAction
  Location="EditControlBlock"
  RegistrationType="List"
  RegistrationId="101"
  Id="DevLeap.CustomActions.DemoECB.SampleAction"
  Title="Sample Action"
  Description="Sample custom action.">
  <UrlAction Url="javascript:window.alert('You clicked the Sample Action!'),"/>
</CustomAction>

The Location attribute specifies that the action will be shown in the ECB menu. The RegistrationType attribute targets a specific List, while the RegistrationId explicitly defines the list type (101 = “Document Library”). Notice the child element, UrlAction, which defines a destination URL for when the end user clicks the menu item. In this first example, the custom action simply shows an alert. Figure 12-1 depicts how the action looks in the web browser.

Figure 12-1. The custom action shown in the ECB of a document item.

Often, you need to define a custom action targeting not only a list, but also a specific content type, regardless of the list in which it is contained. For example, suppose that you have a custom content type defining a document of type invoice (call it DevLeapInvoice). This content type needs to have an identifying unique ID, which in this example will have a value of 0x010100DFCFE30E0795465F8973EF29B73F1551.

The DevLeapInvoice content type has some custom metadata fields to define the invoice number, a description, and a status that can assume some predefined values (Draft, Approved, Sent, and Archived). Figure 12-2 illustrates the edit form of this kind of document.

Figure 12-2. The edit form of a DevLeapInvoice item instance.

A CustomAction element targeting the ECB of items with a content type of DevLeapInvoice demonstrates a custom action, still targeting the ECB, that will be shown only in the ECB of items with a content type of DevLeapInvoice. The action allows archiving a single invoice, changing its Status field to a value of Archived.

<CustomAction
  Location="EditControlBlock"
  RegistrationType="ContentType"
  RegistrationId="0x010100DFCFE30E0795465F8973EF29B73F1551"
  Id="DevLeap.CustomActions.Invoices.Archive"
  Title="Archive Invoice"
  Rights="ViewListItems,EditListItems"
  Description="Archive this Invoice.">
  <UrlAction Url="~site/_layouts/DevLeap.SP2013.UIExtensions/
  DevLeapInvoiceChangeStatus.aspx?ItemId={ItemId}&ListId={ListId}&
  Status=Archived" />
</CustomAction>

The only substantial difference between A CustomAction element targeting the ECB of items with a content type of DevLeapInvoice and A CustomAction targeting the ECB menu of items in a document library is the RegistrationType attribute, which now targets a ContentType, as well as the RegistrationId, which now defines the ID of the target content type instead of the ID of a list template. The code sample in A CustomAction element targeting the ECB of items with a content type of DevLeapInvoice also introduces the Rights attribute, with which you can archive invoices only to users who have the ViewListItems and EditListItems permissions assigned.

Additionally, the UrlAction child element defined in A CustomAction element targeting the ECB of items with a content type of DevLeapInvoice declares a URL of a custom application page, instead of a piece of JavaScript, as in A CustomAction targeting the ECB menu of items in a document library. The URL could also link to a custom page provided by a custom SharePoint 2013 app. In the “Application pages” section of this chapter, you will learn how to deploy custom application pages. For now, however, disregard the page itself and focus your attention on the Url attribute of the UrlAction element. This attribute can link to any kind of URL and can contain tokens that will be replaced by the environment during page rendering. These tokens are

Finally, you can use any valid JavaScript code block.

In A CustomAction element targeting the ECB of items with a content type of DevLeapInvoice, the Url attribute uses the {ItemId} and {ListId} tokens because it targets the ECB menu of a single item, so it passes the item ID and list ID to the target page as QueryString parameters.

The ECB menu isn’t the only location suitable for defining custom actions. Table 12-2 lists the most useful additional locations.

Microsoft also documents the Id values for many of the previously defined custom actions, with which you can override standard menu items with custom items of your own.

Another useful element for defining custom actions is CustomActionGroup. Using this element, you can define groups of actions; it is typically used when defining custom sections in the configuration pages, such as the Site Settings page or the pages of the Central Administration. In fact, you can also extend and override administrative pages, not only end-user UI elements. The CustomActionGroup element structure shows the structure of the CustomActionGroup element.

<CustomActionGroup
  Description = "Text"
  Id = "Text"
  Location = "Text"
  Sequence = "Integer"
  Title = "Text">
</CustomActionGroup>

The CustomActionGroup element is mainly descriptive (for the group it defines). It does not have any child elements because the only purpose of this element is to declare a new group, which will be referenced by other custom actions. Table 12-3 presents a brief description of the available attributes.

CustomActionGroup element extending the Site Settings administrative page illustrates how to use the CustomActionGroup element to define a new section in the Site Settings administrative page. Notice the CustomAction element that uses a value of Microsoft.SharePoint.SiteSettings for the Location attribute and the value of the custom action group’s Id for the GroupId attribute.

<CustomActionGroup
  Location="Microsoft.SharePoint.SiteSettings"
  Id="DevLeap.CustomActions.Invoices.Settings"
  Description="View Invoices Settings"
  Title="Invoices Management" />
<CustomAction
  Location="Microsoft.SharePoint.SiteSettings"
  GroupId="DevLeap.CustomActions.Invoices.Settings"
  Id="DevLeap.CustomActions.Invoices.SampleSettings"
  Title="Invoices Sample Settings Page"
  Description="Go to a custom page for managing Invoices' settings.">
  <UrlAction Url="~site/_layouts/DevLeap.SP2013.UIExtensions/InvoicesSettings.aspx" />
</CustomAction>

Figure 12-3 shows the customized Site Settings administrative page in action.

Figure 12-3. A customized Site Settings administrative page.

The last element available for customizing UI actions is HideCustomAction. Using this element, you can hide existing actions, regardless of whether they are standard, native actions or custom actions defined by you or someone else. Be aware, though, that not all native actions can be hidden. The HideCustomAction element structure shows you the structure of the HideCustomAction element.

<HideCustomAction
  GroupId = "Text"
  HideActionId = "Text"
  Id = "Text"
  Location = "Text">
</HideCustomAction>

This element simply defines the information about the action to hide. Table 12-4 gives you a brief explanation of the available attributes.

A sample HideCustomAction element declaration presents an example of the HideCustomAction element being used to hide the Quick Launch menu item in the Look And Feel group of the Site Settings page.

<HideCustomAction
  Id="DevLeap.CustomActions.HideQuickLaunchFromSettings"
  Location="Microsoft.SharePoint.SiteSettings"
  GroupId="Customization"
  HideActionId="QuickLaunch" />

In A sample HideCustomAction element declaration, the Location, GroupId, and HideActionId attributes correspond to those identifying the Site Theme action. Figure 12-4 shows the result of this action, comparing the page before applying the customization, and then after.

Figure 12-4. The Look And Feel group before (left) and after (right) hiding the Site Theme action.

You can also create custom actions that define their content dynamically by using server-side code, instead of using an XML declaration. To define this kind of action, you need to declare a CustomAction element within a feature element manifest, providing a value for the ControlAssembly and ControlClass attributes. These attributes must reference the assembly and the full type name of a class inheriting from the base class System.Web.UI.WebControls.WebControl and building a specific set of controls inside the CreateChildControls method override. The custom action referencing a custom ControlClass attribute illustrates an example of a custom action referencing a custom ControlClass attribute.

<CustomAction
  Location="Microsoft.SharePoint.StandardMenu"
  GroupId="SiteActions"
  ControlAssembly="DevLeap.SP2013.UIExtensions, Version=1.0.0.0,
    Culture=neutral, PublicKeyToken=3b7c6076bf78362f"
  ControlClass="DevLeap.SP2013.UIExtensions.SwitchToMobileMode"
  Id="DevLeap.CustomActions.SwitchToMobileMode">
</CustomAction>

The action targets the Site Actions menu (also known as the gear menu) and allows switching the site to mobile-rendering mode. Of course, you could write this action without a custom class, but this example gives you an idea of what’s possible.

The class referenced by the CustomClass attribute of the custom action of The custom action referencing a custom ControlClass attribute displays the sample implementation of the class, which is referenced in the ControlClass attribute, and which internally generates the menu item.

public class SwitchToMobileMode : System.Web.UI.WebControls.WebControl {
    protected override void CreateChildControls() {
        SPWeb web = SPControl.GetContextWeb(HttpContext.Current);
        MenuItemTemplate switchToMobile = new MenuItemTemplate();
        switchToMobile.Text = "Switch to Mobile view";
        switchToMobile.Description =
          "Switches the current site rendering mode to mobile";
        switchToMobile.ClientOnClickNavigateUrl =
          String.Format("{0}?Mobile=1", web.Url);
        this.Controls.Add(switchToMobile);
    }
}

The class referenced by the CustomClass attribute of the custom action of The custom action referencing a custom ControlClass attribute illustrates that you can instantiate a MenuItemTemplate class, which represents a single menu item. You can then configure its descriptive properties, such as Text, Description, ImageUrl, and so on. However, the fundamental properties are those related to the behavior of the menu item within the UI. You can configure the ClientOnClickNavigateUrl property if you simply need to define a URL to navigate to when the user clicks the menu. Additionally, you can configure the ClientOnClickScript property to configure an ECMAScript code block to execute when the menu entry is clicked. Lastly, to set the control ID and parameter for a postback event, you can assign the ClientOnClickUsingPostBackEvent property. In this last scenario, you should handle the postback event yourself; for example, by implementing the System.Web.UI.IPostBackEventHandler interface in the control class. You can also configure the ClientOnClickPostBackConfirmation property to provide a confirmation message that will be displayed to the end user, just before handling the post-back event. Figure 12-5 shows the result of the sample in The class referenced by the CustomClass attribute of the custom action of The custom action referencing a custom ControlClass attribute.

Figure 12-5. The custom action defined using a MenuItemTemplate class on the server side.

Another type of menu that you can instantiate within custom code is SubMenuTemplate, which represents the parent of a hierarchical menu.

Regardless of the type of menu items you define within your CustomClass implementation, it is mandatory to define the class as a SafeControl object for SharePoint. (Details about using SafeControl elements in web.config files were presented at the end of Chapter 11)

Ribbon commands represent single items to place in a previously existing ribbon tab and group. For example, think about the code sample in A CustomAction element targeting the ECB of items with a content type of DevLeapInvoice. The goal of that custom action was to allow archiving a single invoice, changing its Status field to a value of Archived. A better option, however, would be to give users the opportunity to archive multiple invoices at the same time. The ECB menu extended with A CustomAction element targeting the ECB of items with a content type of DevLeapInvoice applies only to a single item, while a ribbon command could be applied to multiple items simultaneously, improving usability and overall user experience.

To get familiar with ribbons, start with a simple example. A sample ribbon that shows an alert upon being clicked presents a ribbon that displays an alert when it is clicked.

<CustomAction
  RegistrationType="ContentType"
  RegistrationId="0x010100DFCFE30E0795465F8973EF29B73F1551"
  Id="DevLeap.CustomActions.Invoices.SampleRibbonCommand"
  Location="CommandUI.Ribbon.ListView">
  <CommandUIExtension>
    <CommandUIDefinitions>
      <CommandUIDefinition Location="Ribbon.Documents.Manage.Controls._children">
        <Button Id="SampleRibbonCommand"
                Alt="Shows an alert."
                Description="Shows an alert, just to make an example."
                Sequence="25"
                Command="ShowSampleAlert"
Image16by16="/_layouts/15/images/DevLeap.SP2013.UIExtensions/Baloon_16x16.png"
Image32by32="/_layouts/15/images/DevLeap.SP2013.UIExtensions/Baloon_32x32.png"
                LabelText="Show Alert"
                TemplateAlias="o1" />
      </CommandUIDefinition>
    </CommandUIDefinitions>
  <CommandUIHandlers>
    <CommandUIHandler Command="ShowSampleAlert"
                      CommandAction="javascript:
                      window.alert('This an alert from the ribbon')," />
    </CommandUIHandlers>
  </CommandUIExtension>
</CustomAction>

The CustomAction element is almost the same as in the previous section, but the Location attribute targets a location with a value of CommandUI.Ribbon.ListView, which corresponds to the ribbon menu of a ListView control. Then the action targets the DevLeapInvoice content type through its content type ID, as with the ECB custom action defined earlier. Thus, the ribbon command will show up only while DevLeapInvoice  items are being worked on. However, instead of a UrlAction child element, now there is a CommandUIExtension element, which defines a ribbon item. In particular, it defines a set of CommandUIDefinition elements, wrapped in a CommandUIDefinitions parent element, together with one or more CommandUIHandler elements, wrapped by a CommandUIHandlers parent tag. A CommandUIDefinition element defines the UI behavior of the command with its Location attribute, which in the code sample has a value of Ribbon.Documents.Manage.Controls._children and declares that its child elements will be children of the Manage group of the Documents tab of the ribbon. In A sample ribbon that shows an alert upon being clicked, the command is represented as a Button element with a title, a description, a couple of images sized 16×16 pixels and 32×32 pixels, and so on. Also in A sample ribbon that shows an alert upon being clicked, the Button element has a Sequence attribute with a value of 25, which means it will render between the second and third button of the target ribbon group (Manage). For standard and native buttons, the Sequence attribute has a value that is a multiple of 10. Thus, the first button has a Sequence value of 10, the second has a Sequence value of 20, and so on.

Another interesting Button attribute is TemplateAlias, which defines the rendering behavior of the control. Native available templates are o1, which renders the 32×32 image form of the button, and o2, which renders the 16×16 image form. However, you can also define your own templates. Additionally, the CommandUIHandler element declares the code to execute when the commands are clicked. For example, in A sample ribbon that shows an alert upon being clicked, the CommandAction attribute of the CommandUIHandler element invokes a client-side window.alert method based on JavaScript. For mapping the Button to its handler, there is a Command attribute whose value corresponds to the Command attribute of the CommandUIHandler element. Figure 12-6 shows the results of A sample ribbon that shows an alert upon being clicked in action.

Figure 12-6. The custom ribbon command to show an alert in action.

The CommandUIDefinition element can host a rich set of child elements. Table 12-5 presents a quick list of all the supported child elements, taken from the official product documentation on MSDN (http://msdn.microsoft.com/en-us/library/ff458373.aspx).

Recall that the goal of this particular section is to have a ribbon with which a user can archive multiple items with content type DevLeapInvoice at the same time. Source code for a ribbon that archives one or more items with a content type of DevLeapInvoice shows the source code necessary.

<CustomAction
  RegistrationType="ContentType"
  RegistrationId="0x010100DFCFE30E0795465F8973EF29B73F1551"
  Id="DevLeap.CustomActions.Invoices.ArchiveRibbon"
  Location="CommandUI.Ribbon.ListView">
  <CommandUIExtension>
    <CommandUIDefinitions>
      <CommandUIDefinition
        Location="Ribbon.Documents.EditCheckout.Controls._children"> 
        <Button Id="InvoiceArchiveRibbonButton"
                Alt="Changes the status of the Invoice to Archived."
                Description="Change the status of the Invoice to Archived."
                Sequence="25"
                Command="ChangeInvoiceStatusToArchived"
                Image16by16=
"/_layouts/15/images/DevLeap.SP2013.UIExtensions/IconArchive_16x16.gif"
                Image32by32=
"/_layouts/15/images/DevLeap.SP2013.UIExtensions/IconArchive_32x32.gif"
                LabelText="Archive Invoices"
                TemplateAlias="o1" />
      </CommandUIDefinition>
    </CommandUIDefinitions>
    <CommandUIHandlers>
      <CommandUIHandler Command="ChangeInvoiceStatusToArchived"
                        EnabledScript="javascript:
                            function checkInvoicesSelected() {
                              // Check the number of selected items
                              var items =
                                SP.ListOperation.Selection.getSelectedItems();
                              return (items.length >= 1);
                            }
                            checkInvoicesSelected();"
                        CommandAction="javascript:
                            // Shared variables
                            var ctx;
                            var itemsToArchive;
                            var notifyId = '';
                            // Function that archives the selected items
                            function archiveInvoices() {
                              // Notify the end user about the work in progress
                              this.notifyId =
                                SP.UI.Notify.addNotification(
                                  'Archiving items…', true);
                              // Get the current ClientContext
                              this.ctx = new SP.ClientContext.get_current();
                              // Get the current Web
                              var web = this.ctx.get_web();
                              // Get the currently selected list
                              var listId =
                                SP.ListOperation.Selection.getSelectedList();
                              var sourceList = web.get_lists().getById(listId);
                              // Get the selected items and archive each of them
                              var items =
                                SP.ListOperation.Selection.getSelectedItems(
                                  this.ctx);
                              var item;
                              this.itemsToArchive = new Array(items.length);
                              for(var i in items) {
                                item = items[i];
                               // Get each selected item
                                var listItem = sourceList.getItemById(item.id);
                                this.itemsToArchive.push(listItem);
                                this.ctx.load(listItem);
                              }
                              // Effectively load items from SharePoint
                              this.ctx.executeQueryAsync(
                                Function.createDelegate(this, onQuerySucceeded),
                                Function.createDelegate(this, onQueryFailed));
                            }
                            // Delegate called when server
                            // operation is completed upon success
                            function onQuerySucceeded(sender, args) {
                              // Mark each item as Archived
                              var item = null;
                              do {
                                item = this.itemsToArchive.pop();
                                if (item != null) {
                                  item.set_item('DevLeapInvoiceStatus', 
                                      'Archived'),
                                  item.update();
                                }
                              } while (item != null);
                              // Effectively update items in SharePoint
                              this.ctx.executeQueryAsync(
                              Function.createDelegate(this, onUpdateSucceeded),
                              Function.createDelegate(this, onQueryFailed));
                            }
                            // Delegate called when server
                            // operation is completed upon success
                            function onUpdateSucceeded(sender, args) {
                              SP.UI.Notify.removeNotification(this.notifyId);
                              SP.UI.ModalDialog.RefreshPage(
                              SP.UI.DialogResult.OK);
                            }
                            // Delegate called when server
                            // operation is completed with errors
                            function onQueryFailed(sender, args) {
                              alert('The requested operation failed: ' +
                                args.toString());
                            }
                            archiveInvoices();" />
    </CommandUIHandlers>
  </CommandUIExtension>
</CustomAction>

Although Source code for a ribbon that archives one or more items with a content type of DevLeapInvoice is not short, it is actually quite simple. In fact, it takes advantage of the JavaScript Client-Side Object Model (JSOM)—which was presented in Chapter 7—within the code of the CommandAction attribute of the CommandUIHandler element. It creates a ClientContext, retrieves the selected items by using the SP.ListOperation.Selection class, and then updates them with a Status field value of Archived, invoking the asynchronous operation via the executeQueryAsync method of the ClientContext.

It is interesting to note that the ribbon is entirely defined in XML and JavaScript, without the need for any kind of server-side code. Thus, it will work asynchronously in the web browser without requiring a postback to the server. The only postback is required at the end of the update process, to refresh the list of items and reflect the applied changes. You can see the invocation of the SP.UI.ModalDialog.RefreshPage method in the onUpdateSucceeded method. You can also include the JavaScript code in an external JS file and reference it using a custom action with the Location attribute with a value of ScriptLink. Last but not least, remember that you can deploy such commands while working within a custom SharePoint 2013 app as well.

Another interesting aspect of Source code for a ribbon that archives one or more items with a content type of DevLeapInvoice is the attribute EnabledScript of the element CommandUIHandler. This attribute is invoked on the client side, and it contains another JavaScript script block to determine if the ribbon command must be enabled or disabled. Internally, the script checks the number of selected items and returns true only if there is at least one invoice selected in the result of the SP.ListOperation.Selection.getSelectedItems() method. As the sample code illustrates, the SP.ListOperation.Selection.getSelectedItems() method returns only the IDs of the selected items, not the items themselves.

To complete the example, the Location attribute of the CommandUIDefinition element declares where to locate the new ribbon. In this example, the ribbon is in the Open & Check Out group of the Documents tab, which has a location of Ribbon.Documents.EditCheckout.Controls. Thus, the new command has a Location value of Ribbon.Documents.EditCheckout.Controls._children to instruct the environment to show the item as a child of the Open & Check Out group.

The sample code of Source code for a ribbon that archives one or more items with a content type of DevLeapInvoice also uses the new notification area of SharePoint 2010, which will be discussed in the “Status bar and notification area” section. Figure 12-7 shows the ribbon command in action.

Figure 12-7. The custom ribbon command to archive multiple invoices simultaneously.

Finally, consider that inside the code of the CommandAction attribute, you can use substitution tokens that are replaced by the environment before executing the script. The available tokens are

One last scenario to consider is the creation of a custom ribbon tab. In fact, if you have multiple commands to support your custom content, it is good habit to define a ribbon tab of your own, instead of extending an existing one. To define a new tab of ribbons, you need to use the Tab, Scaling, Groups, and Group elements. A custom tab of ribbons for a content type of DevLeapInvoice demonstrates the declaration of a custom tab, which will show up only when selecting items with a content type of DevLeapInvoice. The tab will host three buttons that, for the sake of simplicity, just show an alert with a welcome message.

<CustomAction
  RegistrationType="ContentType"
  RegistrationId="0x010100DFCFE30E0795465F8973EF29B73F1551"
  Id="DevLeap.CustomActions.Invoices.Tab"
  Location="CommandUI.Ribbon.ListView">
  <CommandUIExtension>
    <CommandUIDefinitions>
      <CommandUIDefinition
        Location="Ribbon.Tabs._children">
        <Tab
          Id="DevLeap.CustomActions.Invoices.Tab.One"
          Title="Invoices"
          Description="This tab holds custom commands for Invoices."
          Sequence="1000">
          <Scaling
            Id="DevLeap.CustomActions.Invoices.Tab.One.Scaling">
            <MaxSize
              Id="DevLeap.CustomActions.Invoices.Tab.One.Scaling.MaxSize"
              GroupId="DevLeap.CustomActions.Invoices.Tab.One.GroupOne"
              Size="OneLargeTwoSmall"/>
            <Scale
              Id="DevLeap.CustomActions.Invoices.Tab.One.Scaling.Scale"
              GroupId="DevLeap.CustomActions.Invoices.Tab.One.GroupOne"
              Size="OneLargeTwoSmall" />
          </Scaling>
          <Groups Id="DevLeap.CustomActions.Invoices.Tab.Groups">
            <Group
              Id="DevLeap.CustomActions.Invoices.Tab.One.GroupOne"
              Description="This is the first group."
              Title="First Group"
              Sequence="52"
              Template="DevLeap.CustomActions.Invoices.RibbonTemplate">
              <Controls Id="Ribbon.CustomTabExample.CustomGroupExample.Controls">
                <Button
                  Id="DevLeap.CustomActions.Invoices.Tab.One.ButtonOne"
                  Command="ButtonOneCommand"
                  Sequence="10"
                  Description="First sample command."
                  Image32by32=
"/_layouts/15/$Resources:core,Language;/images/formatmap32x32.png"
                  Image32by32Left="-160"
                  Image32by32Top="-256"
                  LabelText="First sample command!"
                  TemplateAlias="customOne"/>
               <Button
                  Id="DevLeap.CustomActions.Invoices.Tab.One.ButtonTwo"
                  Command="ButtonTwoCommand"
                  Sequence="20"
                  Description="Second sample command."
                  Image16by16=
"/_layouts/15/$Resources:core,Language;/images/formatmap16x16.png"
                  Image16by16Left="-144"
                  Image16by16Top="-32"
                  LabelText="Second sample command!"
                  TemplateAlias="customTwo"/>
                <Button
                  Id="DevLeap.CustomActions.Invoices.Tab.One.ButtonThree"
                  Command="ButtonThreeCommand"
                  Sequence="30"
                  Description="Third sample command."
                  Image16by16=
"/_layouts/15/$Resources:core,Language;/images/formatmap16x16.png"
                  Image16by16Left="-96"
                  Image16by16Top="-128"
                  LabelText="Third sample command!"
                  TemplateAlias="customThree"/>
              </Controls>
            </Group>
          </Groups>
        </Tab>
      </CommandUIDefinition>
      <CommandUIDefinition Location="Ribbon.Templates._children">
        <GroupTemplate Id="DevLeap.CustomActions.Invoices.RibbonTemplate">
          <Layout
            Title="OneLargeTwoSmall"
            LayoutTitle="OneLargeTwoSmall">
            <Section Alignment="Top" Type="OneRow">
              <Row>
                <ControlRef DisplayMode="Large" TemplateAlias="customOne" />
              </Row>
            </Section>
            <Section Alignment="Top" Type="TwoRow">
              <Row>
                <ControlRef DisplayMode="Small" TemplateAlias="customTwo" />
              </Row>
              <Row>
                <ControlRef DisplayMode="Small" TemplateAlias="customThree" />
              </Row>
            </Section>
          </Layout>
        </GroupTemplate>
      </CommandUIDefinition>
    </CommandUIDefinitions>
     <CommandUIHandlers>
      <CommandUIHandler
        Command="ButtonOneCommand"
        CommandAction="javascript:window.alert('You pressed CommandOne!')," />
      <CommandUIHandler
        Command="ButtonTwoCommand"
        CommandAction="javascript:window.alert('You pressed CommandTwo!')," />
      <CommandUIHandler
        Command="ButtonThreeCommand"
        CommandAction="javascript:window.alert('You pressed CommandThree!')," />
    </CommandUIHandlers>
  </CommandUIExtension>
</CustomAction>

A custom tab of ribbons for a content type of DevLeapInvoice first creates a new ribbon tab that declares a Location value of Ribbon.Tabs._children, with a Title value of Invoices. It also declares some scaling information, indicating how the ribbon will behave when the window is resized. Specifically, you must define a MaxSize element for each ribbon group, describing the rendering behavior at the maximum size. You also need to define at least one Scale element for each ribbon group, providing information about how to scale the contents of the group. Both the MaxSize and Scale elements use a Size attribute with a value that references the Title attribute of the Layout elements defined in the CommandUIDefinition element, with a Location value of Ribbon.Templates._children. In the current example, the OneLargeTwoSmall sizing layout describes a first Section element with one row, and a second Section element with two rows. The Row elements defined in the Section elements also declare a TemplateAlias, which the Button elements will reference. It is also important to notice the value of the Location attribute of the two CommandUIDefinition elements.

Notice the way that the images of the buttons are defined. For performance reasons, SharePoint 2013 uses CSS image sprites, which use images that are maps of multiple icons, rendered using CSS cropping. For example, there are two image files, named formatmap16x16.png and formatmap32x32.png, that contain a rich set of icons used for rendering buttons of ribbons and menus with a size of 16×16 pixels and 32×32 pixels, respectively. If you want to render a specific image, you need to reference the proper picture in the Image16by16 or Image32by32 attribute, depending on the size of the image you are looking for. Then you need to provide the location of the top and left corners of the image to crop, using the attributes Image16by16Top and Image16by16Left, or Image32by32Top and Image32by32Left. These attributes require a negative value for the offset. In A custom tab of ribbons for a content type of DevLeapInvoice, the image URLs include the reference to the proper culture code, determined by querying the core resource strings. Figure 12-8 displays the output of A custom tab of ribbons for a content type of DevLeapInvoice as it appears in the web browser.

Figure 12-8. The custom tab of ribbons targeting the content type DevLeapInvoice.

The first types of content that you will probably need to deploy are custom images. By default, SharePoint stores images in the SharePoint15_RootTEMPLATEIMAGES folder and makes them available through a virtual directory named _layouts/15/images/.

Working with Visual Studio 2012, you can deploy custom images in the proper folder by right-clicking the project to open the menu shown in Figure 12-9, and then selecting Add | SharePoint “Images” Mapped Folder. This creates a folder named Images in your project. When you add an image file to this folder, the file will be automatically deployed in the SharePoint Images folder. To better organize files in the SharePoint folders, Visual Studio 2012 automatically creates a subfolder that uses the name of the current project and places the images there. For example, if your project name is MyCustomProject, and you add an image file with the name MyImage.jpg, then the image will be deployed under the path SharePoint15_RootTEMPLATEIMAGESMyCustomProjectMyImage.jpg, and will be available through the relative URI ./_layouts/15/images/MyCustomProject/MyImage.jpg.

Figure 12-9. The menu item to add an image to the SharePoint15_RootTEMPLATEIMAGES folder.

If you need to deploy other kinds of generic content, such as ASCX controls, CSS files, JS files, and so on, select Add | SharePoint Mapped Folder from the project’s contextual menu. You will be prompted with a pop-up window like the one shown in Figure 12-10. From there, you will be able to select any of the folders available under the SharePoint15_Root path.

Figure 12-10. The pop-up window to select a SharePoint mapped folder.

Application pages are ASPX files that are available for all sites of a farm and deployed in the SharePoint15_RootTEMPLATELAYOUTS folder. SharePoint makes them available through a virtual directory named _layouts. In general, these pages are defined to provide the UI for administrative tasks or to implement custom application pages that will be used to support custom solutions, which in this case do not include SharePoint apps that use a different page model (as discussed in Chapter 8). For example, A CustomAction element targeting the ECB of items with a content type of DevLeapInvoice contains a UrlAction element referencing a custom application page called DevLeapInvoiceChangeStatus.aspx.

To create such pages using Visual Studio 2012, you can simply add a new item to the project and then select an item of type Application Page, which is an ASPX file. A folder named Layouts will be added to the project, if it does not already exist. Within that folder, a subfolder will be created, using the name of your project. The new ASPX file will be placed in that subfolder. The ASPX file will define a standard ASP.NET page, which you will be able to define using standard ASP.NET controls, custom SharePoint controls, or custom controls of your own. By default, the page will have a DynamicMasterPageFile attribute with a value of ~masterurl/default.master, but you can freely change this behavior. In addition, the CodeBehind attribute of the page will reference a code file declaring a custom ASP.NET page that will inherit from the LayoutsPageBase class, which is defined in the Microsoft.SharePoint.WebControls namespace and defines the base and common behavior for every application page. The LayoutsPageBase base class provides some useful properties to directly access the SPWeb and SPSite instances of the current context.

In A CustomAction element targeting the ECB of items with a content type of DevLeapInvoice, the custom application page used in the UrlAction element was capable of changing the Status field of a single item with a content type of DevLeapInvoice, reading the target ListId, ItemId, and Status from the QueryString. The source code behind the DevLeapInvoiceChangeStatus.aspx page used in A CustomAction element targeting the ECB of items with a content type of DevLeapInvoice reveals the source code behind that page.

using System;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;
using System.Web;
using Microsoft.SharePoint.Utilities;
namespace DevLeap.SP2013.UIExtensions.Layouts.DevLeap.SP2013.UIExtensions {
    public partial class DevLeapInvoiceChangeStatus : LayoutsPageBase {
        protected void Page_Load(object sender, EventArgs e) {
            String itemId = this.Request.QueryString["ItemId"];
            String listId = this.Request.QueryString["ListId"];
            String status = this.Request.QueryString["Status"];
            if (!String.IsNullOrEmpty(itemId) &&
                !String.IsNullOrEmpty(listId) &&
                !String.IsNullOrEmpty(status)) {
                SPWeb web = this.Web;
                try {
                    try {
                      SPList list =
                        web.Lists[new Guid(this.Request.QueryString["ListId"])];
                      SPListItem item =
                        list.GetItemById(
                          Int32.Parse(this.Request.QueryString["ItemId"]));
                      web.AllowUnsafeUpdates = true;
                      item[FieldsIds.DevLeapInvoiceStatus_ID] = status;
                      item.Update();
                      SPUtility.Redirect(
                        list.DefaultViewUrl,
                        SPRedirectFlags.Default,
                        HttpContext.Current);
                    }
                   finally {
                        web.AllowUnsafeUpdates = false;
                    }
                }
                catch (ArgumentException) {
                    throw new ApplicationException("Invalid List or Item ID!");
                }
            }
        }
    }
}

The ASPX code of the DevLeapInvoiceChangeStatus.aspx page is not terribly interesting because it has no content. However, a classic custom application page should define only the content regions to fill out the content placeholders defined in the master page used by the target site.

Sometimes you need to deploy pages that do not need to be shared and available on any site of your farm. Instead, you simply need to deploy a custom page or Web Part page to a single target site, eventually supporting customization by the end user or by using SharePoint Designer 2013.

To accomplish this task, you can use the Module feature element, which enables you to deploy an item into the content database of a target site. The structure of the Module feature element, together with its child elements shows the structure of the Module element, together with its child elements.

<Module
  HyperlinkBaseUrl = string
  IncludeFolders = "Text"
  List = "Integer"
  Name = "Text"
  Path = "Text"
  RootWebOnly = "TRUE" | "FALSE"
  SetupPath = "Text"
  Url = "Text">
 <File
    DocumentTemplateForList = string
    DoGUIDFixUp = "TRUE" | "FALSE"
    IgnoreIfAlreadyExists = "TRUE" | "FALSE"
    Level = Draft
    Name = string
    NavBarHome = "TRUE" | "FALSE"
    Path = string
    Type = "Ghostable" | "GhostableInLibrary"
    Url = string>
      <AllUsersWebPart />
      <BinarySerializedWebPart />
      <NavBarPage />
      <Property />
      <View />
      <WebPartConnection />
  </File>
</Module>

The code in The structure of the Module feature element, together with its child elements is made up of a small set of attributes, while the core part is made of the child File element. Table 12-6 provides explanations of the main attributes of the Module element.

Moreover, Table 12-7 provides explanations of each attribute available for the File element.

A Module feature to deploy an image into the Site Assets library of a SharePoint site shows how to deploy a custom image into the Site Assets library of a SharePoint site by using the Module feature.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Module Name="SiteAssetsImage" Url="SiteAssets">
    <File IgnoreIfAlreadyExists="True"
          Path="SiteAssetsImageDevLeap-Icon-48x48.png"
          Url="DevLeap-Icon-48x48.png"
          Type="GhostableInLibrary" />
  </Module>
</Elements>

You can also use the Module feature for deploying a content page, eventually to be made up of Web Parts. If you need to deploy an ASPX content page only, you can use an element manifest file, such as the one shown in A Module feature used to deploy a content page on a SharePoint site.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Module Name="SampleContentPage">
    <File IgnoreIfAlreadyExists="True"
          Path="SampleContentPageSampleContentPage.aspx"
          Url="SampleContentPage.aspx" />
  </Module>
</Elements>

The code in A Module feature used to deploy a content page on a SharePoint site provisions a page with a URL value of SampleContentPage.aspx under the root of the target site, reading the page content from a file stored in the feature’s folder, under the relative path SampleContentPageSampleContentPage.aspx. The source code of the page SampleContentPage.aspx provisioned in A Module feature used to deploy a content page on a SharePoint site presents the source code of that page.

<%@ Page language="C#" MasterPageFile="~masterurl/default.master" %>
<asp:Content ID="Content1" ContentPlaceHolderId="PlaceHolderPageTitle" runat="server">
    This is the SampleContentPage Title
</asp:Content>
<asp:Content ID="Content2" ContentPlaceHolderId="PlaceHolderPageTitleInTitleArea"
runat="server">
    This is the SampleContentPage Title in Title Area
</asp:Content>
<asp:Content ID="Content7" ContentPlaceHolderId="PlaceHolderPageDescription"
runat="server">
    This is the description of the SampleContentPage
</asp:Content>
<asp:Content ID="Content12" ContentPlaceHolderId="PlaceHolderMain" runat="server">
    This is the main body of the SampleContentPage
</asp:Content>

If the page you are going to provision is a Web Part page, that means it is made up of Web Parts; the File element supports some child elements specifically available for including Web Parts in a Web Part page. Now consider the ASPX page illustrated in A Web Part page provisioned through a Module feature. It defines a page that includes a WebPartZone control with an ID of MainWebPartZone placed in the PlaceHolderMain content region.

<%@ Page language="C#" MasterPageFile="~masterurl/default.master"
Inherits="Microsoft.SharePoint.WebPartPages.WebPartPage,
Microsoft.SharePoint,Version=15.0.0.0,Culture=neutral,PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls"
Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral,
PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="Utilities" Namespace="Microsoft.SharePoint.Utilities"
Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral,
PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="WebPartPages" Namespace="Microsoft.SharePoint.WebPartPages"
Assembly="Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral,
PublicKeyToken=71e9bce111e9429c" %>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Assembly Name="Microsoft.Web.CommandUI, Version=15.0.0.0, Culture=neutral,
PublicKeyToken=71e9bce111e9429c" %>
<asp:Content ID="Content1" ContentPlaceHolderId="PlaceHolderPageTitle" runat="server">
  <SharePoint:ListItemProperty ID="ListItemProperty1" Property="BaseName"
    maxlength="40" runat="server"/>
</asp:Content>
<asp:Content ID="Content12" ContentPlaceHolderId="PlaceHolderMain" runat="server">
  <table cellpadding="4" cellspacing="0" border="0" width="100%">
    <tr>
      <td id="_invisibleIfEmpty" name="_invisibleIfEmpty" valign="top" width="100%">
        <WebPartPages:WebPartZone runat="server" Title="loc:FullPage"
          ID="MainWebPartZone" FrameType="TitleBarOnly" />
      </td>
    </tr>
  </table>
</asp:Content>

The Module element defined in The feature element manifest used to provision a Web Part page, together with some Web Parts automatically provisions the page from A Web Part page provisioned through a Module feature into the library Site Pages, adding two Web Parts into the WebPartZone with ID MainWebPartZone. The key point is the inclusion of the AllUsersWebPart child elements in the File element. The first one defines an instance of the standard ImageWebPart of SharePoint. The second child element references the HelloWorldWebPart that was defined at the beginning of Chapter 11.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <Module Name="SampleWebPartPage" Url="SitePages">
    <File IgnoreIfAlreadyExists="True"
          Path="SampleWebPartPageSampleWebPartPage.aspx"
          Url="SampleWebPartPage.aspx"
          Type="GhostableInLibrary">
      <AllUsersWebPart WebPartZoneID="MainWebPartZone" WebPartOrder="1">
        <![CDATA[
          <WebPart xmlns="http://schemas.microsoft.com/WebPart/v2"
            xmlns:iwp="http://schemas.microsoft.com/WebPart/v2/Image">
              <Assembly>Microsoft.SharePoint, Version=15.0.0.0, Culture=neutral,
                  PublicKeyToken=71e9bce111e9429c</Assembly>
              <TypeName>Microsoft.SharePoint.WebPartPages.ImageWebPart</TypeName>
              <FrameType>None</FrameType>
              <Title>$Resources:wp_SiteImage;</Title>
<iwp:ImageLink>/_layouts/images/homepageSamplePhoto.jpg</iwp:ImageLink>
              <iwp:AlternativeText>Home Page Sample Photo</iwp:AlternativeText>
          </WebPart>
        ]]>
      </AllUsersWebPart>
      <AllUsersWebPart WebPartZoneID="MainWebPartZone" WebPartOrder="2">
        <![CDATA[
          <webParts>
            <webPart xmlns="http://schemas.microsoft.com/WebPart/v3">
              <metaData>
                <type name="DevLeap.SP2013.WebParts. HelloWorldWebPart.
HelloWorldWebPart, DevLeap.SP2013.WebParts, Version=1.0.0.0, Culture=neutral,
PublicKeyToken=a7081b3b197bafe2" />
                <importErrorMessage>Cannot import this Web Part.
</importErrorMessage>
              </metaData>
              <data>
                <properties>
                  <property name="Title" type="string">Hello World Web Part
</property>
                </properties>
              </data>
            </webPart>
          </webParts>
        ]]>
      </AllUsersWebPart>
    </File>
  </Module>
</Elements>

Notice also that the syntax for declaring the two Web Parts is different. In fact, the former is a legacy Web Part that supports the old-style DWP Web Part deployment technique available since SharePoint 2003, while the latter uses the syntax of the new WEBPART deployment files available since SharePoint 2010.

The File element supports some other child elements. For example, it supports the View child element, which can be used to instantiate a ListView into the target Web Part page. Additionally, it supports the WebPartConnection element to connect Web Parts directly during the provisioning process.

Keep in mind that extending a site using custom pages and custom content directly deployed into the content database is a habit that Microsoft started to discourage with SharePoint 2013. In fact, you should use the new app model available in SharePoint 2013, which Part III of this book, “Developing SharePoint apps,” discusses.