b4um Generator – Installation und Grundeinrichtung

Seit unserem ersten Tutorial hat sich der b4um Generator deutlich weiterentwickelt.

Viele Schritte, die wir früher noch manuell durchführen mussten, übernimmt der Installer inzwischen selbst. Dazu gehört unter anderem das Anlegen einer Startseite samt Root-Route und passendem Navigationseintrag.

In diesem Revisited-Tutorial richten wir deshalb eine neue Rails-Anwendung mit der aktuellen Version des b4um Generators von Grund auf ein.

Wir verwenden in diesem Tutorial:

Ruby 3.4.2
Rails 8.1.4
b4um_generators 0.2.7

Am Ende besitzen wir eine vollständige b4um-Grundinstallation mit Startseite, Navigation, Hero, Footer, Sitemap, Theme-Umschaltung und Cookie Consent.

1. Eine neue Rails-Anwendung erstellen

Zunächst erstellen wir eine neue Rails-Anwendung:

rails new b4um_revisited

Anschließend wechseln wir in das Projektverzeichnis:

cd b4um_revisited

Zur Kontrolle können wir uns die verwendeten Ruby- und Rails-Versionen anzeigen lassen:

ruby -v
bin/rails -v

In unserem Beispiel verwenden wir Ruby 3.4.2 und Rails 8.1.4.

2. b4um Generators installieren

Der b4um Generator steht als Gem über RubyGems zur Verfügung.

Wir fügen die aktuelle Version unserer Anwendung hinzu:

bundle add b4um_generators --version "~> 0.2.7"

Dadurch wird der entsprechende Eintrag automatisch in die Gemfile aufgenommen:

gem "b4um_generators", "~> 0.2.7"

Ob die richtige Version installiert wurde, können wir anschließend überprüfen:

bundle info b4um_generators

Die Ausgabe sollte unter anderem die installierte Version anzeigen:

b4um_generators (0.2.7)

3. Verfügbare b4um Generatoren überprüfen

Nach der Installation können wir kontrollieren, ob Rails die b4um Generatoren erkannt hat:

bin/rails generate | grep b4um

Mit Version 0.2.7 stehen unter anderem folgende Generatoren zur Verfügung:

b4um:attachment
b4um:authentication
b4um:bento
b4um:comments
b4um:controller
b4um:help
b4um:infinite_scroll
b4um:install
b4um:pagination
b4um:readable
b4um:scaffold
b4um:search
b4um:table
b4um:trix

Damit ist das Gem erfolgreich in unsere Rails-Anwendung eingebunden.

4. Den b4um Installer starten

Jetzt können wir die eigentliche Grundeinrichtung starten:

bin/rails generate b4um:install

Der Installer führt uns durch verschiedene Optionen. Wir können dadurch selbst entscheiden, welche Bestandteile unsere Anwendung benötigt.

5. Passwortunterstützung mit bcrypt

Zunächst fragt der Installer:

Install bcrypt for password support? (y/n)

Wenn unsere Anwendung später Benutzeranmeldung und Passwortfunktionen verwenden soll, können wir bcrypt direkt aktivieren.

Wir wählen:

Der Installer aktiviert bcrypt daraufhin in der Gemfile.

Benötigen wir keine Passwortunterstützung, können wir stattdessen n wählen.

6. Active Storage einrichten

Als Nächstes fragt der Installer:

Install Active Storage for image attachments? (y/n)

Active Storage benötigen wir beispielsweise für Bilder und andere Dateianhänge.

Da wir diese Funktionen in unserer Anwendung später verwenden möchten, wählen wir:

Der Installer führt daraufhin die notwendige Active-Storage-Installation durch und erstellt anschließend auch die Datenbanktabellen.

Intern werden unter anderem folgende Rails-Aufgaben ausgeführt:

bin/rails active_storage:install
bin/rails db:migrate

Damit ist Active Storage direkt einsatzbereit.

7. Startseite automatisch erstellen

An dieser Stelle gibt es gegenüber früheren Versionen des b4um Generators eine wichtige Verbesserung.

Der Installer fragt:

Create a home page? (y/n)

Wir wählen:

Anschließend können wir Controller und Action bestimmen:

Home controller [Pages]:
Home action [home]:

Die Werte in den eckigen Klammern sind die Standardwerte.

Für unsere Anwendung übernehmen wir beide Vorgaben, indem wir jeweils einfach Enter drücken.

