API für Komponenten in edoc automate

Alle Komponenten in edoc automate sind eigenständige Plug-Ins. Sie können jederzeit eigene neue Aktionen hinzufügen.

In edoc automate sind zwei Arten von Komponenten definiert:

• Komponenten, die standardmäßig die in edoc automate mitgeliefert werden.

• Komponenten, die Sie als App-Entwickler:in definieren. Sie können eigene Komponenten nur in edoc automate verwenden.

Beide Komponentenarten sind gleichwertig, sie unterscheiden sich jedoch im verwendeten Namespace und dem Speicherort in der App.

Klassendiagramm für Komponenten

Sie können Komponenten auch als übergeordnete und untergeordnete Komponenten verwenden.

Standard für Namespaces

Standardaktionen finden Sie unter:

<?php 
// Namespace for system components
namespace edoc\appserver\app\components;

Ihre eigenen Plug-Ins speichern Sie unter:

<?php
// Namespace for app components
namespace edoc\appserver\app\components\plugins;

Hinzufügen von eigenen App-Komponenten

Wenn Sie eigene Komponenten in Ihrer App entwickeln möchten, müssen Sie ein neues Plug-In im App-Ordner /<app>/plugins/components z.B. per WebDAV erstellen.

So geht’s

1. Erstellen Sie im Ordner /<app>/plugins/components einen neuen Ordner mit dem Namen der Komponente. Der Name des Ordners, der Datei und der Klasse müssen übereinstimmen.

2. Erstellen Sie in dem Ordner eine neue Datei mit demselben Namen und der Endung .php (z.B. Number.php)

3. Öffnen Sie die Datei mit einem beliebigen Texteditor.

4. Fügen Sie folgenden Inhalt in die Datei ein:

   PHP

   <?php
   
   namespace edoc\appserver\app\components\plugins;
   
   use edoc\appserver\app\AbstractComponent;
   
   class Number extends AbstractComponent
   {
     public function init()
     {
       // Set name, description and icon
       $this->setMetadata('Number', 'Component for numbers', 'component-input');
       
       // Set component group
       $this->setGroup('text');
       
       // Add properties
       $this->addProperty('Min', 'number' ['min' => 0, 'value' => '0']); // since 22.3.x you can use self::PROP_TYPE_NUMBER
       $this->addProperty('Max', 'number');
       
       // Add system-events.
       $this->registerEvent('input', new UpdateValue($this));
     }
     
     public function htmlContent()
     {
       $html = '...';
       
       return $html;
     }
     
   }
   

5. Speichern Sie die Datei mit dem korrekten Encoding: UTF-8 ohne BOM.

Sie können die neue Komponente im edoc automate-Editor verwenden.

Möglicherweise müssen Sie edoc automate erneut laden, damit Sie die Aktion verwenden können.

Eine Auflistung möglicher Eigenschaftstypen finden Sie unter: Übersicht zu den Eigenschaftstypen für Komponenten in edoc automate

Traits: Die PHP-Methode zum Wiederverwenden von Code

edoc automate verwendet Traits, um der Komponente verschiedene Eigenschaften hinzufügen, die dann in allen Komponenten gleich sind.

Folgende Traits können Sie verwenden:

• \edoc\appserver\app\component\Editable: Aktiviert die Eigenschaft, mit der Sie die Editierbarkeit eine Komponente auch mit Aktionen ändern können.

• \edoc\appserver\app\component\Visibility: Aktiviert die Eigenschaft, mit der Sie die Sichtbarkeit einer Komponente auch mit Aktionen ändern können.

• \edoc\appserver\app\component\Disableable: Aktiviert die Eigenschaft, mit der Sie die Komponente aktivieren und deaktivieren können.

• \edoc\appserver\app\component\PropertyClass: Fügt einer Komponenten die Eigenschaft Class hinzu, um CSS-Klassen festzulegen.

• \edoc\appserver\app\component\PropertyMaxLength: Fügt einer Komponenten die Eigenschaft Max Length hinzu, um die maximale Länge für eingegebene Texte festzulegen.

Komponenten mit Unterkomponenten

Sie können neue Komponenten definieren, die an bestimmten Stellen ebenfalls Komponenten beinhalten, z.B. Table, Columns oder Container.

Für diese Komponenten müssen Sie als übergeordnete (parent) Klasse edoc\appserver\app\AbstractEmbeddedComponent; anstelle von edoc\appserver\app\AbstractComponent; verwenden.

Alle Instanzen für die untergeordneten (child) Klassen müssen Sie in der Klasseneigenschaft components in einem mehrdimensionalen Array mit Zeilen und Spalten speichern.

Beispiel für untergeordnete und übergeordnete Komponenten

<?php

namespace edoc\appserver\app\components\plugins;

use edoc\appserver\app\AbstractEmbeddedComponent;

class ComponentWithChildren extends AbstractEmbeddedComponent
{
    protected function initEmbedded()
    {
    }
    
    public function htmlContent()
    {
      $html = '...';
      
      return $html;
    }
    
    public function getComponentByName($name)
    {
      // search in $this->components
      return false;
    }
    
    public function getComponentById($id)
    {
      // search in $this->components
      return false;
    }
}

Anzeigen der Dokumentation für eigene Komponenten

Sie können die Dokumentation für die eigenen Komponenten anzeigen, indem Sie über der Klasse einen Kommentar im DocBlock-Format definieren. In edoc automate wird ein leicht angepasstes DocBlock-Format verwendet, das ggf. nicht von allen Standard-DocBlock-Parsern korrekt interpretiert wird.

Gut zu wissen

Sie können die Texte in der Dokumentation mit Markdown-Befehlen formatieren:

• Nur die Formatierungen Fett und Kursiv werden unterstützt.

• Zeilenumbrüche fügen Sie mit \n ein.

Beispiel für die Dokumentation

<?php

namespace edoc\appserver\app\components\plugins;

use edoc\appserver\app\AbstractComponent;

/**
 * Number Component
 *
 * Component to enter numbers. 
 *
 * @param NUMBER $Min Min Number
 * @param NUMBER $Max Max Number
 *
 */
class Number extends AbstractComponent
{
  // ...
}

Verwenden von Bootstrap für eigene Komponenten

Wenn Sie für die Erstellung eigener Komponenten das Bootstrap-Framework verwenden möchten, müssen Sie folgende Punkte berücksichtigen:

• Version: Die verwendete Version muss mit der von edoc automate verwendeten Bootstrap-Version kompatibel sein.

• Assets: Zusätzlich benötigte JavaScript-Librarys (Bootstrap, Popper.js usw.) und CSS-Styles müssen Sie selbst in Ihrer App oder über die Komponente einbinden.

• Modal: Wenn die eigene Komponente in einem Modal angezeigt werden soll und JavaScript-Funktionen von Bootstrap benötigt, müssen Sie in der Komponente das Attribut data-eas-modal-propagate-click="true" festlegen. Nur mit diesem Attribut werden click-Events der Komponente an übergeordnete Elemente des Modals weitergeleitet.