Eigene App-Screens und Komponenten mit simplebis-builder erstellen.
Custom Screens werden in der App-IDE unter Apps > App bearbeiten > IDE öffnen erstellt. Die neue Implementierung speichert Screens und Komponenten als App-Elemente. Ein Screen hat den Typ screen, eine wiederverwendbare Komponente den Typ component.
In der App werden Builder-Screens mit Keys wie element_{id} gerendert. Ältere AppScreen-/PageBuilder-Screens verwenden dagegen Keys wie custom_{id}. Neue individuelle App-Oberflächen sollten bevorzugt mit simplebis-builder erstellt werden.
Ein Builder-Screen besteht aus Elementen, Properties, State, Contexts, Styles und Workflows.
Elemente bilden die sichtbare Oberfläche. Properties sind Eingaben von außen, zum Beispiel aus Navigation, Route oder App-Shop-Konfiguration. State sind Werte, die der Screen selbst verwaltet. Contexts laden fachliche Daten wie Artikel oder Events. Workflows führen Aktionen aus, zum Beispiel Navigation oder State-Änderungen.
Properties werden am Screen oder an einer Komponente definiert und beim Rendern übergeben. Sie eignen sich für IDs und Konfigurationen, die von außen kommen. Beispiele sind articleId, shopId, eventId, ein Titel oder ein Modus.
Ein typischer Artikel-Screen erhält articleId und shopId als Properties. Diese Werte können dann verwendet werden, um den Artikel-Context zu laden.
Beispiel für die gedachte Property-Struktur eines Artikel-Screens:
{
"articleId": "ARTIKEL_ID",
"shopId": "SHOP_ID"
}
Wenn derselbe Screen für mehrere Artikel oder Shops verwendet werden soll, sollten IDs nicht fest in Elementen stehen, sondern als Properties übergeben und im Context-Mapping verwendet werden.
State enthält Werte, die während der Nutzung eines Screens entstehen oder verändert werden. Der Default-State wird aus der Screen-Konfiguration erzeugt und dem Renderer beim Start übergeben.
State kann über den Workflow setState geändert werden. Dabei wird ein Key und ein Wert gesetzt. Unterstützt werden Text, Integer, Float, Boolean und JSON-Objekte.
Beispiel für einen Workflow, der einen Filter setzt:
{
"type": "setState",
"attributes": {
"key": "filter",
"value": {
"type": "string",
"value": "popular"
}
}
}
Beispiel für einen Boolean-State:
{
"type": "setState",
"attributes": {
"key": "showDetails",
"value": {
"type": "boolean",
"value": true
}
}
}
State-Werte können anschließend in bindbaren Attributen oder Bedingungen verwendet werden, sofern das jeweilige Builder-Element diese Bindung unterstützt.
Contexts laden fachliche Daten vor oder während dem Rendern eines Screens. Die App stellt aktuell diese Contexts bereit:
article: lädt einen Artikel über /api/v1/articles/details. Der Context benötigt eine Artikel-ID. Zusätzlich kann ein Shop übergeben werden, damit Shop-spezifische Preise, Verfügbarkeiten und Warenkorbaktionen passen.
event: lädt ein Event über /api/v2/events/details. Der Context benötigt eine Event-ID. Zusätzlich kann ein Shop übergeben werden, wenn der Event- oder Ticketkontext einen Shopbezug benötigt.
Ein typisches Mapping liest IDs aus den Properties und schreibt das geladene Ergebnis in den State:
{
"key": "article",
"type": "article",
"mapping": {
"from": "props",
"fromKey": "articleId",
"target": "state",
"targetKey": "article",
"additions": [
{ "key": "_shop", "from": "props", "fromKey": "shopId" }
]
}
}
Für ein Event sieht das Mapping entsprechend so aus:
{
"key": "event",
"type": "event",
"mapping": {
"from": "props",
"fromKey": "eventId",
"target": "state",
"targetKey": "event"
}
}
Nach dem Laden können Elemente auf die geladenen Daten zugreifen, indem sie Attribute an den entsprechenden State- oder Context-Wert binden.
Eigene Builder-Elemente lesen ihre konfigurierten oder gebundenen Werte über getAttribute. Dadurch muss ein Element nicht wissen, ob der Wert fest eingetragen, aus Properties, State oder Context kommt.
Ein stark vereinfachtes Beispiel für ein eigenes Element:
const Render = ({ getAttribute }) => {
const title = getAttribute("title");
const disabled = getAttribute("disabled");
const article = getAttribute("article", { plainObject: true });
if (!article) {
return null;
}
return (
<Button disabled={disabled}>
{title || article.add_to_cart_label}
</Button>
);
};
Bei Objektwerten wie einem geladenen Artikel sollte plainObject: true verwendet werden, wenn das Element mit dem normalen Objekt arbeiten soll.
Workflows führen Aktionen aus. In der App sind vor allem diese Workflows relevant:
navigate öffnet eine App-Route. Wenn das Ziel nicht mit /instance beginnt, ergänzt die App den Prefix automatisch.
{
"type": "navigate",
"attributes": {
"target": "/shop/SHOP_ID"
}
}
openUrl öffnet eine externe URL.
{
"type": "openUrl",
"attributes": {
"url": "https://example.com"
}
}
goBack geht zur vorherigen Seite zurück, sofern die App zurück navigieren kann.
setState setzt einen State-Wert und wird verwendet, um Filter, Auswahlzustände, Ansichtsmodi oder lokale UI-Zustände zu verändern.
Neben den Basis-Elementen des simplebis-builders stellt die App eigene Elemente bereit:
simplebis_page rendert eine App-Seite im einfachen App-Layout.
html rendert HTML-Inhalt.
article_cart_action zeigt eine Warenkorbaktion für einen geladenen Artikel.
shop_floating_cart_button zeigt einen schwebenden Warenkorbbutton für einen Shop.
ticket_add_to_cart_button zeigt eine Ticket-Kaufaktion für ein Event.
subscriptions_button stellt eine Abo-/Subscription-Aktion bereit.
app_form bindet ein App-Formular ein.
Zusätzlich können gespeicherte App-Komponenten als eigene Elementtypen in anderen Screens verwendet werden.
Eine eigene Artikel-Detailseite wird als Builder-Screen erstellt und anschließend unter Apps > App bearbeiten > Shops als Artikel-Detailseite für den App-Shop ausgewählt.
Der Screen sollte articleId und shopId als Properties erwarten. Der Artikel-Context lädt mit diesen Properties den Artikel und schreibt ihn zum Beispiel nach state.article. Danach können Elemente wie Texte, Bilder und article_cart_action den geladenen Artikel verwenden.
Vereinfachter Ablauf:
1. Screen in der App-IDE erstellen.
2. Properties `articleId` und `shopId` definieren.
3. Context `article` mit Mapping von `props.articleId` und Zusatz `_shop` aus `props.shopId` konfigurieren.
4. Artikelinformationen im Screen anzeigen.
5. Element `article_cart_action` einfügen und an den geladenen Artikel binden.
6. Screen beim App-Shop als eigene Artikel-Detailseite hinterlegen.
So bleibt der Screen wiederverwendbar und funktioniert für jeden Artikel, den die App mit passenden Properties öffnet.
Eine eigene Event-Ticketseite wird als Builder-Screen erstellt und erhält eventId als Property. Der Event-Context lädt das Event und stellt die Daten dem Screen zur Verfügung.
Für den Ticketverkauf wird das Element ticket_add_to_cart_button verwendet. Es benötigt die Event-ID und kann Labels wie Tickets kaufen und Zum Warenkorb konfigurieren.
Vereinfachter Ablauf:
1. Screen in der App-IDE erstellen.
2. Property `eventId` definieren.
3. Context `event` mit Mapping von `props.eventId` konfigurieren.
4. Eventdaten anzeigen.
5. Element `ticket_add_to_cart_button` einfügen.
6. Button mit Event-ID verbinden.
7. Screen über Navigation, Aktion oder Event-Kontext erreichbar machen.
Der Ticketverkauf funktioniert nur, wenn Event, Tickets, Shop, Preise, Verfügbarkeit und Zahlungsarten fachlich korrekt konfiguriert sind.
Eigene Builder-Screens sollten immer mit echten Properties getestet werden. Wichtig ist, ob Contexts korrekt laden, ob leere oder fehlende Daten sauber behandelt werden, ob Workflows die richtigen Routen öffnen und ob State-Änderungen sichtbar funktionieren.
Bei Shop- und Ticketseiten sollten zusätzlich Verfügbarkeit, Preise, Warenkorb, Checkout und Login-Zustand geprüft werden. Bei Account-Screens muss geprüft werden, dass persönliche Daten nicht ohne Login sichtbar sind.