Der Installer erstellt daraufhin automatisch:

app/controllers/pages_controller.rb
app/views/pages/home.html.erb

Zusätzlich richtet er die passende Root-Route ein:

root "pages#home"

Damit verweist die Hauptadresse unserer Anwendung direkt auf:

PagesController#home

Genau dieser Schritt musste in früheren Versionen noch manuell durchgeführt werden.

8. Die erzeugte Home-Seite

Unsere neue Startseite befindet sich unter:

app/views/pages/home.html.erb

Der Installer liefert bereits eine einfache Ausgangsstruktur:

<% content_for :title, "Home" %>

<div class="page-header">
  <h1>Home</h1>
</div>

<div class="b4um-grid">
  <section class="b4um-card b4um-card--full">
    <h2 class="b4um-card__title">
      Home
    </h2>

    <p class="b4um-card__text">
      Add your content here.
    </p>
  </section>
</div>

Diesen Inhalt können wir später vollständig an unsere Anwendung anpassen.

9. Navigation wird ebenfalls vorbereitet

Auch den Home-Eintrag in der Navigation müssen wir nicht mehr von Hand anlegen.

Der Installer erzeugt automatisch:

<%= navigation_link_to "Home",
                       root_path,
                       controller: :pages,
                       action: :home %>

Der Link verwendet unsere Root-Route und enthält gleichzeitig Controller und Action.

Dadurch kann die b4um Navigation erkennen, wann wir uns auf der Home-Seite befinden und den Menüpunkt entsprechend als aktiv darstellen.

Damit entfallen mehrere manuelle Schritte, die in der ersten Version unseres Tutorials noch notwendig waren.

10. Hero-Bereich installieren

Als Nächstes fragt der Installer:

Add a hero section? (y/n)

Wir möchten auf unserer Startseite einen hervorgehobenen Einstiegsbereich verwenden und wählen deshalb:

Der Installer erstellt:

app/views/shared/_hero.html.erb

Der Hero wird auf der Root-Seite eingebunden und kann später beispielsweise für Überschrift, Einführungstext oder einen Call-to-Action angepasst werden.

11. Footer installieren

Danach können wir einen Footer hinzufügen:

Add a footer? (y/n)

Wir wählen:

Dadurch entsteht:

app/views/shared/_footer.html.erb

Der Footer bildet gleichzeitig die Grundlage für die Sitemap, die wir im nächsten Schritt einrichten.

12. Sitemap zum Footer hinzufügen

Da wir einen Footer installiert haben, fragt b4um anschließend:

Add a sitemap to the footer? (y/n)

Wir wählen:

Jetzt können wir bestimmen, aus wie vielen Spalten unsere Sitemap bestehen soll.

Die Vorgabe lautet:

Number of sitemap columns [4]:

Für unser Beispiel übernehmen wir den Standardwert von vier Spalten mit Enter.

Anschließend können die Überschriften festgelegt werden:

Sitemap column 1 title [Kontakt]:
Sitemap column 2 title [Inhalte]:
Sitemap column 3 title [Service]:
Sitemap column 4 title [Mehr]:

Auch hier übernehmen wir jeweils die vorgeschlagenen Standardwerte.

Unsere Sitemap besitzt damit vier Bereiche:

Kontakt
Inhalte
Service
Mehr

Der Installer erstellt dafür unter anderem:

app/views/shared/_sitemap.html.erb
app/javascript/controllers/sitemap_controller.js

13. Die Sitemap-Konfiguration überprüfen

Die Konfiguration der Sitemap befindet sich in:

config/b4um.yml

Nach unserer Installation enthält sie zunächst die vier Sitemap-Spalten.

Da wir später Impressum, Datenschutz und AGB unter Service anzeigen möchten, passen wir zusätzlich die Position der rechtlichen Links an.

Unsere Konfiguration sieht anschließend so aus:

---
sitemap:
  - key: column_1
    title: Kontakt
  - key: column_2
    title: Inhalte
  - key: column_3
    title: Service
  - key: column_4
    title: Mehr
legal_links:
  placement: column_3

Entscheidend ist:

legal_links:
  placement: column_3

Standardmäßig kann hier noch footer eingetragen sein.

Da column_3 in unserer Konfiguration den Titel Service trägt, bereiten wir damit die Sitemap bereits für unsere späteren rechtlichen Seiten vor.

