Der Tab-Leiste eigene Tabs hinzufügen

Sie können eigene Tabs in die Tab-Leiste (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:

1. Öffnen Sie links in der Seitenleiste Explorer.
2. Öffnen Sie Ihr Konfigurationsprojekt und dort den Ordner js unter:

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

3. Legen Sie über das Kontextmenü und die Aktion Neu den Ordner home an.
4. Legen Sie im Ordner home über das Kontextmenü und die Aktion Neu die JavaScript-Datei provider.js an.
5. Befüllen Sie die Datei provider.js mit den existierenden JavaScript-Funktionen für einen provider.
6. 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.

Das home-Objekt

Das home-Objekt, das als Parameter übergeben wird, enthält folgende Eigenschaften:

Beispiel

module.exports = home => {
  if (home.env === 'desktop') {
    // Dieser Tab wird nur auf Desktop angezeigt
    home.registerTab({
      name: 'mein.desktop.tab',
      text: 'Desktop-Tab',
      icon: 'mdi:desktop',
      aon: { type: 'mein.desktop.widget' }
    });
  }

  if (home.env === 'mobile') {
    // Dieser Tab wird nur auf Mobile angezeigt
    home.registerTab({
      name: 'mein.mobile.tab',
      text: 'Mobile-Tab',
      icon: 'mdi:cellphone',
      aon: { type: 'mein.mobile.widget' }
    });
  }
};

registerTab

Registriert einen neuen Tab in der Seitenleiste.

Syntax

home.registerTab(<tab>);

Felder zum Parameter „tab“

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

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'
  });
};

Vordefinierte Tab-Typen

Das System stellt folgende vordefinierte Tab-Typen bereit, die Sie direkt verwenden können:

Typ "tree"

Zeigt einen Ordnerbaum mit konfigurierbaren Root-Ordnern an.

Erforderliche Felder:

• roots: Array von Ordner-IDs (Pfade oder UUIDs)

Optionale Felder:

• name, text, icon: Werden automatisch vom ersten Root-Ordner übernommen, falls nicht angegeben

Beispiel:

home.registerTab({
  type: 'tree',
  roots: ['<…>']
});

Typ "details"

Zeigt die Objekt-Info eines bestimmten Objekts an.

Erforderliche Felder:

• id: Objekt-ID (Pfad oder UUID)

Optionale Felder:

• name, text, icon: Werden automatisch vom Objekt übernommen, falls nicht angegeben

Beispiel:

home.registerTab({
  type: 'details',
  id: '<…>'
});

updateTab

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

Syntax

home.updateTab(<tab>);

Felder zum Parameter "tab"

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

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

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.
  });
};

Unterschiede zwischen Desktop und Mobile

Die mobile Ansicht von agorum core unterstützt nur Tabs mit einem aon-Widget. Tabs, die ausschließlich eine externe URL anzeigen, werden in der mobilen Ansicht automatisch ausgefiltert.

Sie können im Provider zwischen Desktop- und Mobile-Ansicht unterscheiden, um unterschiedliche Tabs für die jeweilige Umgebung bereitzustellen:

module.exports = home => {
  if (home.env === 'desktop') {
    // Dieser Tab ist nur auf Desktop verfügbar
    home.registerTab({
      name: 'mein.desktop.tab',
      text: 'Desktop-Tab',
      icon: 'mdi:desktop',
      aon: { type: 'mein.desktop.widget' }
    });
  }

  if (home.env === 'mobile') {
    // Dieser Tab ist nur auf Mobile verfügbar
    home.registerTab({
      name: 'mein.mobile.tab',
      text: 'Mobile-Tab',
      icon: 'mdi:cellphone',
      aon: { type: 'mein.mobile.widget' }
    });
  }

  // Dieser Tab ist auf Desktop und Mobile verfügbar
  home.registerTab({
    name: 'mein.universal.tab',
    text: 'Universal-Tab',
    icon: 'mdi:view-dashboard',
    aon: { type: 'mein.universal.widget' }
  });
};

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'
  }
});

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'
  }
});

/* 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;

Eine 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/'
});

Einen Workflowfilter anzeigen

/* global sc */
let objects = require('common/objects');

module.exports = home => {
  home.registerTab({
    name: 'agorum.doc.test.acworkflow.tasks',
    text: 'Workflow-Aufgaben (Dokumentation)',
    aon: {
      type: 'agorum.composite.acic',
      settingName: 'acworkflow.tasks',
    },
  });
};

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

1. 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';
  });
};

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.

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();
};