Montag, 27. August 2012

Administrationsoberfläche ActiveAdmin für Rails Applikationen

Abstract

Etwas größere Web-Applikationen erfordern oft einen Administrationsbereich, in welchem z.B. Texte, Produkte oder Bilder erstellt, angezeigt, bearbeitet oder gelöscht (CRUD) werden können sollen. Für Rails Applikationen, die ActiveRecord als ORM nutzen, bietet sich die Nutzung des dafür hervorragend geeigneten Tools ActiveAdmin von Greg Bell an. Im Folgenden werden ActiveAdmin und einige Anpassungs-Möglichkeiten vorgestellt.

Die Beispielapplikation kann unter https://github.com/andywenk/active_admin_example bezogen und installiert werden.

Einfache Beispiel Applikation

Als Beispiel soll hier eine ganz einfach und unvollständige Shop-Applikation dienen. Um diese zu erstellen, werden nur wenige Schritte benötigt. Für die ActiveRecord Objekte wird der komfortable Rails Generator genutzt, der auch gleichzeitig für die AR-Objekte eine Migrationsdatei anlegt:

Zusätzlich werden noch Beziehungen zwischen den Objekten product, order, order_item und user hergestellt. Dazu editieren wir jeweils die Objekt-Dateien in app/models:

Wichtig ist hier die Erstellung der Beziehung zwischen einer Order, den dazugehörigen OrderItems und einem User: ein User kann viele Orders haben (has_many :orders). Eine Order gehört hierbei exakt zu einem User (belongs_to :user). Eine Order kann wiederum viel OrderItems haben (has_many :order_items). Und schliesslich gehört ein OrderItem exakt zu einer Order (belongs_to :order).

ActiveAdmin erkennt diese Beziehungen und gibt diese entsprechend in der Administrationsoberfläche bei den einzelnen Objekten als DropDown aus. Es zeigt sich also wieder wie wichtig ein gutes Datenbankmodell und die Verknüpfungen der einzelnen Objekte in einer Applikation sind.

Einbindung in ein Applikation

Da es sich um eine Rails 3.2.x Applikation handelt, ist die Einbindung von ActiveAdmin sehr einfach. Im Gemfile der Applikation werden folgende Einträge hinzugefügt:

  gem 'activeadmin'
  gem 'meta_search'

Nachdem die Einträge vorgenommen sind, werden der Applikation mit dem Befehl bundle install die entsprechenden gems zur Verfügung gestellt.

Das gem 'meta_search' nutzt ActiveAdmin für die Suche innerhalb der Oberfläche. Im nächsten Schritt wird nun ActiveAdmin installiert, wobei hier auch Datenbank Migrationen erstell werden. Das bedeutet, dass der entsprechende rake task ebenfalls noch mal ausgeführt werden muss. Ist dies auch geschehen kann die Applikation gestartet werden und unter http://localhost:3000 aufgerufen werden:

Grundlegendes Arbeiten mit dem Administrationsbereich

Der Administrationsbereich kann nun unter http://localhost:3000/admin aufgerufen werden und mit den Zugangsdaten User: admin@example.com, Password: password betreten werden

Auf dem Bild ist das grundlegende Interface (das Dashboard) von ActiveAdmin zu sehen. Allerdings befindet sich dort noch nichts administrierbares. Das wird geändert, indem die vier ActiveRecord Objekte user, product, order und order_item als Ressource hinzugefügt werden:

Wird die Seite aktualisiert, erscheinen oben in der horizontalen Navigation die Einträge Orders, OrderItems, Products und Users. Um beispielsweise Produkte anzulegen, begibt man sich in den Bereich "Products" und klickt rechts oben den Schalter "New Product". Die folgende Seite enthält ein Formular mit den Eingabefeldern für die Attribute des Product Objektes. Für weitere Anschauungen sollten einfach ein User, ein paar Produkte und eine Order mit ein paar OrderItems erstellt werden.

Nachdem die Datensätze erstellt wurden, leitet ActiveAdmin den Anwender auf die Ansichtsseite (show). Per Klick auf den Navigationspunkt "Products" gelangt man zur Übersicht und sieht dort eine Liste der erstellten Datensätze. Ausserdem bietet ActiveAdmin natürlich "pagination" bei vielen Datensätzen und auf der rechten Seite eine Suchmaske an.

Wie hier beschrieben wurden alle Datensätze über ActiveAdmin Interface erstellt. Es versteht sich von selbst, dass die Datensätze natürlich auch über jeglichen anderen Weg eingegeben werden können und per ActiveAdmin verwaltet werden können - z.B. über Import oder Benutzereingabe.

Anpassen der unterschiedlichen Ansichten

ActiveAdmin bietet eine sehr einfache zu benutzende DSL (Domain Specific Language), um die Ansichten (Views) und Formulare (Form) anpassen zu können. Dies geschieht in einer Datei der jeweiligen Seite die unter app/admin zu finden ist:

  active_admin_example
    app
      admin
        dashboards.rb
        order_items.rb
        orders.rb
        products.rb
        users.rb

