SharePoint 2013 Apps: Schnellstartleiste im App Web

Bei der Suche im Web nach einer Möglichkeit die Schnellstartleiste (Quicklaunch) auch im App Web verwenden zu können, bin ich auf viele nicht funktionierende "Lösungen" gestossen. Zumindest bei mir hatte keines der meist identischen Beispiele die erwünschte Wirkung erzielt. Offenbar haben hier viele Blogger ohne zu testen einfach nur voneinander abgeschrieben. Nach ein wenig Probieren habe ich dann aber selbst eine funktionierende Lösung gefunden.

Für das App Web wird standardmäßig die Gestaltungsvorlage (Master Page) app.master verwendet und bei der ist die Schnellstartleiste ausgeblendet. Wenn man diese verwenden möchte, muß man also eine eigene Gestaltungsvorlage verwenden. Wie das geht, habe ich hier beschrieben.

Man sucht jetzt einfach in der eigenen Gestaltungsvorlage nach PlaceHolderLeftNavBar. Standardmäßig ist dieser Platzhalter leer. Den leeren Platzhalter überschreibt man mit folgendem:

<asp:ContentPlaceHolder id="PlaceHolderLeftNavBar" runat="server">
 
<div>
    <asp:SiteMapDataSource SiteMapProvider="SPNavigationProvider"
                           ShowStartingNode="False"
                           id="QuickLaunchSiteMap"
                           StartingNodeUrl="sid:1025"
                           runat="server"/>
    <SharePoint:AspMenu id="V4QuickLaunchMenu"
                        runat="server"
                        EnableViewState="false"
                        DataSourceId="QuickLaunchSiteMap"
                        UseSimpleRendering="true"
                        Orientation="Vertical"
                        StaticDisplayLevels="3"
                        AdjustForShowStartingNode="true"
                        MaximumDynamicDisplayLevels="2"
                        SkipLinkText=""
                        CssClass="s4-ql"/>
  </div>
</asp:ContentPlaceHolder>

Das reicht bereits, um die Schnellstartleiste anzuzeigen. Allerdings gibt es jetzt noch ein Problem: der Inhaltsbereich rutscht jetzt auf manchen Seiten unter die Schnellstartleiste, anstatt rechts daneben angezeigt zu werden. Um das zu beheben, muß man dem <div>, das in der Gestaltungsvorlage direkt darunter notiert ist, einen Abstand per Inline-Style zuweisen:

<div id="contentBox" aria-live="polite" aria-relevant="all" style="margin-left: 250px;">

SharePoint 2013 Apps: Eigene Gestaltungsvorlage verwenden

Wenn eine App für SharePoint ein in SharePoint gehostetes App Web benutzt, kann man für dieses eine eigene Gestaltungsvorlage (Master Page) benutzen. Ohne weiteres Zutun verwendet SharePoint für App Webs die Standard-Gestaltungsvorlage app.master.

Dieser Beitrag zeigt die Vorgehensweise anhand einer SharePoint-hosted App, aber es funktioniert genauso bei cloud-basierten Apps, die ein App Web benutzen, z.B. um dort eigene Listen für die Datenhaltung anzulegen.

Gestaltungsvorlage hinzufügen

Wir müssen zunächst die zu verwendende Gestaltungsvorlage in das Visual Studio Projekt aufnehmen. Dazu legen wir im Projekt, das die App repräsentiert, ein neues Element vom Typ Module an (z.B. durch Rechtsklick auf das Projekt – Add New Item Module). Wichtig ist, daß das wirklich im App-Projekt geschieht (das ist das, welches die AppManifest.xml enthält) und nicht in dem Projekt, das die Remote-Komponenten von cloud-basierten Apps enthält. Bei einer SharePoint-hosted App gibt es in Visual Studio ohnehin nur dieses eine Projekt.

Beim Hinzufügen eines Modules legt Visual Studio automatisch eine Sample.txt Datei an. Sie kann einfach gelöscht werden.

Als Ausgangsbasis für die eigene Gestaltungsvorlage empfiehlt es sich die standardmäßig verwendete app.master zu benutzen. Man findet sie auf einem SharePoint 2013 Server unter 15\TEMPLATE\GLOBAL. Zum Hinzufügen der Datei in Visual Studio gibt es jetzt zwei Möglichkeiten. Man fügt entweder eine neue Textdatei ein, nennt sie z.B. myapp.master und fügt dann per Kopieren und Einfügen den Inhalt hinzu. Oder man kopiert gleich die ganze Datei in den Ordner des Modules, benennt sie um und nimmt sie über Add Existing Item ins Projekt auf. Visual Studio nimmt die Datei jetzt automatisch in die Elements.xml des Modules auf:

<Module Name="CustomMaster">
  <File Path="CustomMaster\myapp.master" Url="CustomMaster/myapp.master" ReplaceContent="TRUE" />
</Module>

Hier müssen jetzt diverse Änderungen gemacht werden, damit die Datei in den Katalog für Gestaltungsvorlagen (Master Page Catalog) aufgenommen wird. Dazu fügt man beim Module-Element ein Attribut List="116" und ein Attribut Url="_catalogs/masterpage" hinzu. Beim File-Element wird der Ordnername aus dem Url-Attribut entfernt, das ReplaceContent-Attribut wird komplett entfernt und ein Attribut Type="GhostableInLibrary" wird hinzugefügt. Das Module sieht dann so aus:

