Der Seitenleiste eigene Tabs hinzufügen

Sie können eigene Tabs in die Seitenleiste von agorum core hinzufügen, etwa, wenn Sie eine neue aguila-basierte UI entwickelt haben und diese systemweit (oder nur für bestimmte Benutzer) als neuen Tab anzeigen lassen möchten.

Ein Tab stellt einen Eintrag in der Seitenleiste dar.
Der Tab öffnet sich bei Klick rechts im Vollbild, etwa wie der agorum core explorer.
Das Modul agorum.home stellt diese Tabs bereit.
Im Modul agorum.home existieren provider, die diese Tabs registrieren und verwalten.

Einen provider definieren

Ein provider ist eine JavaScript-Bibliothek, die eine einzelne Funktion über module.exports exportiert.
Pro Konfigurationsprojekt existiert üblicherweise ein provider.
Sie legen diesen provider über eine JavaScript-Datei an.

So definieren Sie einen provider:

Öffnen Sie links in der Seitenleiste Explorer.

Öffnen Sie Ihr Konfigurationsprojekt und dort den Ordner js unter:

Eigene Dateien/Administration/customers/<Konfigurationsprojekt>/js

Legen Sie über das Kontextmenü und die Aktion Neu den Ordner home an.
Legen Sie im Ordner home über das Kontextmenü und die Aktion Neu die JavaScript-Datei provider.js an.
Befüllen Sie die Datei provider.js mit den existierenden JavaScript-Funktionen für einen provider.
Speichern Sie die Änderungen.

Einen provider registrieren

Verwenden Sie die Aktion home provider registrieren im agorum core template manager, um einen provider nach der Definition im System zu registrieren.

Funktionen eines providers

Das Modul agorum.home ruft die exportierte Funktion auf, wenn Informationen über verfügbare Tabs abgerufen werden sollen, etwa beim Öffnen eines neuen agorum.home-Tabs im Browser oder bei der Anzeige der Konfigurationsmaske für die Seitenleiste.
Als Parameter übergibt das System das Objekt home, über das die Kommunikation mit dem Modul agorum.home abläuft.
Zum Objekt home existieren die hier aufgeführten Funktionen.

registerTab

Registriert einen neuen Tab in der Seitenleiste.

Syntax

home.registerTab(<tab>);

Felder zum Parameter „tab“

Feld	Beschreibung
type (optional)	Definiert den Namen des registrierten Tab-Typs, den das System für diesen Tab verwendet (siehe Funktion registerType). Dieses Feld benötigen Sie, wenn Sie etwa mehrere ähnliche Tabs der gleichen Art erzeugen möchten, die alle die gleichen Merkmale aufweisen. Abhängig vom verwendeten Typ kann das System andere Felder für den Parameter tab unterstützen.
name	Definiert einen eindeutigen internen Namen für diesen Tab. Das System verwendet diesen Namen unter anderem für die Speicherung von individuellen Benutzereinstellungen zu diesem Tab. Wenn Sie ein eigenes widget darstellen möchten, verwenden Sie den Namen des widget-Typs.
text	Definiert den Titel, den der Benutzer für diesen Tab in der Seitenleiste und im Seitentitel des Browsers sieht.
icon	Definiert das aguila-Icon, das der Benutzer für diesen Tab in der Seitenleiste und vor dem Seitentitel des Browsers sieht.
aon	Definiert die Beschreibung des aguila-Widgets, den das System als Tab anzeigt.

Beispiel

Dieses Beispiel zeigt die Anwendung der Funktion.

module.exports = home => {
  home.registerTab({
    name: 'sample.package.tab.test',
    text: 'Test-Tab',
    icon: 'agorum:rounded-square-5;color=LightSeaGreen;scale=.9|ionicon:search;color=white;scale=.8',
    aon: {
      type: 'sample.package.tab.test'
    }
  });
};

registerType

Registriert einen neuen Tab-Typ, den darauffolgende registerTab-Aufrufe verwenden können.

Syntax

home.registerType(<name>, <builder>);

Parameter

Parameter	Beschreibung
name	Definiert einen eindeutigen internen Namen für diesen Tab-Typ. Sie können diesen Tab-Typ als type für Aufrufe der Funktion registerTab verwenden (siehe Beispiel).
builder	Definiert Funktionen, die das System aufruft, wenn Sie einen Tab dieses Typs registrieren. Die Funktion enthält den Parameter tab, den das System an die Funktion registerTab übergeben hat. Von der Funktion wird erwartet, dass sie diesen Parameter modifiziert, sodass eine vollständige Tab-Definition mit name, text, icon und aon entsteht.

Beispiel

Dieses Beispiel zeigt die Anwendung der Funktion.

