Standardfunktionen im Explorer überschreiben

Sie können Standardfunktionen im Explorer durch ein Skript überschreiben. Sie können Folgendes anpassen:

• das Hauptmenü,
• das Kontextmenü,
• die Toolbar im Explorer,
• die Aktion beim Öffnen.

Die Konfiguration erfolgt über Property-Bundles und eine Property-Group in der MetaDB sowie über ein JavaScript.

Einbinden eines override-Skripts

Gehen Sie wie folgt vor, um die Standardeinstellung für Hauptmenü, Kontextmenü, Toolbar oder die Aktion beim Öffnen zu überschreiben.

1. Öffnen Sie links in der Seitenleiste Administration und erstellen Sie das neue Skript, etwa unter folgendem Pfad im Administrationsbereich:

   Root/agorum/roi/customers/agorum.doc.test/js/override/explorer.js

2. Legen Sie ein neues Modul in der MetaDB an. Öffnen Sie dazu links in der Seitenleiste Administration und dann MetaDB.
3. Rufen Sie folgenden Pfad auf:

   MAIN_MODULE_MANAGEMENT/customers/agorum.explorer
   

4. Legen Sie über folgendes Property-Bundle an und rufen Sie es danach auf:
   Name: settings
5. Legen Sie über eine Property-Group an und rufen Sie sie danach auf. Idealerweise verwenden Sie einen Projektnamen:
   Name: name-des-projekts

    

   

   Beispiel für eine Property-Group mit Projektnamen
6. Legen Sie über ein Property-Bundle an und rufen Sie es danach auf. Idealerweise verwenden Sie einen Namen, der die Verwendung genauer spezifiziert:
   Name: name-des-bundles

    

   

   Beispiel für ein Property-Bundle mit Namen
7. Legen Sie im zuletzt angelegten Property-Bundle über das folgende Property-Entry an:
   
   Name: js
   Datentyp: Zeichenkette (String)
   Wert (String): <Pfad zur erstellten JavaScript-Datei und Name der Datei ohne Dateiendung>

    

   

   Beispiel für ein JavaScript Property-Entry mit Pfadangabe
8. Optional können Sie ein weiteres Property-Entry mit dem Schlüssel (Namen) acl anlegen, um einzuschränken, für wen das Skript geladen werden soll. Die ACL-Gruppe geben Sie als Wert an.

override-Skript schreiben

Sie können mit einem override-Skript Einträge im Hauptmenü, im Kontextmenü oder in der Toolbar ergänzen oder ändern. Außerdem können Sie die Aktion ändern, die beim Öffnen eines Objekts ausgeführt wird. Dazu verwenden Sie verschiedene Overrides:

• mainMenuOverride: Ändert das Hauptmenü
• menuOverride: Ändert das Kontextmenü
• toolbarOverride: Ändert die Toolbar in den Ordnerdetails
• openOverride: Ändert die Aktion, die beim Öffnen eines Objekts ausgeführt wird, etwa durch einen Doppelklick
• itemOverride: Ändert die CSS-Klasse, die für die Anzeige eines Eintrags in einem Baum oder einer Liste verwendet wird, also das Layout des Eintrags, siehe itemOverride

Das folgende Beispiel zeigt, wie Sie eine Gruppe von Einträgen zum Kontextmenü und eine Schaltfläche zur Toolbar in den Ordnerdetails hinzufügen können.

Hinzugefügte Gruppe im Kontextmenü und Schaltfläche in der Toolbar

let icons = require('/agorum/roi/customers/agorum.icons/js/icons');

exports.settings = user => [
  {
    name: 'agorum.doc.test.override',

    // Fügt eine Gruppe neuer Einträge zum Kontextmenü hinzu
    menuOverride: (items, objs, parent) => {
      console.log('menu override called', items, objs, parent);
      items = [
        {
          name: 'testGroup',
          icon: 'aguila-icon settings_ethernet',
          text: 'Testgruppe',
          type: 'group',
          items: [
            {
              name: 'testAction', // Name der Aktion
              text: 'Test als Aktion',
              type: 'action',
              icon: icons.cls('agorum:agorum-logo;color=#0069b5'),
            },
            {
              name: 'testHandler',
              text: 'Test mit Handler',
              handler: () => console.log('Test-Handler'),
            },
          ],
        },
        '-',
      ].concat(items);
      return items;
    },
    // Fügt eine Schaltfläche zur Toolbar in den Ordnerdetails hinzu
    toolbarOverride: (items, objs, parent) => {
      console.log('toolbar override called', items, objs, parent);
      items.push({
        type: 'agorum.button',
        meta: {
          parent: parent,
          objects: objs,
          //action: 'testActionTB',
          //structure: 'testStructureTB',
        },
        tooltip: 'Test-Aktion auf Toolbar',
        icon: icons.cls('mdi:person;color=#0069b5'),
        disabled: !objs[0],
      });
      //return [];
      return items;
    },
  },
];