Die eigentlichen Seiten wie Impressum, Datenschutz und AGB erstellen wir in einem weiteren Tutorial.

14. Cookie Consent installieren

Zum Schluss können wir Cookie Consent aktivieren.

Der Installer fragt:

Add cookie consent? (y/n)

Wir wählen:

Daraufhin werden unter anderem folgende Dateien eingerichtet:

app/views/shared/_cookie_consent.html.erb
app/javascript/controllers/cookie_consent_controller.js

Beim ersten Besuch der Anwendung erscheint dadurch der Cookie-Hinweis.

Besucher können zwischen:

Ablehnen

und

Akzeptieren

wählen.

Beim ersten Besuch zeigt die b4um-Grundeinrichtung den optional installierten Cookie-Hinweis mit den Möglichkeiten „Ablehnen“ und „Akzeptieren“.

Auf diesem Bild sind gleichzeitig bereits Navigation, Hero, Startseite, Sitemap und Theme-Umschaltung zu sehen.

15. Was der Installer zusätzlich einrichtet

Neben den von uns ausgewählten Komponenten richtet b4um:install weitere Bestandteile der b4um-Grundausstattung ein.

Dazu gehören unter anderem:

app/assets/stylesheets/b4um/
app/views/shared/_navigation.html.erb
app/views/shared/_theme_switcher.html.erb
app/javascript/controllers/navigation_controller.js
app/javascript/controllers/theme_controller.js
app/javascript/controllers/image_preview_controller.js
app/javascript/controllers/image_lightbox_controller.js
app/javascript/controllers/dismissible_controller.js
app/helpers/navigation_helper.rb
app/helpers/b4um_helper.rb
config/b4um.yml

Auch das Rails Application Layout wird automatisch für die benötigten b4um-Komponenten vorbereitet.

Wir müssen diese Bestandteile deshalb nicht einzeln von Hand integrieren.

16. Anwendung starten

Jetzt starten wir unseren Rails-Server:

bin/rails server

Anschließend öffnen wir:

http://localhost:3000

Da der Installer bereits unsere Root-Route eingerichtet hat, erscheint unmittelbar die neue Home-Seite.

Wir müssen weder eine zusätzliche Route noch einen Home-Link manuell konfigurieren.

Unsere fertige b4um-Grundeinrichtung mit Navigation, Hero-Bereich, Home-Seite, vierteiliger Sitemap, Footer und Theme-Umschaltung.

17. Die Root-Route überprüfen

Falls wir die eingerichtete Route zusätzlich im Terminal kontrollieren möchten, können wir ausführen:

bin/rails routes | grep root

In unserer Anwendung erhalten wir:

root GET / pages#home

Damit ist bestätigt:

http://localhost:3000
        ↓
        /
        ↓
root "pages#home"
        ↓
PagesController#home
        ↓
home.html.erb

Was haben wir in diesem Tutorial gemacht?

Wir haben eine neue Rails-Anwendung erstellt und anschließend b4um_generators in Version 0.2.7 über RubyGems installiert.

Danach haben wir die Grundeinrichtung gestartet:

bin/rails generate b4um:install

Über den Installer haben wir:

bcrypt aktiviert,
Active Storage installiert,
eine Home-Seite erzeugt,
die Root-Route automatisch eingerichtet,
die Navigation vorbereitet,
einen Hero installiert,
einen Footer angelegt,
eine vierteilige Sitemap eingerichtet,
die Sitemap für spätere rechtliche Seiten vorbereitet,
Cookie Consent aktiviert und
die vollständige b4um-Grundausstattung installiert.

Besonders praktisch ist die automatische Einrichtung der Startseite.

Während wir bei früheren Versionen noch selbst einen Controller erzeugen, eine Root-Route festlegen und anschließend die Navigation anpassen mussten, übernimmt der aktuelle Installer diese Schritte direkt.

Unsere Anwendung besitzt damit bereits nach der Grundeinrichtung eine funktionierende Ausgangsbasis.

Im nächsten Revisited-Tutorial können wir darauf aufbauen und weitere statische Seiten erstellen. Dabei sehen wir uns an, wie wir beispielsweise Über uns, Kontakt, Impressum, Datenschutz und AGB mit dem b4um Controller-Generator erzeugen und gezielt in Navigation und Sitemap einordnen.

Meld dich an und schreibe ein Kommentar