Exemplarische Vorgehensweise: Erstellen eines benutzerdefinierten Webparts mit einer Kontextregisterkarte

  • Artikel

Letzte Änderung: Freitag, 4. Februar 2011

Gilt für: SharePoint Foundation 2010

Inhalt dieses Artikels
Erstellen eines SharePoint-Projekts
Implementieren des Webparts
Erstellen der Seitenkomponente
Bereitstellen der Anpassung

In diesem Thema wird das Erstellen eines benutzerdefinierten Webparts veranschaulicht, das eine Kontextregisterkarte auf dem Menüband für die Serverkomponente in Microsoft SharePoint Foundation öffnet.

Voraussetzungen

Microsoft SharePoint Foundation 2010

SharePoint-Entwicklungstools in Microsoft Visual Studio 2010

Erstellen eines SharePoint-Projekts

Zum Anpassen des Webparts und Menübands erstellen Sie zunächst ein leeres SharePoint-Projekt.

So erstellen Sie ein SharePoint-Projekt

  1. Starten Sie Visual Studio 2010.

  2. Zeigen Sie im Menü Datei auf Neu, und klicken Sie dann auf Projekt.

  3. Wählen Sie in Projekttypen unter C# die Option Leeres SharePoint-Projekt aus.

  4. Geben Sie ContextualTabWebPart als Projektnamen ein, und klicken Sie dann auf OK.

  5. Wählen Sie im Assistenten zum Anpassen von SharePoint die Option Als Farmlösung bereitstellen aus, und klicken Sie dann auf Fertig stellen.

Implementieren des Webparts

Implementieren Sie nun das Webpart.

So implementieren Sie das Webpart

  1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf Verweise, und wählen Sie dann Verweis hinzufügen aus.

  2. Wählen Sie im Dialogfeld Verweis hinzufügen die Registerkarte .NET aus, und wählen Sie dann Microsoft.Web.CommandUI.dll aus. Klicken Sie auf OK.

  3. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt ContextualTabWebPartA, zeigen Sie auf Hinzufügen, und wählen Sie dann Neues Element aus.

  4. Wählen Sie im Dialogfeld Neues Element hinzufügen die Option Webpart aus. Geben Sie ContextualTabWebPart als Namen ein.

  5. Nach dem Hinzufügen des Webparts und dem Anzeigen der Datei ContextualTabWebPart.cs fügen Sie die folgenden Anweisungen hinzu.

    using System.Xml;