Wenn eine neue Order erstellt werden soll (was natürlich ein etwas konstruierter Fall ist, dies im Adminbereich zu tun), kann durch die Verknüpfung zwischen den Objekten user und order im Administrationsbereich ein User per dropdown ausgewählt werden. Leider wird hier aber eine Objektreferenz angeboten und nicht etwa der Vor- und Nachname des Benutzers:

Um dies zu ändern, wird das Formular unter Verwendung der DSL entsprechend in der Datei app/admin/orders.erb angepasst:

Der Aufbau des Codes in der Datei ist ein Block, welcher am ActiveAdmin Objekt zu erst einmal das Objekt Order registriert. Innerhalb des Blocks wird die Methode Form mit einem Block aufgerufen. Dieser Aufruf gehört zur DSL von ActiveAdmin. Wie später noch gezeigt wird, gibt es weitere Methoden wie show oder index.

ActiveAdmin nutzt für die Erstellung der Formulare die FormBuilder DSL formtastic.Innerhalb des form-Blocks wird nun die DSL von formtastic genutzt, wobei ein Eingabefeld für die user_id als DropDown (select) erstellt wird. Wichtig ist hier der Wert für den key :collection: mit diesem Code wird ein Array erstellt, welches key - value Paare enthält, die aus Nachname, Vorname als key und die user_id als value bestehen. Das ist exakt die Anzeige, die wir brauchen.

Wenn die Order erstellt wird, glangt man wieder zur Detailansicht dieses Datensatzes. Hier besteht für den Eintrag User nun das gleich Problem wie bei dem Formular. Dies lässt sich durch folgenden Eintrag in app/admin/orders.rb beheben:

Bei der Anzeige der Order Details wird wieder die ActiveAdmin DSL genutzt - diesmal die Methode show.

Was aber nutzt eine Order, die keine OrderItems enthält. Es sollen also OrderItems angelegt werden. Dies geschieht über den Navigationspunkt OrderItems und wiederum rechts per klick auf den Schalter New Order Item. Auch hier muss etwas angepasst werden. Die DropDowns Order und Product sollen eine OrderID und den Produktnamen anzeigen. Ausserdem soll die OrderItem Detailseite ebenfalls diese Werte wiedergeben. Der folgende Code bewerkstelligt dies in app/admin/order_items.rb.

Wenn der Link OrderItems in der horizontalen Navigation aufgerufen wird, gelangt man zur Liste aller OrderItems. Hervorragend wäre doch die Anzeige einer Spalte, zu welcher Order das Item gehört und welches Produkt es referenziert. Also wird app/admin/order_items.rb erweitert, in dem aus der ActiveAdmin DSL die Methode index genutzt wird:

Sehr gut gewählt ist hier die Bezeichnung column für die einzelnen Attribute im Gegensatz zu row bei der show Methode.

Um nun die ersten Schritte in ActiveAdmin rund zu machen, wird nochmal an den Orders gefeilt. In der Detailansicht sollte zum einen eine extra Zeile vorhanden sein, die alle OrderItems ausgibt und eine Zeile, die den Gesamtpreis der Order angibt. Dafür ist das Erweitern der Datei app/admin/orders.rb erforderlich um folgenden Code:

Für den Eintrage ORDER ITEMS ist Code erstellt worden, der in einer Variablen ordered Links zu den einzelnen OrderItems speichert, und diese dann in jeweils einer Zeile ausgibt. Im Eintrag "TOTAL" werden die Preise der einzelen OrderItemes multipliziert mit der jeweiligen Anzahl der Produkte aufsummiert. Letztich werden zu Anfang der show Methode in der Variablen items alle zu dieser Order gehörigen OrderItems gespeichert um Code Duplication zu vermeiden. Das Ergebnis ist eine sehr aussagekräftige Ansicht:

Ausblick

Die hier gegebene Einführung in ActiveAdmin streift ein paar Möglichkeiten um ActiveAdmin für die Belange einer Applikation anzupassen. Dies stellt aber bei weitem nicht das Ende der Fahnenstange dar. Unter anderem lässt sich das Design komplett per CSS anpassen. Weiterhin kann nicht nur auf eine tabellarische Darstellung der jeweiligen index Seite genutzt werden, sondern z.B. auch ein Grid. Natürlich ist ActiveAdmin auch komplett mehrsprachig einrichtbar und es gibt Möglichkeiten um die Rechte mehrere Administratoren unterschiedlich einzustellen.

Fazit

ActiveAdmin ist hervorragend geeignet, um sich das Erstellen eines Administrationsbereichs zu sparen. Das Tool bietet tiefgreifende Anpassungsmöglichkeiten und kommt mit einem schlichten, aber modernen Design daher. Der Autor des Posts nutzt das Tool in mehreren Applikationen und ist sehr zu frieden damit. Selbst das Erstellen von Seiten die nicht einem ActiveRecord Objekt zu Grunde liegen ist möglich. Es kann also nur jedem empfohlen werden, der den Bedarf eines Administrationsbereichs für seine Applikation hat

Resourcen

Keine Kommentare:

Kommentar veröffentlichen