Eintrag im Kontextmenü ergänzen

Sie können mit einem Skript nach folgendem Muster einen einzelnen neuen Eintrag im Kontextmenü ergänzen, etwa den Eintrag:

exports.settings = user => [
  {
    // eindeutiger Name
    name: 'my-context-menu',

    /**
     * menuOverride: Wird aufgerufen, nachdem das Menü durch den Explorer erstellt wurde
     * Parameters:
     *   items: Die Menü-Items (Array der erstellten Menü-Items)
     *   objects: Das Array der agorum core-Objekte, die durch den Explorer selektiert wurden
     *   parent: Das zugehörige parent folder object, von dem das Kontextmenü geöffnet wurde (optional)
     */
    menuOverride: (items, objects, parent) => {
      // Fügt einen neuen Eintrag zum Kontextmenü hinzu
      items.push({
        // Zeigt das Menü-Item als inaktiv an (true/false)
        disabled: false,

        // Der Handler, der aufgerufen wird, wenn das Menü-Item angeklickt wird
        handler: () => {
          let names = '';
          let parentName = '';

          if (objects) names = objects.map(item => item.name).join(', ');
          if (parent) parentName = parent.name;

          console.log('Das folgende Menü-Item wurde angeklickt: Objects: ' + names + ', Parent: ' + parentName);
        },

        // Icon für den Menü-Eintrag
        icon: 'aguila-icon sentiment_satisfied',

        // Eindeutiger Name für den Menü-Eintrag
        name: 'my-menu-entry-1',

        // Der Text des Menü-Eintrags
        text: 'My new menu entry',
      });

      return items;
    },
  },
];

Einträge aus dem Kontextmenü entfernen

Sie können Einträge entfernen und nur noch bestimmte Einträge zulassen, auch abhängig von der Benutzergruppe, indem Sie

1. eine Liste von zulässigen Einträgen definieren und
2. alle anderen Einträge für bestimmte Benutzergruppen unter bestimmten Bedingungen aus dem Kontextmenü entfernen

Sie könnten etwa das Kontextmenü für das Starten von Workflows auf folgende Einträge reduzieren

Das können Sie mit einem Skript nach folgendem Muster erreichen:

let icons = require('/agorum/roi/customers/agorum.icons/js/icons');
let objects = require('common/objects');
let beans = require('common/beans');

let tokenAllowed = {
  startWorkflow: true,
  Detailsanzeigen: true,
};

let removeItem = (items, objects, allowed, selectors) => {
  if (objects.some(obj => beans.selected(obj, selectors))) {
    items = items.filter(item => allowed[item.name]);
  }

  return items;
};

exports.settings = user => [
  {
    // eindeutiger Name
    name: 'my-context-menu',

    menuOverride: (items, objects, parent) => {
      console.log('context menu override called', items, objects);
      if (!sc.adminEnabled) {
         items = removeItem(items, objects, tokenAllowed, '<REPLACESELECTOR>'); 
      }
      return items;
    },
  },
];

Toolbar-Schaltfläche ergänzen

Sie können mit einem Skript nach folgendem Muster ein Toolbar-Icon ergänzen, etwas das Icon:

 

let icons = require('/agorum/roi/customers/agorum.icons/js/icons');

exports.settings = user => [
  {
    name: 'agorum.doc.test.override',

    toolbarOverride: (items, objs, parent) => {
      console.log('toolbar override called', items, objs, parent);
      items.push({
        type: 'agorum.button',
        meta: {
          parent: parent,
          objects: objs,
          //action: 'testActionTB',
          //structure: 'testStructureTB',
        },
        tooltip: 'Test-Aktion auf Toolbar',
        icon: icons.cls('mdi:person;color=#0069b5'),
        disabled: !objs[0],
      });
      //return [];
      return items;
    },
  },
];

Die Einstellung disabled: !objs[0] führt dazu, dass das Icon nur aktiv wird, wenn der Benutzer einen Eintrag im Explorer ausgewählt hat, wie hier gezeigt:

Aktivieren eines Icons nur bei aktiver Auswahl

Hauptmenü-Icon ergänzen

Sie können mit einem Skript nach folgendem Muster ein Hauptmenü-Icon ergänzen, etwas das Icon :

let icons = require('/agorum/roi/customers/agorum.icons/js/icons');

