J4.x:Cloud File Systems for Media Manager/nl

GSoC 2017
Cloud File Systems for Media Manager
Documentation

Joomla! 

4.x

Introduction

Joomla! 4.x is shipped with cloud file systems for the Media Manager by default. With the previous API, creating custom file systems was a difficult task. Thanks to the new API, it's now easy to create a custom file system. If you want to use a Cloud Service with the new Media Manager, it is advised to use OAuth2.0.

This document will guide you through important steps to create your own File System Plugin to extend the Media Manager. Before proceeding, please make sure you have the basic knowledge on how to develop a plugin for Joomla. This tutorial should help.

Create your Filesystem plugin

Configuration

First of all, we need to create a filesystem plugin to extend the Media Manager. This plugin should contain some important attributes so that it can work with the Media Manager.

Make sure your plugin contains group="filesystem". So in your [plugin-name].xml, you should have:

<?xml version="1.0" encoding="utf-8"?>
<extension version="4.0" type="plugin" group="filesystem" method="upgrade">
	<name>plg_filesystem_myplugin</name>
	<author>Joomla! Project</author>
	<creationDate>April 2017</creationDate>
	<copyright>Copyright (C) 2005 - 2017 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>__DEPLOY_VERSION__</version>
	<description>Description</description>
	<files>
		<filename plugin="myplugin">myplugin.php</filename>
		<folder>SomeFolder</folder>
	</files>
	
	<config>
		<fields name="params">
			<fieldset name="basic">
				<field
					name="display_name"
					type="text"
					label="YOUR_LABEL"
					description="YOUR_DESCRIPTION"
					default="DEFAULT_VALUE"
				/>
			</fieldset>
		</fields>
	</config>
</extension>

The display_name parameter helps the Media Manager to display the name of your File System as a root node in the File Browser. Any adapter belonging to your File System will be displayed as children under the root.

Include any required parameters you may need such as App Secret with suitable Form Fields.

Plugin Events

• onFileSystemGetAdapters()
• onFileSystemOAuthCallback(\Joomla\Component\Media\Administrator\Event\OAuthCallbackEvent $event)

onFileSystemGetAdapters()

Any De plug-n van het bestandssysteem moet de gebeurtenis bevatten met de naamonFileSystemGetAdapters() voor functionaliteit. Deze gebeurtenis moet een 'array retouneren van Joomla\Component\Media\Administrator\Adapter\AdapterInterface als het is aangeroepen. Het event wordt georganiseerd wanneer u Media Manager opent. Elke AdapterInterface zal worden gemount aan de basis van je bestandssysteem.

onFileSystemOAuthCallback()

Deze gebeurtenis wordt geactiveerd wanneer u Media Manager gebruikt OAuthCallbackHandler voor OAuth2.0 Autorisatie- en authenticatieproces hieronder beschreven in het document. De gebeurtenis wordt alleen geactiveerd op de gevraagde plug-in. Het is dus niet nodig om te controleren op $context in een typisch scenario.

Een voorbeeld van het gebruik van deze gebeurtenis ziet eruit als:

public function onFileSystemOAuthCallback(\Joomla\Component\Media\Administrator\Event\OAuthCallbackEvent $event)
{
	// Your context
	$context = $event->getContext();

	// Get the input
	$data = $event->getInput();

	// Your code goes here
	
	// Set result to be returned
	$result = [
		"action" => "control-panel"
	];
	
	// Pass back the result to event
	$event->setArgument('result', $result);
}

OAuthCallbackEvent bevat de invoer doorgestuurd naar de Media Manager OAuthCallback URI. $event->getInput() geeft een invoerobject terug.

$result definieert hoe Joomla zich gedraagt ​​na een omleiding naar de callback. Er zijn verschillende mogelijke oplossingen beschikbaar:

• action
  • sluit: Sluit een scherm dat is geopend door Javascript using window.open()
  • doorverwijzing: Doorverwijzing naar de pagina redirect_uri
  • controle-paneel: Verwijs door naar het controle paneel
  • media beheer: Verwijs door naar Media Beheer