using Microsoft.Web.CommandUI;

  6. Implementieren Sie als Nächstes die IWebPartPageComponentProvider-Schnittstelle wie im folgenden Code dargestellt. Sie werden sie später verwenden.

    public class ContextualTabWebPart : WebPart, IWebPartPageComponentProvider

    Im nächsten Schritt erstellen Sie zwei globale Zeichenfolgenvariablen für das Menüband-XML. Diese beiden Variablen definieren die Kontextregisterkarte und die Gruppenvorlagen. Weitere Informationen zu Menüband-XML finden Sie unter XML für das Menüband für die Serverkomponente.

  7. Beachten Sie in der contextualTab-Zeichenfolge das ContextualGroup-Element. Dieses Element definiert das folgende Tab-Element als Kontextregisterkarte. Das Color-Attribut definiert die Farbe der Registerkarte, wenn diese gerendert wird. Id und ContextualGroupId sind eindeutige Bezeichner für die Gruppe. Das Sequence-Attribut definiert, wo die Kontextregisterkarte gerendert wird. Der folgende Code implementiert die beiden globalen Zeichenfolgenvariablen.

    private string contextualTab = @"
   <ContextualGroup Color=""Magenta"" 
     Command=""CustomContextualTab.EnableContextualGroup"" 
     Id=""Ribbon.CustomContextualTabGroup"" 
     Title=""Custom Contextual Tab Group"" 
     Sequence=""502"" 
     ContextualGroupId=""CustomContextualTabGroup"">
          <Tab 
              Id=""Ribbon.CustomTabExample"" 
              Title=""My Custom Tab"" 
              Description=""This holds my custom commands!"" 
              Command=""CustomContextualTab.EnableCustomTab"" 
              Sequence=""501"">
            <Scaling
              Id=""Ribbon.CustomTabExample.Scaling"">
              <MaxSize
                Id=""Ribbon.CustomTabExample.MaxSize"" 
                GroupId=""Ribbon.CustomTabExample.CustomGroupExample"" 
                Size=""OneLargeTwoMedium""/>
              <Scale 
                Id=""Ribbon.CustomTabExample.Scaling.CustomTabScaling""
                GroupId=""Ribbon.CustomTabExample.CustomGroupExample"" 
                Size=""OneLargeTwoMedium"" />
            </Scaling>
            <Groups Id=""Ribbon.CustomTabExample.Groups"">
              <Group 
                Id=""Ribbon.CustomTabExample.CustomGroupExample"" 
                Description=""This is a custom group!"" 
                Title=""Custom Group"" 
                Command=""CustomContextualTab.EnableCustomGroup"" 
                Sequence=""52"" 
                Template=""Ribbon.Templates.CustomTemplateExample"">
                <Controls 
                  Id=""Ribbon.CustomTabExample.CustomGroupExample.Controls"">
                  <Button 
                    Id=""Ribbon.CustomTabExample.CustomGroupExample.HelloWorld"" 
                    Command=""CustomContextualTab.HelloWorldCommand"" 
                    Sequence=""15"" 
                    Description=""Says hello to the World!"" 
                    LabelText=""Hello, World!"" 
                    TemplateAlias=""cust1""/>
                  <Button 
                    Id=""Ribbon.CustomTabExample.CustomGroupExample.GoodbyeWorld"" 
                    Command=""CustomContextualTab.GoodbyeWorldCommand"" 
                    Sequence=""17"" 
                    Description=""Says good-bye to the World!"" 
                    LabelText=""Good-bye, World!"" 
                    TemplateAlias=""cust2""/>
                </Controls>
              </Group>
            </Groups>
          </Tab>
   </ContextualGroup>";
 
        private string contextualTabTemplate = @"
          <GroupTemplate Id=""Ribbon.Templates.CustomTemplateExample"">
            <Layout 
              Title=""OneLargeTwoMedium"" LayoutTitle=""OneLargeTwoMedium"">
              <Section Alignment=""Top"" Type=""OneRow"">
                <Row>
                  <ControlRef DisplayMode=""Large"" TemplateAlias=""cust1"" />
                </Row>
              </Section>
              <Section Alignment=""Top"" Type=""TwoRow"">
                <Row>
                  <ControlRef DisplayMode=""Medium"" TemplateAlias=""cust2"" />
                </Row>
                <Row>
                  <ControlRef DisplayMode=""Medium"" TemplateAlias=""cust3"" />
                </Row>
              </Section>
            </Layout>
          </GroupTemplate>";

  8. Erstellen Sie eine neue Zeichenfolgeneigenschaft namens DelayScript. DelayScript enthält ECMAScript (JavaScript, JScript), mit dem die benutzerdefinierte Seitenkomponente hinzugefügt und registriert wird. Sie erstellen die benutzerdefinierte Seitenkomponente nachfolgend in diesem Thema. Mit der _addCustomPageComponent-Methode wird die benutzerdefinierte Seitenkomponente erstellt und dem Seiten-Manager hinzugefügt. Jedes Webpart besitzt eine Seitenkomponente, und beim Erstellen eines benutzerdefinierten Seitenkomponentenobjekts wird die Seitenkomponenten-ID des Webparts verwendet. Dies ist erforderlich, damit das Webpart der Seitenkomponente zugeordnet werden kann und damit kontextabhängig zur benutzerdefinierten Menübandregisterkarte gewechselt werden kann. Mit der _registerCustomPageComponent-Methode wird die JavaScript-Datei beim Laden der Seite registriert.

    Der folgende Code implementiert DelayScript.

            public string DelayScript 
        {
            get
            {
                string webPartPageComponentId = SPRibbon.GetWebPartPageComponentId(this);
                return @"
<script type=""text/javascript"">
//<![CDATA[
 
            function _addCustomPageComponent()
            {
                var _customPageComponent = new ContextualTabWebPart.CustomPageComponent('" + webPartPageComponentId + @"');
                SP.Ribbon.PageManager.get_instance().addPageComponent(_customPageComponent);
            }
 
            function _registerCustomPageComponent()
            {
                SP.SOD.registerSod(""CustomContextualTabPageComponent.js"", ""\/_layouts\/CustomContextualTabPageComponent.js"");
                SP.SOD.executeFunc(""CustomContextualTabPageComponent.js"", ""ContextualWebPart.CustomPageComponent"", _addCustomPageComponent);
            }
            SP.SOD.executeOrDelayUntilScriptLoaded(_registerCustomPageComponent, ""sp.ribbon.js"");
//]]>
</script>";
            }
        }

  9. Erstellen Sie eine neue Funktion namens AddContextualTab. Fügen Sie innerhalb der AddContextualTab-Methode Code zum Registrieren der Kontextregisterkarte und der benutzerdefinierten Vorlagen für das Menüband ein. Mit der RegisterDataExtension(XmlNode, String)-Methode werden Menübanderweiterungen registriert. RegisterDataExtension(XmlNode, String) informiert das Menüband darüber, wo das übergebene XML geladen werden soll. Sie verwenden die IDs der Elemente ContextualTabs und Templates in der Datei CMDUI.xml.

    Der folgende Code implementiert die AddContextualTab-Methode.

            private void AddContextualTab()
        {
 
            // Get the current instance of the ribbon on the page.
            Microsoft.Web.CommandUI.Ribbon ribbon = SPRibbon.GetCurrent(this.Page);
 
            // Prepare an XmlDocument object used to load the ribbon extensions.
            XmlDocument ribbonExtensions = new XmlDocument();
 
            // Load the contextual tab XML and register the ribbon extension.
            ribbonExtensions.LoadXml(this.contextualTab);
            ribbon.RegisterDataExtension(ribbonExtensions.FirstChild, "Ribbon.ContextualTabs._children");
 
            // Load the custom templates and register the ribbon extension.
            ribbonExtensions.LoadXml(this.contextualTabTemplate);
            ribbon.RegisterDataExtension(ribbonExtensions.FirstChild, "Ribbon.Templates._children");
        }

  10. Nun müssen Sie die WebPartContextualInfo-Eigenschaft der IWebPartPageComponentProvider-Schnittstelle implementieren. Zum Implementieren der Schnittstelle klicken Sie mit der rechten Maustaste auf IWebPartPageComponentProvider,, wählen Sie Schnittstelle implementieren und dann Schnittstelle explizit implementieren aus.

    Mit dieser Schnittstelle wird das Menüband darüber informiert, dass ein Webpart ausgewählt wurde und welche Kontextgruppe und -registerkarte angezeigt werden soll. Beim Hinzufügen der Kontextgruppe senden Sie die ID der Kontextgruppe, den VisibilityContext-Wert und Command. Die ID ist der Id-Eigenschaft des ContextualGroup-Elements im Menüband-XML zugeordnet. Der VisibilityContext-Wert wird zum Gruppieren von Steuerelementen verwendet, um diese ein- oder auszublenden. Der Command-Parameter ist dem Command-Wert des ContextualGroup-Elements im Menüband-XML zugeordnet. Sie fügen auch die Registerkarte hinzu, die im Menüband-XML definiert wurde. Sie müssen nur die Parameter Id und VisibilityContext für die Registerkarte übergeben. Fügen Sie den folgenden Code für WebPartContextualInfo ein.

            public WebPartContextualInfo WebPartContextualInfo
        {
            get 
            {
                WebPartContextualInfo info = new WebPartContextualInfo();
                WebPartRibbonContextualGroup contextualGroup = new WebPartRibbonContextualGroup();
                WebPartRibbonTab ribbonTab = new WebPartRibbonTab();
 
                // Create the contextual group object and initialize its values.
                contextualGroup.Id = "Ribbon.CustomContextualTabGroup";
                contextualGroup.Command = "CustomContextualTab.EnableContextualGroup";
                contextualGroup.VisibilityContext = "CustomContextualTab.CustomVisibilityContext";
 
                // Create the tab object and initialize its values.
                ribbonTab.Id = "Ribbon.CustomTabExample";
                ribbonTab.VisibilityContext = "CustomContextualTab.CustomVisibilityContext";
 
                // Add the contextual group and tab to the WebPartContextualInfo.
                info.ContextualGroups.Add(contextualGroup);
                info.Tabs.Add(ribbonTab);
                info.PageComponentId = SPRibbon.GetWebPartPageComponentId(this);
 
                return info;
            }
        }

  11. Im nächsten Schritt implementieren Sie die OnPreRender-Methode. Dies ermöglicht Ihnen das Hinzufügen von Elementen zum Menüband, bevor es auf der Seite gerendert wird. Innerhalb von OnPreRender rufen Sie die AddContextualTab-Methode auf und registrieren DelayScript mit ClientScriptManager.

    Der folgende Code implementiert die OnPreRender-Methode.

            protected override void OnPreRender(EventArgs e)
        {
            base.OnPreRender(e);
 
            this.AddContextualTab();
 
            ClientScriptManager clientScript = this.Page.ClientScript;
            clientScript.RegisterClientScriptBlock(this.GetType(), "ContextualTabWebPart", this.DelayScript);
 
        }

    Das Webpart ist abgeschlossen. Im nächsten Schritt erstellen Sie die Seitenkomponente.

