Kolumne: SharePoint ganz praktisch

Eigene SharePoint-Felder (Teil 1)
Kommentare

Die vergangenen zwei Ausgaben dieser Kolumne widmeten sich der Erstellung und der Verwendung eigener Datenstrukturen in SharePoint. Die heutige Ausgabe beschreibt, mit welchen Möglichkeiten Einfluss auf die Darstellung von Feldern genommen werden kann.

Die Definition und Anlage eigener Datenstrukturen in SharePoint ist für eigene Anwendungen, wie für jede andere nicht SharePoint-Lösung auch, zwingend erforderlich. Die Vorgehensweise ähnelt dabei der Definition eines Datenbankschemas. Wie bei Datenbanktabellen auch existieren in SharePoint verschiedene Datentypen. Wie in der vergangenen Ausgabe bereits gezeigt wurde, enthält jede Felddefinition (Field Definition) das Attribut Type, das Auskunft über den Datentyp des Felds gibt. Die Angabe des Typs wirkt sich auch auf die Darstellung des Felds aus. Ein als DateTime deklariertes Feld wird mithilfe eines Steuerelements zur Datumsauswahl (DateTimePicker Control) dargestellt. Bei dem Feldtyp User wird ein erweitertes Steuerelement ausgegeben, das die Suche nach Benutzern ermöglicht. Abbildung 1 zeigt beispielhaft, wie Typ und verwendetes Steuerelement zusammenhängen.

Abb. 1: Felder in SharePoint

Abb. 1: Felder in SharePoint

In vielen Fällen enthalten die speziellen Steuerelemente auch Validierungsregeln. Wird z. B. ein unbekannter Benutzer in ein Benutzerauswahlfeld (Typ User) eingetragen, gibt das Steuerelement eine Warnmeldung aus (Abb. 2).

Abb. 2: SharePoint-Feldwertvalidierungen

Abb. 2: SharePoint-Feldwertvalidierungen

SharePoint besitzt bereits eine Menge an eingebauten Typen, die für eigene Felder verwendet werden können. Tabelle 1 zeigt eine vollständige Übersicht. Teilweise ergeben sich aber fachliche Anforderungen, die nicht mit den eingebauten Feldern realisierbar sind. Für diese Fälle können eigene Felder umgesetzt werden. Eigene Felder werden immer dann erforderlich, wenn auf die Darstellung oder auch das Verhalten des Felds auf der Oberfläche Einfluss genommen werden muss. Auf die Darstellung kann bereits seit SharePoint 2013 auf zwei verschiedene Arten eingewirkt werden. Vor SharePoint 2013 war hierfür die Anlage eines eigenen serverseitigen Felds erforderlich. SharePoint 2013 eröffnet mit clientseitigen Ausgabevorlagen nun eine neue Möglichkeit, die Darstellung zu ändern. Diese und die nächste Ausgabe der Kolumne beschreiben beide Möglichkeiten anhand konkreter Beispiele.

Tabelle 1: Eingebaute SharePoint-Felder und deren Funktion

Tabelle 1: Eingebaute SharePoint-Felder und deren Funktion

Serverseitige Feldsteuerelemente

Die Möglichkeit der serverseitigen Erstellung eigener SharePoint-Felder ist in SharePoint schon seit langer Zeit möglich. Die zentrale Klasse für serverseitige Felder ist SPField. Diese stellt die Basisklasse aller Felder dar, von der alle in Tabelle 1 dargestellten Felder entweder direkt oder indirekt ableiten. SPField beinhaltet die wesentlichen Eigenschaften, Ereignisse und Methoden, die ein SharePoint-Feld charakterisieren. Eine vollständige Übersicht über alle Mitglieder der Klasse ist hier abrufbar. Bei der programmatischen Erstellung eines neuen Felds kann entweder direkt von SPField oder von einem bereits vorhandenen Feld (Tabelle 1) abgeleitet werden. Innerhalb der Klasse des neuen Felds kann das Verhalten dann durch Überschreiben von Eigenschaften und Methoden an die speziellen Anforderungen angepasst werden.

Erstellung eines einfachen Felds

