Kontrolka DelegateControl

Zdarzają się momenty, w których chcielibyśmy dodać do strony dodatkową funkcjonalność, czy zmienić wygląd strony. Nie możemy jednak utworzyć nowej lub zmodyfikować już istniejącej strony wzorcowej (master page), bo np. klient sobie tego nie życzy albo wiązałoby się to z dużym nakładem pracy. Właśnie w takim celu powstała kontrolka DelegateControl.

Jest to mechanizm działający jako kontener. Umożliwia on wstrzyknięcie kontrolki/kontrolek w miejscu, gdzie kontrolka DelegateControl  występuje. Podczas otwierania strony kontrolka DelegateControl szuka zarejestrowanych kontrolek. W przypadku znalezienia kontrolek, w zależności od ustawień kontrolki DelegateControl, w ich miejsce renderowana jest albo jedna, albo wszystkie.

W ten sposób, poprzez dodanie własnych wpisów lub wykorzystaniu już istniejących, na stronie wzorcowej można dodać nowe funkcjonalności do wszystkich stron korzystających z danej strony wzorcowej.

Zatem zaczynajmy.

Każda “pudełkowa” strona wzorcowa w bloku HEAD zawiera wpis:

<SharePoint:DelegateControl runat="server"

ControlId="AdditionalPageHead"

AllowMultipleControls="true"/>

gdzie:

ControlId – id identyfikujące kontrolkę DelegateControl,

AllowMultipleControls – określa, czy kontrolka DelegateControl może wyrenderować kilka kontrolek czy tylko jedną.

Jako przykład przygotujemy kontrolkę dodającą arkusz stylu CSS ukrywającego lewe menu boczne.

Pozwoli to sprawdzić w prosty sposób, czy kod działa. Poza tym, bazując na moim doświadczeniu, klienci nad wyraz często chcą by to menu było ukryte.

Na początek utworzymy nową, farmową solucję SharePoint’ową BlogerSii.Examples.DelegateControl.

W Visual Studio dodaj SharePoint’owy folder „Layouts”

Następnie dodaj do niego plik arkuszu stylów CSS „HideMenu.css”.

Wklej do nowo utworzonego pliku definicji stylu:

#sideNavBox { 
display:none; 
}

W Visual Studio dodaj nowy User Control HideSideMenuControl.ascx

Do pliku HideSideMenuControl.ascx dodaj wpis:

<link rel="stylesheet" href="/_layouts/15/DelegateControl/HideMenu.css" />

Mamy już kontrolkę – teraz trzeba ją wykorzystać.

Służy do tego odpowiednio przygotowany dokument XML.

W Visual Studio dodaj „Empty Element”. W Elements.xml dodaj wpis:

<Control Id="AdditionalPageHead" Sequence="90" ControlSrc="~/_CONTROLTEMPLATES/15/DelegateControl/HideSideMenuControl.ascx " />

Tak przygotowany dokument XML pozwala na powiązanie kontrolki ASP.NET z kontrolką DelegateControl, gdzie:

ID – definiuje, która kontrolka DelegateControl ma wyrenderować naszą kontrolkę,

Sequence – w przypadku, gdy kontrolka DelegateControl nie ma flagi AllowMultipleControls ustawionej na „true” lub w ogóle jej nie ma, o tym, która kontrolka zostanie wstrzyknięta, decyduje sequence – wygrywa ta, która ma najniższą wartość,

ControlSrc – lokalizacja wstrzykiwanego elementu.

Utworzony element należy dodać do funkcji (feature) o zakresie (scope) „Web”.

Zasięg elementu jest zależny od zakresu (scope) funkcji (feature), do której dodajemy element z naszym plikiem XML:

• Farm – cała farma,
• WebApp – web aplikacja,
• Site – kolekcja witryn,
• Web – konkretna witryna.

Efekt przed:

Efekt po:

Jak widać nasz arkusz stylów CSS został dodany, menu boczne zniknęło.

Wykorzystanie kontrolki DelegateControl w SharePoint’cie jest bardzo prostym i efektywnym sposobem na dokonanie zmian o dużym zasięgu.

Efektem końcowym naszego przykładu było dodanie arkusza stylów CSS, jednak możliwości jakie daje to rozwiązanie są ograniczone jedynie przez API i wyobraźnię samego programisty.