Umbraco Code Camp

Original von Per Ploug Hansen

Während Niels darüber nachdenkt, wie die Client-Seite der Designauswahl realisiert werden kann, nehmen wir uns heute vor zurück zu den Grundlagen der Web-Entwicklung zurückzukehren, und einiges mit altbewährtem HTML und JavaScript zu schreiben.

Der bisherige Blog-Kommentar ist ein wenig altmodisch und es fehlt ihm daher der richtige Schliff. Daher wollen wir ihn neu schreiben, vor allem um möglichst sauberes HTML zu bekommen, aber auch um folgende Details zu verwirklichen:

• saubere, freundliche Eingabeüberprüfungen mit jquery.validation
• senden der Eingabedaten über AJAX
• Gravatar-Vorschau bei Eingabe der E-Mail Adresse
• Kompatibilität für Screenreader (Bildschirmleseprogramme)

Der Plan dazu sieht wie folgt aus:

1. Schaffung der Server-seitigen Logik, welche den Kommentar erzeugt,
2. Verknüpfung dieser Logik mit dem Client unter Verwendung von /base,
3. Umsetzung einer simplen HTML-Gliederung des Formulars ohne runat="server" Attribute,
4. Entwicklung eines einfachen jQuery-Skripts, um die Eingabewerte an /base zu schicken,
5. Verschönerung des Formulars,
6. alles auch ohne JavaScript funktionieren lassen.

Die Server-seitige Logik

Zu diesem Zweck schreiben wir eine einfache statische Methode mit einem einzelnen Parameter, der Id des Blogbeitrags. Diese Methode erzeugt einen Kommentar und füllt die verschiedenen Eigenschaften aus: E-Mail, Name, Kommentar usw.

Die Eingabedaten empfängt sie über die HttpContext Request Collection. Alle die sich noch an ASP 3.0 Classic erinnern können werden diese Vorgehensweise wiedererkennen, und alles ohne die "view state"-Hölle. Die gesamte Methode ist nachfolgend aufgeführt. Sie enthält eine Reihe von Kommentaren um den Ablauf leichter verstehen zu können. Die wichtigsten Abschnitte sind:

1. Die Werte aus der HttpContext Request Collection ermitteln,
2. prüfen, ob diese auch gültige Werte darstellen,
3. Prüfung, ob der Blog-Beitrag überhaupt existiert und den entsprechenden Dokumenttyp besitzt,
4. Erzeugung eines Kommentar-Dokuments und ausfüllen der Eigenschaften,
5. Speichern und Veröffentlichen,
6. Rückgabe der Id des erzeugten Kommentar-Dokuments.

public static int CreateComment(int parentId)
{
//here we find form values posted to the current page
    HttpRequest post = HttpContext.Current.Request;
    string email = post["email"];
    string comment = post["comment"];
    string name = post["name"];
    string website = post["website"];

    //if all values are there + valid email.. we start to create the comment
    if (!string.IsNullOrEmpty(email) && isValidEmail(email) && !string.IsNullOrEmpty(comment) && !string.IsNullOrEmpty(name))
    {
        Document blogpost = new Document(parentId);

        //if parent is actually a blogpost
        if(blogpost != null && blogpost.ContentType.Alias == "BlogPost"){
            DocumentType dt = DocumentType.GetByAlias("BlogPostComment");
            Document d = Document.MakeNew("RE: " + blogpost.Text + " by: " + name, dt, new umbraco.BusinessLogic.User(0), blogpost.Id);
            d.getProperty("comment").Value = comment;
            d.getProperty("email").Value = email;
            d.getProperty("name").Value = name;
            d.getProperty("website").Value = website;
            d.Save();
            d.Publish(new umbraco.BusinessLogic.User(0));

            umbraco.library.UpdateDocumentCache(d.Id);
            return d.Id;
        }
    }

    //if nothing gets created, we return zero
    return 0;
}

Server- und Client-Logik miteinander verbinden

Nachdem wir nun den Quelltext fertig haben, um einen Kommentar zu erzeugen, müssen wir ihn auch vom Browser aus zugänglich machen. Dazu verwenden wir die in Umbraco eingebaute /base Funktionalität. /base arbeitet kurz gesagt als Proxy zwischen der Server-seitigen Logik und dem Browser, indem URLs erzeugt werden, die diesen Server-Code aufrufen und ausführen.

Die Verbindung wird über die Konfigurationsdatei /config/restExtensions.config eingerichtet. In dieser verknüpfen wir die Assembly Umlaut.Umb.Blog.dll mit einem <ext>-Element, fügen einen freundlichen Alias hinzu und geben den Zugriff auf die Methode CreateComment als Manifest für diese Schnittstelle frei:

<ext assembly="/bin/Umlaut.Umb.Blog" type="Umlaut.Umb.Blog.Library.Base" alias="Blog4Umbraco">

    <permission method="CreateComment" returnXml="false" allowAll="true" />

</ext>

Diese Konfiguration bewirkt, dass wir nun die angegebene Methode über die URL /base/Blog4Umbraco/CreateComment/[pageId].aspx aufrufen können. Genau das werden wir später tun, um die Formulardaten über jQuery zu senden.

HTML-Auszeichnung des Formulars

Das tolle daran, ein Formular ohne ASP.NET-Steuerelemente zu entwickeln, ist die Wiederentdeckung der Tatsache, wie einfach und großartig HTML eigentlich ist. Um die vollständige Textauszeichnungen zu sehen, können wir uns das Blog-Package von nightly.umbraco.org installieren und uns die Datei /usercontrols/ajaxcommentform.ascx näher ansehen.

