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 Filesystem plugin should contain an event called onFileSystemGetAdapters() for functionality. This event should return an array of Joomla\Component\Media\Administrator\Adapter\AdapterInterface when it is called. The event is raised when you open the Media Manager. Each AdapterInterface will be mounted under the root node of your file system.

onFileSystemOAuthCallback()

This event is fired when you used Media Manager's OAuthCallbackHandler for OAuth2.0 Authorization and Authentication process described below in the document. The event is only fired on the requested plugin. So there's no need to check for $context in a typical scenario.

An example of use of the event looks like:

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 contains the input forwarded to the Media Manager OAuthCallback URI. $event->getInput() returns an Input Object.

$result defines how Joomla behaves after a redirect to the callback. There are several possible solutions available:

• action
  • close: Closes a window which is opened by a JavaScript using window.open()
  • redirect: Redirects to the page specified by the redirect_uri
  • control-panel: Redirect to the control panel
  • media-manager: Redirect to Media Manager
• redirect_uri
  • Used with redirect action (required)
• message
  • Message needs to be displayed after an action
• message_type
  • warning
  • notice
  • error
  • message(or set empty)

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