Erstellen der Seitenkomponente

Bei einer Seitenkomponente handelt es sich um ein JavaScript-Objekt, das zur Interaktion mit dem Menüband für die Serverkomponente verwendet wird. Eine ausführliche exemplarische Vorgehensweise zur Seitenkomponente finden Sie unter Entwickeln von Seitenkomponenten für das Menüband für die Serverkomponente. Damit die Seitenkomponente korrekt ausgeführt wird, müssen Sie sie mithilfe eines Moduls dem Verzeichnis %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\\TEMPLATES\LAYOUTS hinzufügen. Dadurch werden Befehle auf dem Menüband aktiviert, und es wird auf die Befehle reagiert, die Sie im Menüband-XML definieren.

So können Sie die Seitenkomponente hinzufügen und definieren

  1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt ContextualTabWebPartA, zeigen Sie auf Hinzufügen, und wählen Sie dann Neues Element aus.

  2. Wählen Sie im Dialogfeld Neues Element hinzufügen die Vorlage Modul aus, und geben Sie CustomContextualTabPageComponent als Namen ein. Klicken Sie auf Hinzufügen.

  3. Die hinzugefügten Standarddateien benötigen Sie nicht. Löschen Sie im Projektmappen-Explorer Elements.xml und Sample.txt.

  4. Nun müssen Sie die JavaScript-Datei hinzufügen. Klicken Sie mit der rechten Maustaste auf CustomContextualTabPageComponent, zeigen Sie auf Hinzufügen, und wählen Sie Neues Element aus.

  5. Wählen Sie unter Visual C# in der Liste Installierte Vorlagen die Option Web aus. Wählen Sie den Typ JScript-Datei aus, und geben Sie CustomContextualTabPageComponent als Namen ein.

  6. Sie müssen den Bereitstellungsspeicherort festlegen, um sicherzustellen, dass die Datei im Verzeichnis _layouts gespeichert wird. Wählen Sie hierzu im Projektmappen-Explorer CustomContextualTabPageComponent.js aus. Legen Sie im Fenster Eigenschaften die Option Bereitstellungstyp auf Stammdatei fest. Öffnen Sie die Deployment Location-Eigenschaft, und geben Sie TEMPLATE\LAYOUTS in die Path-Eigenschaft ein.

    Fügen Sie den folgenden Code der Datei CustomContextualTabPageComponent.jshinzu, um die benutzerdefinierte Seitenkomponente zu implementieren.

    Type.registerNamespace('ContextualTabWebPart');
 