Das nachfolgende Beispiel zeigt nun, wie ein eigenes Feld umgesetzt und bereitgestellt werden kann. Umgesetzt wird ein validierungsfähiges Eingabefeld für eine Telefonnummer. Das Eingabefeld ist in der Lage zu prüfen, ob das eingegebene Format korrekt ist und die angegebene Vorwahl existiert. Für die Prüfung des Formats wird ein vereinfachter regulärer Ausdruck verwendet. Um die Vorwahl prüfen zu können, wird der Lösung eine Liste aller gültigen Vorwahlen hinzugefügt. Für das Anlegen eines neuen Felds wird zunächst ein neues SharePoint-Projekt in Visual Studio benötigt. Dazu wird Visual Studio gestartet und aus der Kategorie SharePoint 2013 die Projektvorlage Empty SharePoint Project gewählt. Im unteren Feld Name wird dann ein entsprechender Name für das Projekt vergeben und die Projektanlage mit OK bestätigt. Im nächsten Dialogschritt ist als Lösungstyp Deploy as a Farm Solution zu wählen, zusätzlich muss eine gültige SharePoint-Testseite angegeben werden. Danach den Dialog über Finish beenden und dem leeren Projekt eine neue einfache Klasse hinzufügen. Als Klassenname wird hier PhoneTextField verwendet. Die Klasse muss von der Feldklasse SPFieldText abgeleitet werden, wie es Listing 1 zeigt. Die Klasse besitzt zwei Konstruktoren, die jeweils die Parameterwerte an den Basiskonstruktor weiterleiten. Zusätzlich wird die Methode Initialize aufgerufen, die notwendige Feldwerte initialisiert. Zu Beginn der Methode wird eine Textdatei geöffnet, die dem Projekt als eingebettete Ressource hinzugefügt wurde. Die Datei enthält eine Liste mit gültigen Vorwahlen inklusive zugehöriger Stadt. Während der Initialisierungsphase werden die Einträge gelesen und in ein Dictionary gespeichert. Weiterhin werden zwei GetCustomProperty-Aufrufe in der Methode verwendet, um konfigurierbare Feldeinstellungen abzurufen. Diese Einstellungen können bei der Anlage des Felds vom Benutzer festgelegt werden. Abbildung 3 zeigt zur Verdeutlichung das umgesetzte Feld innerhalb der Feldauswahl während der Anlage einer neuen Listenspalte.

Abb. 3: Hinzufügen des neuen Felds

Abb. 3: Hinzufügen des neuen Felds

Die beiden Eingabefelder „Falsches Eingabeformat“ und „Vorwahl nicht vorhanden“ werden auf die entsprechenden Klasseneigenschaften abgebildet. Zur Aufnahme der Werte für die Validierungsmeldungen gibt es innerhalb der Klasse die Eigenschaften MsgAreaCodeNotExist und MsgFormatNotValid.

public class PhoneTextField : SPFieldText
{
  private Dictionary<string, string> vorwahlen = null;
  public PhoneTextField(SPFieldCollection fields, String fieldName)
    : base(fields, fieldName)
  {
    Initialize();
  }
  public PhoneTextField(SPFieldCollection fields, String typeName,
                        String displayName)
    : base(fields, typeName, displayName)
  {
    Initialize();
  }
  private void Initialize()
  {
    Assembly assembly = Assembly.GetExecutingAssembly();
    Stream stream = assembly.GetManifestResourceStream 
                        ("CustomFieldTypes.DataFile.txt");
    vorwahlen = new Dictionary<string, string>();
    using (StreamReader file = new StreamReader(stream))
    {
      string line = string.Empty;
      string[] parts = null;
      while ((line = file.ReadLine()) != null)
      {
        parts = line.Split(new char[] { ';' });
        vorwahlen.Add(parts[0], parts[1]);
      }
    }
    object errorMsg = GetCustomProperty("MsgFormatNotValid");
    if (errorMsg != null)
      MsgFormatNotValid = errorMsg.ToString();
    errorMsg = GetCustomProperty("MsgAreaCodeNotExist");
    if (errorMsg != null)
      MsgAreaCodeNotExist = errorMsg.ToString();
  }
  public override string GetValidatedString(Object value)
  {
    string retValue = string.Empty;
    if (value != null)
    {
      retValue = value.ToString();
      Regex regex = new Regex(@"0d*-d*$", RegexOptions.IgnoreCase);
      if (!regex.IsMatch(retValue))
        throw new SPFieldValidationException(MsgFormatNotValid);
      string[] parts = null;
      parts = retValue.Split(new char[] { '-' });
      if (!ExistAreaCode(parts[0]))
        throw new SPFieldValidationException(MsgAreaCodeNotExist);
    }
    return retValue;
  }
  private bool ExistAreaCode(string areaCode)
  {
    return vorwahlen.ContainsKey(areaCode);
  }
  public string MsgAreaCodeNotExist { get; set; }
  public string MsgFormatNotValid { get; set; }
}

Die XML-Konfiguration

