mirror of
https://github.com/OpenXE-org/OpenXE.git
synced 2024-11-15 20:47:15 +01:00
430 lines
12 KiB
Markdown
430 lines
12 KiB
Markdown
|
|
# lib Versandarten
|
|
|
|
Jede Versandart besteht aus einer .php-Datei. Zusätslich können unter `content` weitere *.tpl Dateien abgelegt werden.
|
|
|
|
Der Klassenname besteht aus `Versandart_{dateiname}`.
|
|
|
|
Die Klasse muss von der Klasse `Versanddienstleister` erben, welche wenn nötig noch importiert werden muss:
|
|
|
|
```php
|
|
<?php
|
|
if (!class_exists('Versanddienstleister')) {
|
|
require_once dirname(__DIR__) . '/class.versanddienstleister.php';
|
|
}
|
|
|
|
class Versandart_example extends Versanddienstleister
|
|
{
|
|
// ...
|
|
}
|
|
```
|
|
## ZukunftsWünsche:
|
|
Wenn die Versandarten überarbeitet werden oder in den neuen Codebereich übernommen werden, wäre
|
|
eine **mehrstufige GUI** zum Einrichten der Versandarten wünschenswert. Dies wird mindestens in den Versandarten
|
|
``Parcelone`` und ``Sendcloud`` verwendet.
|
|
- In Stufe #1 werden die API-Zugangsdaten abgefragt.
|
|
- In Stufe #2 werden zusätzliche Daten von der API abgeholt (und zur Auswahl gestellt).
|
|
|
|
## Methoden
|
|
|
|
Folgende Methoden müssen implementiert werden:
|
|
- `public function __construct($app, $id)`
|
|
- `public function GetBezeichnung()`
|
|
- `public function EinstellungenStruktur()`
|
|
- `public function Paketmarke($doctyp, $id, $target = '', $error = false, &$adressdaten = null)`
|
|
- `public function PaketmarkeDrucken($id, $sid)`
|
|
|
|
|
|
### __construct
|
|
|
|
`public function __construct($app, $id)`
|
|
|
|
Im Konstruktor werden die Einstellungen der Versandart geladen. Ebenso werden der Paketmarken- & Exportdrucker geladen.
|
|
|
|
### GetBezeichnung
|
|
|
|
```php
|
|
/**
|
|
* @return string
|
|
*/
|
|
public function GetBezeichnung()
|
|
```
|
|
|
|
Ich glaube, diese Methode wird gar nicht verwendet.
|
|
Der Name der Versandarten wird in der Methode Appstore::getAppList() in einem Array hinterlegt.
|
|
Zu finden ist diese Methode in ``www/pages/appstore.php``.
|
|
Der Aufbau sieht wie folgt aus:
|
|
|
|
```php
|
|
$apps = array(
|
|
// ...
|
|
'versandarten_dpdesolutions' [
|
|
'Bezeichnung' => 'DPD eSolutions',
|
|
'Link' => 'index.php?module=versandarten&action=list',
|
|
'Icon' =>' Icons_dunkel_9.gif',
|
|
'Versionen' => 'OSS,PRE,ENT',
|
|
'kategorie' => '{|Versandarten|}')
|
|
],
|
|
);
|
|
```
|
|
|
|
### EinstellungenStruktur
|
|
|
|
```php
|
|
/**
|
|
* @return array
|
|
*/
|
|
public function EinstellungenStruktur()
|
|
```
|
|
|
|
Erstellt die Eingabenmaske unter `/index.php?module=versandarten&action=create`
|
|
|
|
Unterstützt werden derzeit folgende Felder:
|
|
- textarea
|
|
- checkbox
|
|
- select
|
|
- submit
|
|
- custom (Key 'function' als callback)
|
|
|
|
### Paketmarke
|
|
|
|
```php
|
|
/**
|
|
* @param string $doctyp 'lieferschein' / 'versand' / 'retoure'
|
|
* @param string|int $id '1'
|
|
* @param string $target '#TAB1'
|
|
* @param bool $error
|
|
* @param null|array $adressdaten
|
|
*
|
|
* @return array List of error messages
|
|
*/
|
|
public function Paketmarke($doctyp, $id, $target = '', $error = false, &$adressdaten = null)
|
|
```
|
|
|
|
Diese Methode wird von folgenden Endpunkten aus aufgerufen:
|
|
- [Lager -> Lieferschein](index.php?module=lieferschein&action=paketmarke&id={id})
|
|
- [Lager -> Versandzentrum](index.php?module=versanderzeugen&action=frankieren&id={id})
|
|
- [Lager -> Retoure](index.php?module=retoure&action=paketmarke&id={id})
|
|
|
|
Die Variable `$adressdaten` ist in diesem Fall null.
|
|
|
|
Zudem wird diese Methode von `PaketmarkeDrucken()` aufgerufen. In diesem Fall enthält das Array `$adressdaten` die Adressdaten. Sie müseen in diesem Fall *nicht* via `$this->app->Secure->GetPOST()` abgefragt werden.
|
|
|
|
Der Parameter `$doctyp` enthält, abhängig von dem verwendeten Endpunkt eine der folgenden Strings:
|
|
- lieferschein
|
|
- versand
|
|
- retoure
|
|
|
|
`$id` enthält die ID (als String oder Integer) der auszuwertenden Resource.
|
|
|
|
`$target` enthält einen String wie '#TAB1' oder ist leer. Ist dieser Wert gesetzt, muss das Template geparsed werden. Ein leerer String deutet vermutlich auf einen *internen* Aufruf ohne GUI hin.
|
|
|
|
Genutzt wird diese Methode in `erpAPI::Paketmarke()`
|
|
|
|
@file class.erpapi.php:21640 (Stand 06.2019)
|
|
```php
|
|
<?php
|
|
//WAWICORE
|
|
class erpAPI
|
|
{
|
|
// ...
|
|
//@refactor versanddiestleister Modul
|
|
function Paketmarke($parsetarget,$sid="",$zusatz="",$typ="DHL")
|
|
{
|
|
// ...
|
|
// 22042
|
|
$error = $obj->Paketmarke($sid!=''?$sid:'lieferschein',$id);
|
|
// ...
|
|
// 22568
|
|
$error = $obj->Paketmarke($sid!=''?$sid:'lieferschein',($sid=='versand'?$id:$tid), $parsetarget, $error);
|
|
// ...
|
|
}
|
|
// ...
|
|
}
|
|
```
|
|
|
|
### PaketmarkeDrucken
|
|
|
|
```php
|
|
/*
|
|
* @param int|string $id
|
|
* @param $sid
|
|
*
|
|
* @return array List of error messages
|
|
*/
|
|
public function PaketmarkeDrucken($id, $sid)
|
|
```
|
|
|
|
`$sid` enthält einen der Strings welche `Paketmarke` als `$doctyp` übergeben werden.
|
|
|
|
`$id` entspricht der ID des jeweiligen Datensatzes.
|
|
|
|
Genutzt wird diese Methode in `erpAPI::PaketmarkeDrucken()`
|
|
|
|
@file class.erpapi.php:22846 (Stand 06.2019)
|
|
```php
|
|
<?php
|
|
//WAWICORE
|
|
class erpAPI
|
|
{
|
|
// ...
|
|
//@refactor versanddiestleister Modul
|
|
function PaketmarkeDrucken($id, $sid = 'lieferschein')
|
|
{
|
|
// ...
|
|
if($ret = $obj->PaketmarkeDrucken($lieferschein, 'lieferschein'))
|
|
// ...
|
|
}
|
|
// ...
|
|
}
|
|
```
|
|
|
|
### TrackingReplace
|
|
|
|
```php
|
|
/**
|
|
* @param string $tracking
|
|
*
|
|
* @return string
|
|
*/
|
|
public function TrackingReplace($tracking)
|
|
```
|
|
|
|
Genutzt wird diese Methode in `erpAPI::Paketmarke()`
|
|
|
|
@file class.erpapi.php:21703 (Stand 06.2019)
|
|
```php
|
|
<?php
|
|
//WAWICORE
|
|
class erpAPI
|
|
{
|
|
// ...
|
|
//@refactor versanddiestleister Modul
|
|
function Paketmarke($parsetarget,$sid="",$zusatz="",$typ="DHL")
|
|
{
|
|
// ...
|
|
$tracking = $obj->TrackingReplace($tracking);
|
|
// ...
|
|
}
|
|
// ...
|
|
}
|
|
```
|
|
|
|
|
|
## Abstrakte Klasse Versandart
|
|
|
|
Um neue Versandarten schneller und einfacher anzulegen, existiert in der Versandart *ParcelOne* eine abstrakte Klasse, welche die geforderten Methoden mit einer default Implementierung beinhaltet oder diese explizit als abstrakte Methode definiert. Siehe `AbstractVersandartParcelone`. Diese Klasse *muss* nicht verwendet werden, deckt aber bereits einige der Anforderungen ab.
|
|
|
|
Die abstrakte Klasse erbt wie gefordert von der Klasse ``Versanddienstleister``.
|
|
|
|
Um diese Klasse zu verwenden müssen folgende Methoden implementiert werden:
|
|
|
|
- EinstellungenStruktur
|
|
- parseTemplate
|
|
- createPaketmarke
|
|
|
|
Alle anderen gefoderten Methoden stehen mit einer default Implementierung zur Verfügung. Diese können zum Teil überschrieben werden.
|
|
|
|
Weiterhin werden einige nützliche Hilfsmethoden bereitgestellt.
|
|
|
|
### Variablen:
|
|
|
|
Folgende Variablen werden von allen Versandarten benötigt und sind deshalb hier definiert:
|
|
|
|
```php
|
|
public $einstellungen = [];
|
|
public $export_drucker;
|
|
public $paketmarke_drucker;
|
|
```
|
|
|
|
### Konstruktor:
|
|
|
|
Der Konstruktor ist bereits implementiert und lädt die nötigen Einstellungen aus der Datenbank. Er ist als 'final' deklariert, kann folglich nicht überschrieben werden.
|
|
|
|
```php
|
|
/**
|
|
* @param app_t $app
|
|
* @param int $id
|
|
*/
|
|
final public function __construct($app, $id){}
|
|
```
|
|
|
|
### Abstrakte Methoden:
|
|
|
|
Nachfolgende Methoden wurden als abstract deklariert und müssen zwingend implementiert werden:
|
|
|
|
#### EinstellungenStruktur:
|
|
|
|
Erstellt die Eingabenmaske unter `/index.php?module=versandarten&action=create`
|
|
|
|
```php
|
|
/**
|
|
* @return array
|
|
*/
|
|
abstract public function EinstellungenStruktur();
|
|
```
|
|
|
|
#### parseTemplate:
|
|
|
|
Das Template-file ist nicht (zwingend) bekannt. Verschiedene Platzhalter sind abhängig von der verwendeten Versandart. Deshalb ist die Methode ``parseTemplate`` als abstract vorgesehen.
|
|
|
|
```php
|
|
/**
|
|
* @param string $target
|
|
*
|
|
* @return void
|
|
*/
|
|
abstract protected function parseTemplate($target);
|
|
```
|
|
|
|
#### createPaketmarke:
|
|
|
|
Das 'Herzstück' der Paketmarke ist die Methode ``createPaketmarke()`` welche die Methoden ``Paketmarke()`` und ``PaketmarkeDrucken()`` eint.
|
|
|
|
Diese Methode muss sich nicht mehr darum kümmern, von welchem Endpunkt sie aufgerufen wurde und ob die Variable ``$adressdaten`` null ist oder tatsächlich Daten enthält.
|
|
|
|
Stattdessen wird das Array ``$adressdaten`` von den aufrufenden Methoden gefüllt. Zudem wird das Array ``$packageData`` übergeben, welches Daten zum versendeten Paket enthält.
|
|
|
|
Somit muss nur noch diese Methode implementiert werden. ``Paketmarke()`` und ``PaketmarkeDrucken()`` können in der default Implementierung genutzt werden.
|
|
|
|
```php
|
|
/**
|
|
* @param string $doctyp
|
|
* @param string $id
|
|
* @param string $target
|
|
* @param bool $error
|
|
* @param array $adressdaten
|
|
* @param array $packageData
|
|
*
|
|
* @return array list of error messages
|
|
*/
|
|
abstract protected function createPaketmarke($doctyp, $id, $target, $error, $adressdaten, $packageData);
|
|
```
|
|
|
|
### Default Implementierungen:
|
|
|
|
Folgende Methoden existieren mit einer default implementierung und können bei bedarf überschrieben werden:
|
|
|
|
#### TrackingReplace:
|
|
|
|
``TrackingReplace()`` ändert momentan die Trackingnummer nicht.
|
|
|
|
```php
|
|
/**
|
|
* @param string $tracking
|
|
*
|
|
* @return string
|
|
*/
|
|
public function TrackingReplace($tracking)
|
|
{
|
|
return $tracking;
|
|
}
|
|
```
|
|
|
|
#### GetBezeichnung:
|
|
|
|
Erstellt die Bezeichnung anhand des Klassennamens der aktuellen Versandart. Z.B. wird '*Versandart_parcelone*' zu '*Parcelone*' konvertiert.
|
|
|
|
```php
|
|
/**
|
|
* @return string
|
|
*/
|
|
public function GetBezeichnung()
|
|
```
|
|
|
|
#### validateSettings:
|
|
|
|
Die Methode ``validateSettings()`` prüft die getätigten Einstellungen anhand von ``EinstellungenStruktur()`` auf Plausibilität.
|
|
|
|
Es wird geprüft, ob alle nötigen Felder ausgefüllt wurden. Bei Drop-Down Auswahlfeldern wird zudem geprüft, ob die Auswahl tatsächlich erlaubt ist.
|
|
|
|
```php
|
|
/**
|
|
* @throws RuntimeException im Fehlerfall
|
|
* @return void
|
|
*/
|
|
protected function validateSettings()
|
|
```
|
|
|
|
#### getUserName:
|
|
|
|
Enthält eine Hilfsmethode um den Nutzernamen abzufragen. Der String wird mittels ``real_escape_string()`` behandelt.
|
|
|
|
```php
|
|
/**
|
|
* @return string
|
|
*/
|
|
protected function getUserName()
|
|
```
|
|
|
|
#### Paketmarke:
|
|
|
|
Hier ist eine als `final` deklarierte Implementation der Methode `Paketmarke()`. Sie Prüft die Variablen `$doctyp` und `$id` und lädt die entsprechenden Daten aus der DB. Über `validateSettings()` werden die Einstellungen geprüft.
|
|
|
|
Die Addressdaten und Paketdaten werden aus dem Parameter `$adressdaten` oder aus den `$_POST` Feldern ausgelesen. Die benötigten Daten stehen nun in den Variablen `$address` und `$packageData` zur Verfügung, unabhängig von ihrer Quelle.
|
|
|
|
Mit diesen Daten wird anschließend die abstrakte Methode `createPaketmarke()` aufgerufen.
|
|
|
|
```php
|
|
/**
|
|
* @param string $doctyp 'lieferschein' / 'versand' / 'retoure'
|
|
* @param string|int $id '1'
|
|
* @param string $target '#TAB1'
|
|
* @param bool $error
|
|
* @param null|array $adressdaten
|
|
*
|
|
* @return array
|
|
*/
|
|
final public function Paketmarke($doctyp, $id, $target = '', $error = false, &$adressdaten = null)
|
|
```
|
|
|
|
#### PaketmarkeDrucken:
|
|
|
|
Über die default implementierung von `PaketmarkeDrucken()` wird ebenso die abstrakte Methode `createPaketmarke()` aufgerufen.
|
|
|
|
```php
|
|
/**
|
|
* @param int|string $id
|
|
* @param $sid
|
|
*
|
|
* @return array
|
|
*/
|
|
public function PaketmarkeDrucken($id, $sid)
|
|
```
|
|
|
|
#### getDocumentByID:
|
|
|
|
Über die Methode `getDocumentByID()` werden die Daten geladen, welche über einen Dokumenttyp und dessen ID identifiert sind.
|
|
|
|
Der Dokumenttyp sollte einen der folgenden Werte haben:
|
|
- 'lieferschein'
|
|
- 'versand'
|
|
- 'retoure'
|
|
- 'auftrag'
|
|
|
|
Dieser Wert wird nicht geprüft. Damit ist es möglich, auch andere Dokumente zu laden.
|
|
|
|
```php
|
|
/**
|
|
* @param string $documentTyp on of 'lieferschein', 'versand' or 'retoure'
|
|
* @param int $id
|
|
*
|
|
* @throws RuntimeException
|
|
*
|
|
* @return array
|
|
*/
|
|
protected function getDocumentByID($documentTyp, $id)
|
|
```
|
|
|
|
#### getPrinter
|
|
|
|
Durch die Methode `getPrinter()` wird die ID des Standard-Paketmarkendruckers
|
|
|
|
zurückgegeben, falls dies über die Parameter `drucken` bzw `tracking_again` gefordert ist. Ansonsten wird der Wert `0` zurückgegeben.
|
|
```php
|
|
/**
|
|
* @return int
|
|
*/
|
|
protected function getPrinter()
|
|
```
|