Das folgende Beispiel ist die Auszeichnung für ein einzelnes Eingabefeld:

<p class="commentField emailField">
    <label for="tb_email" class="fieldLabel">
        <%= Umlaut.Umb.Blog.BlogLibrary.Dictionary("#Email","Email address") %>:
    </label>
    <input type="text" id="tb_email" name="email" class="input-text required email" />
</p>

Bemerkenswert hierbei: Wir haben für die Beschriftungen Wörterbuch-Unterstützung (der erste Parameter ist der Schlüssel und der zweite Parameter stellt den Vorgabewert dar, falls für den Schlüssel keine Übersetzung existiert). Weiterhin benutzen wir jquery.validation zur Eingabeprüfung der Formulardaten auf der Client-Seite. Dies erreichen wir, indem wir die die Klassen "required" und "email" zum Eingabefeld hinzufügen. Diese Klassen stellen sicher, dass das Eingabefeld sowohl ausgefüllt werden muss, als dann auch eine korrekte E-Mail Adresse enthält.

Eingabewerte an /base senden mit jQuery

Nun aber endlich die Kernfunktionalität! Wenn das Formular ausgefüllt ist, wollen wir es mit Hilfe von AJAX an die /base URL senden, welche dann die eigentliche Erzeugung des Kommentars ausführt. Wir führen dies mit einem jQuery.Post aus:

var url = "/base/Blog4Umbraco/CreateComment/<umbraco:Item field="pageID" runat="server"/>.aspx";

jQuery.post(url, { name: jQuery("#tb_name").val(), email: jQuery("#tb_email").val(), website: jQuery("#tb_website").val(), comment: jQuery("#ta_comment").val() },
    function(data){
        jQuery("#commentPosted").show();
    }
});

Zunächst setzen wir die URL in einer Variable zusammen. Wie zu erkennen ist, zeigt die URL auf /base/Blog4Umbraco/CreateComment/wobei wir dann noch die aktuelle Seiten-ID für die Server-Seite anfügen. jQuery sendet dann eine Kollektion von Werten (E-Mail, Name usw.) an die /base URL und zeigt abschließend die Rückmeldung an.

Schwupps, wir haben ein AJAX-Formular.

Verschönerung des Formulars

Wenn wir gerade dabei sind, können wir auch gleich noch eine Gravatar-Vorschau einbauen. Wenn der Kommentator seine E-Mail Adresse eintippt, so erscheint auf der rechten Seite sofort sein Gravatar-Bild.

Diesen Effekt realisieren wir ebenfalls mittels jQuery und /base:

jQuery("#tb_email").blur(function(){
                var email = jQuery("#tb_email").val();
                if(email != ""){
                    var url = "/base/Blog4Umbraco/GetGravatarImage/" + email + "/80.aspx";
                    jQuery.get(url, function(data){
                        if(data != ""){
                             jQuery("#gravatar").css( "background-image","url(" + data + ")" ).show();
                        }else{
                            jQuery("#gravatar").hide();
                        }
                    });
                }
          });

Auch hierfür senden wir eine einfache Anforderung an eine /base Methode. Diesmal allerdings mit gleich zwei Parametern - E-Mail Adresse und Bildgröße. Der Aufruf liefert eine URL zurück, die auf das der E-Mail Adresse zugeordnete Gravatar-Bild verweist.

Alles auch ohne JavaScript funktionieren lassen

Das mit AJAX realisierte Formular hat den großartigen Nebeneffekt, dass damit automatische Spam-Bots ausgeschlossen werden. Leider aber auch Menschen, die einen Screen Reader benutzen müssen. Wir wollen aber sicherzustellen, dass Screen Reader ebenfalls das Formular benutzen können. Wir müssen dazu die Funktionsfähigkeit auch bei abgeschaltetem JavaScript gewährleisten. Glücklicherweise haben wir bereits die Server-seitige Funktionalität, welche eine Kollektion von Werten mit den Request-Daten erwartet. Und wenn JavaScript abgeschaltet ist, so sendet das Formular entsprechend der ASP.NET Standardlogik sein Postback-Daten zurück an die eigene URL. Dies bedeutet, dass wir die serverseitige /base-Logik einfach beim Page_Load Ereignis aufrufen können. In der Datei AjaxCommentForm.ascx sieht das dann einfach wie folgt aus:

 protected void Page_Load(object sender, EventArgs e)
        {
            if (Page.IsPostBack)
            {
                Library.Base.CreateComment(umbraco.presentation.nodeFactory.Node.GetCurrent().Id);
            }
        }

Wie zu sehen ist, benutzen wir exakt die selbe Methode und da diese auf die Request-Kollektion für die übergebenen Daten zurückgreift ist es ganz egal ob der Aufruf über ein HTTP Post an die /base URL oder ein Post auf die eigene Seitenadresse mit dem obigen Ereignis auf der Server-Seite erfolgt.

Weitere Infos

Wir haben gerade 2 neue Videos auf umbraco.tv hinzugefügt, die weitere Informationen über Umbraco /base und eine detailierte Anleitung für den oben beschriebenen Quelltext geben. Folgender Link bietet noch mehr Infos über den Umgang mit AJAX und Umbraco:

http://umbraco.tv/documentation/videos/for-developers/base-and-ajax-development

Der komplette Quelltext findet sich auf CodePlex: http://blog4umbraco.codeplex.com/
und das installierbare Nightly-Build auf: http://nightly.umbraco.org/Blog4Umbraco/2.0.3/