Damit SharePoint Kenntnis darüber hat, welche Eigenschaften während der Feldkonfiguration verfügbar sind (Abb. 3), müssen sie über eine XML-Konfigurationsdatei – vollständig abgebildet in Listing 2 – spezifiziert werden. Die Einstellungen erfolgen innerhalb eines FieldType-Knotens über mehrere Field-Einträge, die über das Attribut Name geschlüsselt sind. Im oberen Bereich erfolgen generelle Angaben zu dem Feld. Die Bedeutung der einzelnen Einträge kann in den meisten Fällen aus den Bezeichnern abgeleitet werden. Hervorzuheben sind hierbei die beiden geschlüsselten Angaben TypeName und FieldTypeClass. Im ersten Konfigurationseintrag erfolgt die Angabe der Feldklasse, die das Verhalten des Felds steuert. Im zweiten muss der vollständige Name der Bibliothek angegeben werden (Assembly), in der sich die angegebene Feldklasse befindet. Im unteren Bereich befindet sich der Knoten PropertySchema. In ihm werden zusätzliche Eigenschaften definiert, die im User Interface erscheinen sollen. In diesem Fall werden zwei zusätzliche Eingabefelder für mögliche Fehlermeldungen benötigt. Daher werden innerhalb des PropertySchema zwei Field-Knoten angelegt. Jeder Field-Eintrag spiegelt sich später als Eingabeelement an der Oberfläche wider. Für die Ablage der oben dargestellten Konfigurationsdatei in SharePoint ist der Ordner TEMPLATEXML vorgesehen. Um die Ablage zu ermöglichen, wird dem Projekt der SharePoint-Ordner XML zugeordnet. Als Namenskonvention für die Konfigurationsdatei ist dabei folgendes Muster einzuhalten: FLDTYPES_XXX.xml, wobei XXX durch den Namen der Feldklasse zu ersetzen ist. Bisher noch nicht erläutert wurde die überschriebene Methode GetValidatedString der neuen Feldklasse. Diese Methode führt die Validierung des eingegebenen Werts durch. Wird ein definierter Regelverstoß aufgedeckt, erstellt die Methode eine Ausnahme (Exception) vom Typ SPFieldValidationException und löst diese aus. SharePoint fängt die Ausnahme später auf und zeigt die übergebene Fehlermeldung an. Somit ist die Umsetzung eines SharePoint-Felds abgeschlossen. Abbildung 4 zeigt zum Abschluss die aktuell entstandene SharePoint-Projektstruktur.



  
    PhoneTextField
    Eingabe und Check einer Telefonnummer
    Text
    TRUE
    
      CustomFieldTypes.PhoneTextField,
      $SharePoint.Project.AssemblyFullName$
    
    TRUE
    TRUE
    TRUE
    
      
        
          
        
      
          
        
      
    
  

Bereitstellung des neuen Felds in SharePoint

Die Lösung kann nun wie üblich über F5 installiert werden. Im Wesentlichen wird hierbei die erstellte Bibliothek (Assembly) in den Global Assembly Cache (GAC) und die Konfigurationsdatei fldtypes_PhoneTextField.xml in den zugehörigen SharePoint-Ordner kopiert. Anschließend steht das Feld bei der Anlage einer Listenspalte zur Auswahl bereit, wie bereits in Abbildung 3 zu sehen war. Ist das neue Feld nicht direkt sichtbar, muss unter Umständen ein Neustart (Reset/IISReset) des Webservers erfolgen. SharePoint liest dann erneut die XML-Konfigurationen aus dem XML-Ordner ein. Abbildung 5 zeigt das Feld innerhalb eines Bearbeitungsdialogs in Aktion. Wie zu erkennen ist, funktioniert auch die Validierung, und Fehlermeldungen werden erwartungsgemäß eingeblendet.

Abb. 4: Validierungen des neuen Felds

Abb. 4: Validierungen des neuen Felds

Abb. 5: Arbeitsweise des neuen Felds

Abb. 5: Arbeitsweise des neuen Felds

Zusammenfassung

Die Erstellung und Installation von SharePoint-Feldern mit einer eigenen Oberfläche und Validierungsmechanismen ist, wie demonstriert wurde, nicht sonderlich kompliziert. Das hier gezeigte Beispiel ist relativ einfach, da es sich um lediglich ein Eingabefeld handelt. In der nächsten Kolumne wird daher beschrieben, wie komplexe Felder mit mehreren Eingabefeldern realisierbar sind. Als Beispiel wird dazu ein Feld für die Erfassung von Bankinformationen implementiert. Dabei erlaubt das Feld die Erfassung von Bankleitzahl, Kontonummer, Bankname und den Namen des Kontobesitzers.

Unsere Redaktion empfiehlt:

Relevante Beiträge

Meinungen zu diesem Beitrag

X
- Gib Deinen Standort ein -
- or -