var _webPartPageComponentId;
ContextualTabWebPart.CustomPageComponent = function ContextualTabWebPart_CustomPageComponent(webPartPcId) {
    this._webPartPageComponentId = webPartPcId;
    ContextualTabWebPart.CustomPageComponent.initializeBase(this);
}
ContextualTabWebPart.CustomPageComponent.prototype = {
 
    init: function ContextualTabWebPart_CustomPageComponent$init() {  },
 
    getFocusedCommands: function ContextualTabWebPart_CustomPageComponent$getFocusedCommands() {
        return ['CustomContextualTab.EnableCustomTab', 'CustomContextualTab.EnableCustomGroup', 'CustomContextualTab.HelloWorldCommand', 'CustomContextualTab.GoodbyeWorldCommand'];
    },
 
    getGlobalCommands: function ContextualTabWebPart_CustomPageComponent$getGlobalCommands() {
        return [];
    },
 
    isFocusable: function ContextualTabWebPart_CustomPageComponent$isFocusable() {
        return true;
    },
    
    canHandleCommand: function ContextualTabWebPart_CustomPageComponent$canHandleCommand(commandId) {
        // Contextual Tab commands
        if ((commandId === 'CustomContextualTab.EnableCustomTab') || (commandId === 'CustomContextualTab.EnableCustomGroup') || (commandId === 'CustomContextualTab.HelloWorldCommand') || (commandId === 'CustomContextualTab.GoodbyeWorldCommand')) {
            return true;
        }
    },
 
    handleCommand: function ContextualTabWebPart_CustomPageComponent$handleCommand(commandId, properties, sequence) {
 
        if (commandId === 'CustomContextualTab.HelloWorldCommand') {
            alert('Hello, world!');
        }
        if (commandId === 'CustomContextualTab.GoodbyeWorldCommand') {
            alert('Good-bye, world!');
        }
    },
 
    getId: function ContextualTabWebPart_CustomPageComponent$getId() {
        return this._webPartPageComponentId;
    }
}
 
 
ContextualTabWebPart.CustomPageComponent.registerClass('ContextualTabWebPart.CustomPageComponent', CUI.Page.PageComponent);
SP.SOD.notifyScriptLoadedAndExecuteWaitingJobs("CustomContextualTabPageComponent.js");