exports.settings = user => [
  {
    name: 'agorum.doc.test.override',

    mainMenuOverride: (items, objs) => {
      console.log('main menu override called', items, objs);
      items.push({
        type: 'agorum.button',
        tooltip: 'Test-Aktion im Hauptmenü',
        icon: 'aguila-icon directions_subway',
      });
      //return [];
      return items;
    },
  },
];

Öffnen eines externen E-Mail-Programms bei bestimmten Benutzern

In diesem Beispiel wird für bestimmte Benutzer anstelle der eingebauten E-Mail-Anzeige ein externes E-Mail-Programm geöffnet. Dazu wird geprüft, ob der Benutzer eine bestimmte ACL hat (in diesem Fall ACLDemo) und für Benutzer mit dieser ACL der externe E-Mail-Client geöffnet.

/* global sca */

let icons = require('/agorum/roi/customers/agorum.icons/js/icons');
let objects = require('common/objects');
let beans = require('common/beans');

exports.settings = user => {
  let redirectMailOpen = objects(sca.asUser(user)).mayDiscover('ACLDemo');

  return [
    {
      name: 'agorum.doc.test.override',

      openOverride: (items, objs) => {
        console.log('openOverride', redirectMailOpen, items);

        if (redirectMailOpen) {
          /*
          let isMail = items.some(
            item => item.name === '_mail' || item.name === '_mailDraft' || item.name === 'agorum.mail.open'
          );
          */
          let isMail = objs.every(obj => beans.selected(obj, '[classname=/MailObject|AMailMail/]'));

          if (isMail) {
            return [
              {
                name: '_openClient',
              },
            ];
          }
        }

        return items;
      },
    },
  ];
};

open-Aktionen verhindern

Sie können durch die Verwendung von openOverride jegliche open-Aktionen verhindern, etwa um Fallbacks bei Ordnern zu verhindern.

exports.settings = user => [
  {
    name: 'agorum.doc.test.override',
    openOverride: (items, objs) => {
      console.log('open override called', items, objs);
      // keine Aktion ausführen
      return [{}];
    },
  },
];

Verhalten für Widget überschreiben

Mit asa.registerOpen können Sie das Öffnen-Verhalten für ein spezifisches Widget überschreiben und mit asa.registerMenu das Kontextmenü für ein spezifisches Widget. 

Diese Overrides gelten nicht nur für das Widget, auf dem sie registriert wurden, sondern auch für alle darin enthaltenen Widgets (sofern es „weiter unten“ im Widget-Baum keine weiteren Overrides gibt). Wenn man sie etwa auf agorum.explorer registriert, dann gelten sie für die enthaltenen Baum-, Listen- und Breadcrumb-Widgets.

asa.registerOpen

Wenn Sie in einem benutzerdefinierten Widget ein eigenes Öffnen-Verhalten implementieren möchten, ohne das globale Explorer-Verhalten zu ändern, können Sie dazu asa.registerOpen verwenden.

1. Binden Sie zuerst die asa-Bibliothek ein:

   let asa = require('/agorum/roi/customers/agorum.explorer/js/aguila/asa');

2. Erstellen Sie das Widget, z. B. einen Baum.
3. Registrieren Sie den Custom-Handler für das Öffnen-Verhalten in diesem Widget:

   // Register a custom handler for opening objects
   asa.registerOpen(widget, (id, params) => {
     console.log('Custom open handler called', id, params);
     
     // params contains:
     // - parentId: UUID of the parent object
     // - canEnter: boolean, whether the object can be entered
     // - action: name of the default action
     
     if (params.canEnter) {
       // custom logic for folders
       console.log('Opening folder:', id);
       // e.g. navigation to another area
     } else {
       // custom logic for documents
       console.log('Opening document:', id);
       // e.g. custom viewer
     }
   });

asa.registerMenu

Wenn Sie in einem benutzerdefinierten Widget (z. B. einem Baum oder einer Liste) menüspezifische Anpassungen vornehmen möchten, die nur für dieses Widget gelten, können Sie dazu asa.registerMenu verwenden.

1. Binden Sie zuerst die asa-Bibliothek ein:

   let asa = require('/agorum/roi/customers/agorum.explorer/js/aguila/asa');

2. Erstellen Sie ein Widget, z. B. einen Baum.
3. Registrieren Sie den Custom-Handler für das Kontextmenü in diesem Widget:

   // register menu handler
   asa.registerMenu(widget, (items, objs, parent) => {
     // removes certain entries
     items = items.filter(item => item.name !== '<name>');
     
     // adds certain entries
     if (objs.length === 1 && objs[0].isFolder) {
       items.push({
         ...
         },
       });
     }
     
     return items;
   });

Parameter

Für die möglichen Angaben zu den Items siehe agorum core aguila.