Verwendung des DateTime-Picker-Steuerelements

SharePoint stellt zum Bearbeiten von Datums- und Zeitwerten ein schönes Steuerelement zur Verfügung, das DateTimeControl. Dieses Steuerelement kann man auch in eigenen UserControls oder Webparts verwenden. Das Steuer-element befindet sich im Namespace Microsoft.SharePoint.WebControls in der Assembly Microsoft.SharePoint.dll. Dieser Eintrag erläutert welche Schritte beim Einsatz dieses Steuerelements nötig sind, und was man als Entwickler dabei beachten muss.

Grundsätzlich gibt es zwei Möglichkeiten Steuerelemente in WebParts oder UserControls einzubinden. Zum einen kann man das gewünschte Steuerelement im Quellcode eines WepParts oder UserControls instantiieren, zum anderen kann man es direkt im Markup eines UserControls oder einer ASPX-Seite verwenden. In diesem Artikel werde ich beide Varianten kurz vorstellen und zusätzlich auf eventuelle Hürden und Fallstricke beim Einsatz des Steuerelements hinweisen.

DateTimeControl

Verwendung im Quellcode

Um dieses Steuerelement in einem WebPart zu verwenden reichen ein paar kurze Zeilen Code in der CreateChildControls-Methode des WebParts, die das Steuerelement der ControlsCollection desselben hinzufügen:

protected override void CreateChildControls()
{
    base.CreateChildControls();
    ...
    birthdayDateTimeControl = new DateTimeControl();
    birthdayDateTimeControl.ID = "birthdayDateTimeControl" + UniqueID;
    this.Controls.Add(birthdayDateTimeControl);
    ...
}

Beachte, dass der ID des DateTimeControls die UniqueID des WebParts in dem das Steuerelement liegt angehängt wird. Dies ist notwendig um doppelte IDs zu verhindern, sollte ein WebPart zweimal auf einer Seite instantiiert werden.

Braucht man die Referenz auf das Steuerelement später noch an anderer Stelle, ist es natürlich sinnvoll sich die Referenz in einer Klassenvariable außerhalb der CreateChildControls()-Methode zu halten.

Verwendung im Markup

Eine weitere Möglichkeit dieses Steuerelement zu verwenden liegt in der direkten Integration in das Markup (den HTML-Quellcode) beispielsweise eines UserControls. Damit die von SharePoint bereitgestellten Steuerelement überhaupt verwendbar werden ist zunächst ein zusätzlicher Tag-Prefix zu registrieren. Auch hier wird die oben erwähnte Assembly referenziert:

<%@ Register TagPrefix="SharePoint" 
             Namespace="Microsoft.SharePoint.WebControls"
             Assembly="Microsoft.SharePoint, Version=12.0.0.0, 
                       Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>

Anschließend kann das Steuerelement einfach ins Markup des UserControls eingebunden werden.

Verändert man die Eigenschaften des Steuerelements in der Design-Ansicht verändert VisualStudio das dahinter liegende Markup und ergänzt automatisch die zur Anzeige des DateTimeControls verwendeten Steuerelemente. Diese müssen vor dem Ausliefern des UserControls wieder aus dem Markup entfernt werden, da das Steuerelement sonst nicht korrekt funktioniert.[/caution]

Im Gegensatz zum oben erläuterten Einsatz des Steuerelements über den Quellcode brauchen wir hier keine Sorge zu tragen, dass die ID des Steuerelementes seitenweit eindeutig ist. Diese Aufgabe nimmt SharePoint uns dankenswerter Weise ab. Nichtsdestotrotz muss die ID des Steuerelementes innerhalb des UserControls immernoch eindeutig sein!

Netterweise stellt das DateTimeControl bereits einen RequiredFieldValidator zur Verfügung, um zu prüfen ob der Benutzer einen Wert in das Feld eingetragen hat oder nicht. Möchte man allerdings z.B. die Werte zweier DateTimeControls miteinander vergleichen muss man einen kleinen Umweg gehen. Intern werden für jedes DateTimeControl eine TextBox für das Datum und zwei DropDownBoxen für die Stunden und Minuten erzeugt. Die IDs dieser Controls entsprechen jeweils der ID des DateTimeControls mit einem Anhang. Die TextBox für das Datum hat den Anhang “Date”, die DropDownBox für die Stunden den Anhang “DateHours” und die für die Minuten den Anhang “DateMinutes”.

Auf diese Controls kann nun recht einfach zugegriffen werden. Da das anzusprechende Steuerelement aber ein Kindelement des DateTimeControls ist, muss dessen Index dem Validator – getrennt durch ein Dollar-Zeichen ($) ebenfalls mitgegeben werden. Für das Steuerelement “FirstControl”, dessen Datumswert mit dem des Steuerelements “SecondControl” verglichen werden soll, sähe z.B. ein Validator zum Vergleichen zweier Datumswerte folgendermaßen aus:

<asp:CompareValidator ID="MyValidator"
                      ControlToValidate="FirstControl$FirstControlDate"
                      ControlToCompare="SecondControl$SecondControlDate"
                      Type="Date"
                      Operator="GreaterThan"
                      runat="server"
                      ErrorMessage="...">
</asp:CompareValidator>