module.exports = home => {
  // Neuen Typ "sample.package.tab.type" registrieren
  home.registerType('sample.package.tab.type', tab => {
    tab.name = 'sample.package.tab.type.' + tab.id;
    tab.text = 'Test-Tab ' + tab.id;
    tab.icon = 'agorum:rounded-square-5;color=LightSeaGreen;scale=.9|ionicon:search;color=white;scale=.8';

    tab.aon = {
      type: 'sample.package.tab.test',
      id: tab.id
    };
  });

  // Typ "sample.package.tab.type" zur Registrierung eines neuen Tabs verwenden
  home.registerTab({
    type: 'sample.package.tab.type',
    id: '475dc69e-221c-4fae-9466-cf94bd6c2386'
  });
};

updateTab

Ändert den Titel oder das Icon eines bereits registrierten Tabs.

Syntax

home.updateTab(<tab>);

Felder zum Parameter "tab"

Feld	Beschreibung
name	Ändert den internen Namen für diesen Tab. Das System verwendet diesen Namen unter anderem für die Speicherung von individuellen Benutzereinstellungen zu diesem Tab. Wenn Sie ein eigenes widget darstellen möchten, muss dieser Name mit dem Namen des widget-Typs übereinstimmen.
text	Ändert den Titel, den der Benutzer für diesen Tab in der Seitenleiste und im Seitentitel des Browsers sieht.
icon	Ändert das aguila-Icon, das der Benutzer für diesen Tab in der Seitenleiste und vor dem Seitentitel des Browsers sieht.

Beispiel

Dieses Beispiel zeigt die Anwendung der Funktion in Kombination mit der Funktion sub.

/* global sc */

module.exports = home => {
  home.sub('sample.package.broadcast.channel.title.' + sc.loginUser.UUID, () => {
    home.updateTab({
      name: 'sample.package.tab.test',
      text: 'Test-Tab neuer Titel'
      icon: 'agorum:rounded-square-5;color=LightSeaGreen;scale=.9|ionicon:search;color=white;scale=.8',
    });
  });
};

refresh

Signalisiert agorum.home, dass neue Tabs verfügbar sind oder bisher vorhandene Tabs nicht mehr existieren.

Das System aktualisiert die Seitenleisten aller aktuell geöffneten Anmeldungen des Benutzers.

Syntax

home.refresh(<changedTabs>);

Parameter

Parameter	Beschreibung
changedTabs (optional)	Definiert ein Array mit den Namen von Tabs, die sich inhaltlich geändert haben. Ist ein hier aufgeführter Tab geöffnet, erzeugt agorum.home ihn neu, um ihn zu aktualisieren.

Beispiel

Dieses Beispiel zeigt die Anwendung der Funktion in Kombination mit der Funktion sub.

module.exports = home => {
  home.sub('sample.package.broadcast.channel.changed.' + sc.loginUser.UUID, () => home.refresh());
};

sub

Registriert einen provider für einen broadcast-Kanal, um etwa auf Änderungen von Objekten zu reagieren oder sich mit anderen Komponenten austauschen zu können.

agorum.home löst diese Registrierung automatisch wieder auf, wenn das System den provider nicht mehr benötigt.

Syntax

home.sub(<channel>, <handler>);

Parameter

Parameter	Beschreibung
channel	Definiert den Namen des Kanals, für den die Registrierung gilt.
handler	Funktion, die das System aufruft, wenn der Kanal eine Nachricht empfangen hat.

Beispiel

Dieses Beispiel zeigt die Anwendung der Funktion.

module.exports = home => {
  home.sub('object-updated-' + object.UUID, () => {
    // Das Objekt 'object' wurde geändert, nun könnten etwa Titel und Icon eines Tabs aktualisiert werden.
  });
};

Beispiele

Die Objekt-Info eines Objekts anzeigen

home.registerTab({
  // name muss eindeutig sein
  name: 'meine.grundlagen.beispiele.menu',
  text: 'Menü',
  // icon kann über Icon erstellen designt werden
  icon: 'ionicon:fast-food-outline;color=DarkRed;slot=center;scale=2;translate=0.14,0',
  aon:{
    type: 'agorum.composite.details',
    // Pfad des darszustellenden Objektes
    id: '/agorum/roi/Files/agorum academy Schulung - Grundlagen zur Erstellung eigener Konfigs/Anpassung der Seitenleiste/Kantinenessen.html'
  }
});

Die Suche anzeigen

home.registerTab({
  name: 'meine.grundlagen.beispiele.acic.reklamationen.anfragen',
  text: 'Suche Reklamationen & Anfragen',
  icon: 'ionicon:document-text-outline;slot=left;scale=1.51|mdi:thumb-down;color=FireBrick;slot=top-right;scale=0.86;translate=0.1,0|mdi:thumb-up;color=SeaGreen;slot=bottom-right;scale=0.86;translate=0.1,0',
  aon:{
    type: 'agorum.composite.acic',
    settingName: 'meine.grundlagen.beispiele - FilterAnfragen & Reklamationen'
  }
});

Tipp: Sie holen sich den settingName mit der Aktion Search query builder im agorum core template manager. Sie wählen dort den anzuzeigenden Filter aus. Der in der Oberfläche angezeigte Parameter selectedSettingName zeigt den Wert an, den Sie bei settingName eintragen.