Bereitstellen der Anpassung

Das Projekt wird automatisch von den SharePoint-Entwicklungstools in Visual Studio 2010 bereitgestellt. Der Anwendungspool wird automatisch als Teil des Bereitstellungsprozesses zurückgesetzt.

So stellen Sie das Webpart bereit

  1. Drücken Sie F5. Das Webpart und die JavaScript-Datei werden von den SharePoint-Entwicklungstools in Visual Studio 2010 automatisch erstellt und bereitgestellt.

  2. Wechseln Sie zu Ihrer Website.

  3. Klicken Sie auf die Schaltfläche Bearbeiten.

  4. Klicken Sie auf der Registerkarte Einfügen auf die Schaltfläche Webpart.

  5. Wählen Sie in Hinzufügen von Webparts die Kategorie Benutzerdefiniert aus.

  6. Wählen Sie in der Liste der Webparts ContextualTabWebPart aus, und klicken Sie dann auf Hinzufügen.

  7. Nachdem das Webpart der Seite hinzugefügt wurde, klicken Sie auf das Webpart ContextualTabWebPart.

  8. Beachten Sie die angezeigte Registerkarte Custom Contextual Tab Group.

Siehe auch

Konzepte

XML für das Menüband für die Serverkomponente

Entwickeln von Seitenkomponenten für das Menüband für die Serverkomponente

Imperative Anpassung des Menübands der Serverkomponente

Deklarative Anpassung des Menübands der Serverkomponente