Eine API zu einer Joomla-Komponente hinzufügen
From Joomla! Documentation
Diese Seite soll dokumentieren, wie sich die in 
eingeführte Webservices-Schicht in bestehende Joomla-Komponenten integrieren können. Dies setzt voraus, dass die Standard-Joomla-MVC-Schicht verwendet wird.
Ein Beispiel der Webservices-Integration zur Erweiterung von Weblinks
Repository der Erweiterung: https://github.com/joomla-extensions/weblinks
Pull request: https://github.com/joomla-extensions/weblinks/pull/407
Erster Schritt
1. Verzeichnis erstellen: src/api
2. Anlegen der Klasse: WeblinksController
use Joomla\CMS\MVC\Controller\ApiController;
class WeblinksController extends ApiController
{
protected $contentType = 'weblinks';
protected $default_view = 'weblinks';
}
Die folgenden Felder übersteuern (override):
$contentType - wird als Standard für $modelName verwendet, wenn die Antwort als Typ-Objekt ausgegeben wird $default_view - wird als Standard für $viewName verwendet
3. Anlegen der Klasse: JsonApiView.php
use Joomla\CMS\MVC\View\JsonApiView as BaseApiView;
class JsonApiView extends BaseApiView
{
protected $fieldsToRenderItem = [
'id',
'catid',
'title',
'alias',
'url',
'xreference',
'tags',
];
protected $fieldsToRenderList = [
'id',
'title',
'alias',
];
}
Die folgenden Felder übersteuern (override):
$fieldsToRenderItem - Array aus Feldern zur Anzeige eines einzelnen Objekts $fieldsToRenderList - Array aus Feldern um Objekte aufzulisten
Zweiter Schritt
1. Verzeichnis erstellen: plugins/webservices/weblinks
2. In der Datei weblinks.php, erstellen der Klasse: PlgWebservicesWeblinks
use Joomla\CMS\Plugin\CMSPlugin;
use Joomla\CMS\Router\ApiRouter;
class PlgWebservicesWeblinks extends CMSPlugin
{
public function onBeforeApiRoute(&$router)
{
$router->createCRUDRoutes('v1/weblinks', 'weblinks', ['component' => 'com_weblinks']);
}
}
In der Methode onBeforeApiRoute, alle Routen registrieren, die wir für den Webservice benötigen.
3. Erstellen von: weblinks.xml
<?xml version="1.0" encoding="utf-8"?>
<extension version="3.1" type="plugin" group="webservices" method="upgrade">
<name>plg_webservices_weblinks</name>
<author>Joomla! Project</author>
<creationDate>August 2017</creationDate>
<copyright>(C) 2005 - 2019 Open Source Matters. All rights reserved.</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<authorEmail>admin@joomla.org</authorEmail>
<authorUrl>www.joomla.org</authorUrl>
<version>4.0.0</version>
<description>PLG_WEBSERVICES_WEBLINKS_XML_DESCRIPTION</description>
<files>
##FILES##
</files>
<languages folder="administrator/language">
##LANGUAGE_FILES##
</languages>
</extension>
4. Erstellen der Dateien en-GB/en-GB.plg_webservices_weblinks.ini, en-GB/en-GB.plg_webservices_weblinks.sys.ini mit dem folgenden Inhalt:
; Joomla! Project
; Copyright (C) 2005 - 2019 Open Source Matters. All rights reserved.
; License GNU General Public License version 2 or later; see LICENSE.txt, see LICENSE.php
; Note : All ini files need to be saved as UTF-8
PLG_WEBSERVICES_WEBLINKS="Web Services - Weblinks"
PLG_WEBSERVICES_WEBLINKS_XML_DESCRIPTION="Used to add weblinks routes to the Web Services API for your website."
Dritter Schritt
1. In der Datei src/administrator/components/com_weblinks/weblinks.xml eine Beschreibung für die Webdienst-API-Dateien hinzufügen.
<api>
<files folder="api/components/com_weblinks">
##API_COMPONENT_FILES##
</files>
</api>
2. In der Datei src/administrator/manifests/packages/pkg_weblinks.xml eine Beschreibung für das Webservice-Plugin hinzufügen.
<files>
...
<file type="plugin" id="weblinks" group="webservices">plg_webservices_weblinks.zip</file>
</files>
Kategorien
1. Hinzufügen der Kategorie-Unterstützung für den Weblinks-Webservice. Bearbeiten der Datei src/plugins/webservices/weblinks/weblinks.php.
class PlgWebservicesWeblinks extends CMSPlugin
{
public function onBeforeApiRoute(&$router)
{
...
$router->createCRUDRoutes(
'v1/weblinks/categories',
'categories',
['component' => 'com_categories', 'extension' => 'com_weblinks']
);
}
}
Wir verwenden die vorgefertigte Komponente com_categories und müssen nur noch den Parameter 'extension' => 'com_weblinks'
Felder
1. Hinzufügen von Feldern und Feldgruppen für den Webservice „Weblinks“. Bearbeiten der Datei src/plugins/webservices/weblinks/weblinks.php
class PlgWebservicesWeblinks extends CMSPlugin
{
public function onBeforeApiRoute(&$router)
{
...
$router->createCRUDRoutes(
'v1/fields/weblinks',
'fields',
['component' => 'com_fields', 'context' => 'com_weblinks.weblink']
);
$router->createCRUDRoutes(
'v1/fields/groups/weblinks',
'groups',
['component' => 'com_fields', 'context' => 'com_weblinks.weblink']
);
}
}
2. Überschreiben der Funktion save in WeblinksController
class WeblinksController extends ApiController
{
...
protected function save($recordKey = null)
{
$data = (array) json_decode($this->input->json->getRaw(), true);
foreach (FieldsHelper::getFields('com_weblinks.weblink') as $field)
{
if (isset($data[$field->name]))
{
!isset($data['com_fields']) && $data['com_fields'] = [];
$data['com_fields'][$field->name] = $data[$field->name];
unset($data[$field->name]);
}
}
$this->input->set('data', $data);
return parent::save($recordKey);
}
...
}
3. Überschreiben der Funktionen displayList, displayItem, prepareItem in Weblinks\JsonApiView
class JsonApiView extends BaseApiView
{
...
public function displayList(array $items = null)
{
foreach (FieldsHelper::getFields('com_weblinks.weblink') as $field)
{
$this->fieldsToRenderList[] = $field->name;
}
return parent::displayList();
}
public function displayItem($item = null)
{
foreach (FieldsHelper::getFields('com_weblinks.weblink') as $field)
{
$this->fieldsToRenderItem[] = $field->name;
}
return parent::displayItem();
}
protected function prepareItem($item)
{
foreach (FieldsHelper::getFields('com_weblinks.weblink', $item, true) as $field)
{
$item->{$field->name} = isset($field->apivalue) ? $field->apivalue : $field->rawvalue;
}
return parent::prepareItem($item);
}
...
}
In der Funktion prepareItem muss geachtet werden auf:
$field->apivalue
Falls der Typ des Feldes komplex ist, wird hoffentlich ein Wert für die Ausgabe in der Web Services API-Komponente zurückgegeben, andernfalls greifen wir zurück auf:
$field->rawvalue
Beispiel für eine integrierte Arbeit
Hinweis: Nicht vergessen, das Weblinks Webservice Plugin zu aktivieren!
Weblinks
Liste von Weblinks erhalten
curl -X GET /api/index.php/v1/weblinks
Einzelnen Weblink erhalten
curl -X GET /api/index.php/v1/weblinks/{weblink_id}
Weblink löschen
curl -X DELETE /api/index.php/v1/weblinks/{weblink_id}
Weblink erstellen
curl -X POST -H "Content-Type: application/json" /api/index.php/v1/weblinks -d
{
"access": "1",
"alias": "",
"catid": "8",
"description": "<p>text</p>",
"images": {
"float_first": "",
"float_second": "",
"image_first": "",
"image_first_alt": "",
"image_first_caption": "",
"image_second": "",
"image_second_alt": "",
"image_second_caption": ""
},
"language": "*",
"metadata": {
"rights": "",
"robots": ""
},
"metadesc": "",
"metakey": "",
"modified": "",
"params": {
"count_clicks": "",
"height": "",
"target": "",
"width": ""
},
"title": "weblink title",
"url": "http://somelink.com/",
"xreference": "xreference"
}
Weblink aktualisieren
curl -X PUT -H "Content-Type: application/json" /api/index.php/v1/weblinks/{weblink_id} -d
{
"catid": "8",
"description": "<p>some new text</p>",
"language": "*",
"title": "new title",
"url": "http://newsomelink.com/"
}
Kategorien
Die Route zu den Weblinks-Kategorien ist: "v1/weblinks/categories"
Die Arbeitsweise ist vergleichbar mit: Banner-Kategorien.
Felder
Die Route zu den Weblinks-Feldern ist: "v1/fields/weblinks"
Die Arbeitsweise ist vergleichbar mit: Kontakt-Felder.
Gruppenfelder
Die Route zu den Weblinks-Gruppenfeldern ist: "v1/fields/groups/weblinks"
Die Arbeitsweise ist vergleichbar mit: Kontakt-Feldgruppen