View source for Adding an API to a Joomla Component/de

<noinclude><languages /></noinclude>
<noinclude>{{Joomla version|version=4.0}}</noinclude>
Diese Seite soll dokumentieren, wie sich die in {{jver|4.0}} 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'''''

[[File:Struct1.png|500px|thumb|center|File system structure]]

2. Anlegen der Klasse: '''''WeblinksController'''''
<source lang="php">
use Joomla\CMS\MVC\Controller\ApiController;

class WeblinksController extends ApiController 
{
    protected $contentType = 'weblinks';

    protected $default_view = 'weblinks';
}
</source>

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'''''

<source lang="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',
    ];
}
</source>

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'''''

[[File:Struct2.png.png|500px|thumb|center|File system structure]]

2. In der Datei '''''weblinks.php''''', erstellen der Klasse: '''''PlgWebservicesWeblinks'''''
<source lang="php">
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']);
    }
}
</source>

In der Methode '''''onBeforeApiRoute''''', alle Routen registrieren, die wir für den Webservice benötigen.

3. Erstellen von: '''''weblinks.xml'''''
<source lang="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>
</source>

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:
<source lang="php">
; 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."
</source>

== Dritter Schritt  ==
1. In der Datei '''''src/administrator/components/com_weblinks/weblinks.xml''''' eine Beschreibung für die Webdienst-API-Dateien hinzufügen.
<source lang="xml">
<api>
    <files folder="api/components/com_weblinks">
       ##API_COMPONENT_FILES##
    </files>
</api>
</source>

2. In der Datei  '''''src/administrator/manifests/packages/pkg_weblinks.xml''''' eine Beschreibung für das Webservice-Plugin hinzufügen.
<source lang="xml">
<files>
    ...
    <file type="plugin" id="weblinks" group="webservices">plg_webservices_weblinks.zip</file>
</files>
</source>

== Categories ==
1. Add categories support for weblinks webservice. Edit the file '''''src/plugins/webservices/weblinks/weblinks.php'''''
<source lang="php">
class PlgWebservicesWeblinks extends CMSPlugin
{
    public function onBeforeApiRoute(&$router)
    {
        ...
        $router->createCRUDRoutes(
            'v1/weblinks/categories',
            'categories',
            ['component' => 'com_categories', 'extension' => 'com_weblinks']
        );
    }
}
</source>

Die Kategorie-Unterstützung für den Weblinks-Webservice hinzufügen. Bearbeiten der Datei: => 'com_weblinks'

== Felder ==
1. Hinzufügen von Feldern und Feldgruppen für den Webservice „Weblinks“. Bearbeiten der Datei '''''src/plugins/webservices/weblinks/weblinks.php'''''
<source lang="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']
        );
    }
}
</source>

2. Überschreiben der Funktion '''''save''''' in '''''WeblinksController'''''
<source lang="php">
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);
    }

    ...
}
</source>

3. Überschreiben der Funktionen '''''displayList, displayItem, prepareItem''''' in '''''Weblinks\JsonApiView'''''

<source lang="php">
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);
    }

    ...
}
</source>

In der Funktion ''prepareItem'' muss geachtet werden auf: <source lang="php">$field->apivalue</source> 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: 
<source lang="php">$field->rawvalue</source>

== 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 
<source lang="javascript">
{
    "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"
}
</source>

==== Update Weblink ====
curl -X PUT -H "Content-Type: application/json" /api/index.php/v1/weblinks/{weblink_id} -d 
<source lang="javascript">
{
    "catid": "8",
    "description": "<p>some new text</p>",
    "language": "*",
    "title": "new title",
    "url": "http://newsomelink.com/"
}
</source>

=== Categories ===
Route Weblinks Categories is: "v1/weblinks/categories"

Working with it is similar to [[J4.x:Joomla_Core_APIs#Categories|Banners Categories]].

=== Fields ===

Route Fields Weblinks is: "v1/fields/weblinks"

Working with it is similar to [[J4.x:Joomla_Core_APIs#Fields_Contact|Fields Contact]].

=== Groups Fields ===

Route Groups Fields Weblinks is: "v1/fields/groups/weblinks"

Working with it is similar to [[J4.x:Joomla_Core_APIs#Groups_Fields_Contact|Groups Fields Contact]].


<noinclude>
[[Category:Development{{#translation:}}]]
[[Category:Component_Development{{#translation:}}]]
[[Category:Joomla!_4.x{{#translation:}}]]
[[Category:Joomla! 4.x Web Services{{#translation:}}]]
</noinclude>