• redirect_uri
  • Gebruikt met redirect actie (verplicht)
• message
  • Bericht moet getoond worden na een actie
• message_type
  • waarschuwing
  • let op
  • fout
  • bericht(of zet leeg)

Nadat u alles hebt ingesteld, stelt u de$result argument van de $event terug te koppelen.

Een voorbeeld om een ​​bericht aan de gebruiker weer te geven zou zijn:

$result = [
	"action" => "media-manager",
	"message" => "Some message",
	"message-type" => "notice"
];

Hiermee wordt u omgeleid naar Media Manager en wordt een melding weergegeven met de tekst message.

Deze methode zal meestal worden gebruikt om autorisatiecodes te verkrijgen voor het 'OAuth2.0 proces. In het geval van een error, Joomla! zal terugvallen op het bedieningspaneel en zal een foutmelding weergeven.

Authenticatie en authorisatie

Joomla! 4.x adviseerd je gebruik OAuth2.0 voor dit proces. Het is gebruikelijk OAuth2.0 heeft eenredirect url nodig om authenticatiegegevens door te geven aan de applicatie. Dit wordt meestal gedaan door een callback handler. Voor uw plugin hoeft u het wiel niet opnieuw uit te vinden, u kunt de Callback Handler of Media Manager gebruiken om de taak uit te voeren.

Het enige wat u moet doen is stel de Redirect URI' in om te volgen in OAuth2.0 Verstrek en implementeer deonFileSystemOAuthCallback(\Joomla\Component\Media\Administrator\Event\OAuthCallbackEvent $event) in je plugin.

[site-name]/administrator/index.php?option=com_media&task=plugin.oauthcallback&plugin=[your-plugin-name]

In dit voorbeeld: [site-name]/administrator/index.php?option=com_media&task=plugin.oauthcallback&plugin=myplugin

Wanneer u nu een omleiding van uw provider uitvoert zodra deze de opgegeven URL bereikt, de Controller voor de Media Manager zorgt ervoor dat uw plug-in wordt geïmplementeerd onFileSystemOAuthCallback(\Joomla\Component\Media\Administrator\Event\OAuthCallbackEvent $event) voordat u er gegevens aan doorgeeft. Als dit niet het geval is, wordt u doorgestuurd naar het Configuratiescherm met een foutmelding.

Als u alle ingevoerde gegevens hebt geïmplementeerd, wordt de cloudprovider opgenomen in de$event. You can access them using $event->getInput() en behandel het zoals gewoonlijkinput inJoomla!.

Nadat je deinputhebt ontvangen, kan je het gebruiken om de details van uw cloudservice ophalen, zoals Access Token, Refresh Token enz.

Als u meerdere accounts wilt onderscheiden, kunt u daarvoor Session gebruiken.

Note: Het wordt aangeraden om te controleren tegen CSRF token voordat je doorgaat met je request. De meeste cloudproviders ondersteunen de parameter status die kan worden gebruikt om de taak te vervullen.

Gemeenschappelijke valkuilen

Het is verplicht om urlencode() je redirect uri wanneer je het naar de cloudprovider verzendt. Gebruik het om wangedrag van je cloud te voorkomen.

Bestand Serveren vanaf uw adapter

Om uw mediabestanden van Media Manager aan te biede Joomla! Site Joomla\Component\Media\Administrator\Adapter\AdapterInterface helpt je. Deze interface bevat een speciale methode genaamdgetUrl($path).

$path : Pad is relatief ten opzichte van je root

De bedoeling van de methode is om een ​​ 'Public Absolute URL' te geven voor het bestand dat u in de site wilt invoegen. Veronderstel bijvoorbeeld dat uw bestandspad /path/to/me.png is in de cloud-server. Nu kan een openbare URL zoiets zijn als mycloud.com/share/u/myusername/path/to/me.png . Hoe het wordt geserveerd, is helemaal aan jou. Wanneer een gebruiker een door media gegenereerde URL wil invoegen, wordt deze methode gebruikt.

Meer details over Adapter Interface kunnen worden gevonden inadministrator/componenents/com_media/Adapter/AdapterInterface.php