<Module Name="CustomMaster" List="116" Url="_catalogs/masterpage">
 
<File Path="CustomMaster\myapp.master" Url="myapp.master" Type="GhostableInLibrary" />
</Module>

Damit haben wir jetzt schonmal erreicht, daß die Datei im Gestaltungsvorlagenkatalog bereitgestellt wird.

Gestaltungsvorlage verwenden

In einzelnen Seiten

Wenn es hier nur um eigene Seiten, wie z.B. die von Visual Studio automatisch angelegte Default.aspx geht, kann man die zu verwendende Gestaltungsvorlage einfach in der jeweiligen Datei angeben. Standardmäßig steht dort (in der @Page-Direktive)

MasterPageFile="~masterurl/default.master"

Das ersetzt man durch

MasterPageFile="~site/_catalogs/masterpage/myapp.master"

Und schon verwendet die Seite unsere eigene Gestaltungsvorlage.

In allen Seiten

Schwieriger wird das Ganze wenn alle Seiten automatisch die neue Gestaltungsvorlage übernehmen sollen. Wenn man z.B. im App Web eigene Listen hat, sollen die zur Liste gehörenden Ansichts- und Formularseiten ebenfalls die neue Gestaltungsvorlage verwenden. Um das zu erreichen, erstellt man auch noch eine eigene Websitevorlage (Site Template) für das App Web.

Ähnlich wie bei der Gestaltungsvorlage selbst, erstellt man im Projekt ein neues Module, fügt die standardmäßig verwendete ONET.XML ein und modifiziert sie. Die Standardvorlage findet man ebenfalls auf jedem SharePoint 2013 Server im Ordner 15\TEMPLATE\SiteTemplates\App\Xml. Die Datei ONET.XML fügt man im Module ein. Wichtig: sie darf nicht umbenannt werden!

In der Datei müssen jetzt noch Änderungen gemacht werden. Beim Element Project/Configurations/Configuration muß das Name-Attribut geändert und der Pfad im MasterUrl-Attribut angepaßt werden:

MasterUrl="_catalogs/masterpage/myapp.master"

Hier noch ein Screenshot zur Verdeutlichung der Anpassungen:

Die neue Vorlage muß jetzt noch also solche bekannt gemacht werden. Dies geschieht durch ein WebTemplate-Element, das in die Elements-xml des Modules eingefügt wird, das die ONET.XML enthält. Dazu fügt man innerhalb von Elements, aber außerhalb von Module folgendes ein:

<WebTemplate BaseTemplateID="1" BaseConfigurationID="0" BaseTemplateName="APP" Name="CustomTemplate" ProductVersion="15" DisplayCategory="Custom" Description="Web template for Custom Apps."></WebTemplate>

Es sollte also so aussehen:

Wichtig ist dabei, daß das Name-Attribut beim WebTemplate-Element exakt dem Name-Attribut des Module-Elements entspricht!

Als letzten Schritt müssen wir jetzt noch der App mitteilen, daß wir das App Web aus unserer Vorlage erstellen wollen. Das geht über die AppManifest.xml, die durch einen Rechtsklick in der Codeansicht geöffnet wird (nicht mit dem Manifest-Designer). In die Datei fügt man jetzt innerhalb von Properties folgendes ein:

<WebTemplate Id="{6393fe60-d014-4ed1-9153-518538c562a3}#CustomTemplate"></WebTemplate>

Es sollte so aussehen:

Der Inhalt des Id-Attributs setzt sich so zusammen:

  • Öffnende geschweifte Klammer

  • Feature-ID (s.Erklärung unten)

  • Schließende geschweifte Klammer

  • Raute/Hash-Zeichen #

  • Der Name des WebTemplates bzw. des Modules (s.o.)

Als Feature-ID muß die Id des Features angegeben werden, das die Vorlage enthält. Man bekommt sie, indem man das Feature in Visual Studio per Doppelklick öffnet und dann oberhalb des Designers auf Manifest umschaltet:

Test

Um das Ganze zu testen, machen wir jetzt eine Änderung in unserer Gestaltungsvorlage und schauen dann, ob diese Änderung in der bereitgestellten App auch sichtbar ist. Man kann dazu eine beliebige Änderung vornehmen. Ich habe einfach oberhalb des Inhaltsbereichs einen festen Text eingefügt:

In Visual Studio F5 gedrückt und siehe da, es funktioniert:

Vorsicht mit KB2817630

Und schon wieder die Warnung vor einem aktuellen Microsoft-Update. Nachdem erst vor Kurzem ein Update veröffentlich wurde, das Datenansichten in SharePoint unbenutzbar machen konnte, gibt es jetzt schon wieder ein Problem mit einem aktuellen Update vom 10.09.2013. KB2817630 sorgt dafür, daß die Ordneransicht in Outlook 2013 leer bleibt.

Einzige Abhilfe schafft nach derzeitigem Kenntnisstand einzig die Deinstallation dieses Updates. Achtung: bei mir erschien dieses Update zweimal unter den installierten Updates und ich mußte auch beide einzeln deinstallieren bis das Problem behoben war. Selbstverständlich mit einem Neustart zwischendurch…