J4.x

Adding an API to a Joomla Component/de: Difference between revisions

From Joomla! Documentation

← Older editNewer edit →
Created page with "==== Weblink löschen ===="
Created page with "==== Weblink erstellen ===="
Line 265: Line 265:
curl -X DELETE /api/index.php/v1/weblinks/{weblink_id}
curl -X DELETE /api/index.php/v1/weblinks/{weblink_id}


==== Create Weblink ====
==== Weblink erstellen ====
curl -X POST -H "Content-Type: application/json" /api/index.php/v1/weblinks -d  
curl -X POST -H "Content-Type: application/json" /api/index.php/v1/weblinks -d  
<source lang="javascript">
<source lang="javascript">

Revision as of 15:05, 28 August 2021

Other languages:
Joomla! 
4.0

Diese Seite soll dokumentieren, wie sich die in Joomla 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 system structure

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

File system structure

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>

Categories

1. Add categories support for weblinks webservice. Edit the file 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']
        );
    }
}

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 

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"
}

Update Weblink

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/"
}

Categories

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

Working with it is similar to Banners Categories.

Fields

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

Working with it is similar to Fields Contact.

Groups Fields

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

Working with it is similar to Groups Fields Contact.

Retrieved from "https://docs.sandbox.joomla.org/index.php?title=J4.x:Adding_an_API_to_a_Joomla_Component/de&oldid=802068"