Ein aguila-Widget anzeigen

home.registerTab({
  name: 'meine.grundlagen.beispiele.aguila.spiel-widget',
  text: 'Demo',
  icon: 'agorum:rounded-square-5;color=MediumVioletRed;scale=0.9|agorum:agorum-logo;color=white;scale=0.81',
  aon:{
    // Registrierungsname des Widgets
    type: 'meine.grundlagen.beispiele.spielWidget'
  }
});

Tipp: Damit das Widget der Darstellung des Explorers ähnelt, arbeiten Sie mit einem agorum.border-Widget.

Beispielcode

/* jshint unused: true */

let aguila = require('common/aguila');

let widget = aguila.create({
  type: 'agorum.border',
  // Breite & Höhe ist für die Integration in die Seitenleiste egal, aber wichtig, wenn man jetzt im Skript auf RUN klicken kann
  width: 800,
  height: 600,
  docked: {
    center: {
      type: 'agorum.composite.form.basic',
      labelPosition: 'top',
      border: true,
      elements: [
        {
          type: 'agorum.composite.form.element.text',
          label: 'Text',
          name: 'text'
        }
      ]
    }
  }
});

widget;

Die Webseite anzeigen

home.registerTab({
  name: 'meine.grundlagen.beispiele.url',
  text: 'MonkeyUser.com',
  icon: 'agorum:rounded-square-5;color=#0069b5|ionicon:happy-outline;color=white',
  url: 'https://www.monkeyuser.com/'
});

Den Zugriff einer App in der Seitenleiste berechtigen

Soll der neue Eintrag in der Seitenleiste nicht jedem Benutzer zur Verfügung stehen, berechtigen Sie den Befehl mit folgenden Code-Zeilen:

if (objects.mayDiscover('<ACL>')) {
}

Setzen Sie die IF-Bedingung um den entsprechenden home.registerTab, etwa:

if (objects.mayDiscover('<ACL>')) {
  home.registerTab({
    name: 'meine.grundlagen.beispiele.acic.reklamationen.anfragen',
    text: 'Suche Reklamationen & Anfragen',
    icon: ...
    ...
    }
  });
}

Die Seitenleiste nachträglich anpassen

Sie können die Seitenleiste über die Funktion finalize anpassen, nachdem das System die Seitenleiste vollständig geladen hat.

Gängige Einsatzzwecke sind:

Entfernen einer vorhandenen Explorer-Konfiguration aus dem smart assistant, um diese durch eine eigene Einsprungspunkt-Konfiguration eines Add-ons zu ersetzen.
Entfernen von Standard-Seitenleisten-Einträgen, die nicht gewünscht sind und nicht per ACL entfernbar sind.
Ändern von Standard-Seitenleisten, etwa durch Ändern des Symbols oder des Texts.

Die Funktion „finalize“ verwenden

Registrieren Sie die Funktion finalize in Ihrem provider.js-Code folgendermaßen:
```
module.exports.finalize = home => {
  // home.tabs
};
```
Ergebnis: Das System ruft die Funktion auf, wenn alle bisherigen provider durchlaufen und alle Tabs gesammelt wurden.

Durch die Modifikation von home.tabs können Sie dann Einfluss auf die vorhandenen Tabs der Seitenleiste nehmen.

Beispiele

Den Standard-Explorer-Eintrag entfernen

Folgendes Beispiel entfernt den Standard-Explorer-Tab aus der Seitenleiste:

module.exports.finalize = home => {
  home.tabs = home.tabs.filter(tab => {
    return tab.name !== 'agorum.asa.Einstieg';
  });
};

Tipp: Um herauszufinden, wie ein Tab heißt:

Integrieren Sie console.log in die Funktion finalize:

module.exports.finalize = home => {
  console.log('Home-Tabs', home.tabs);
};

Prüfen Sie in der Browser-Konsole, wie die Tabs benannt sind.

Ein Symbol und den Text des Standard-Explorer-Eintrags ändern

module.exports.finalize = home => {
  // finden des explorer tabs
  let explorerTab = home.tabs.find(tab => tab.name === 'agorum.asa.Einstieg');

  if (explorerTab) {
    explorerTab.icon = 'agorum:agorum-logo;color=#003f85';
    explorerTab.text = 'Mein Explorer';
  }
};

Der Explorer besitzt jetzt in der Seitenleiste ein agorum-Symbol und den Text Mein Explorer.

Hinweis: Wenn Sie diesen Code verwenden, kann der Benutzer Icons oder Texte für diesen Eintrag nicht mehr anpassen.

Die Reihenfolge der Tabs ändern

Da die Tabs ein JavaScript-Array sind, können Sie diese umsortieren.

Folgendes Beispiel dreht die Reihenfolge der Tabs um:

module.exports.finalize = home => {
  // Reihenfolge umdrehen
  home.tabs = home.tabs.reverse();
};

Hinweis: Wenn Sie diesen Code verwenden, kann der Benutzer die Reihenfolge der Tabs nicht mehr bestimmen.