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

GSoC 2017
Systèmes de fichiers en cloud pour Gestionnaire de médias
Documentation

Joomla! 

4.x

Introduction

Joomla! 4.x est livré avec des systèmes de fichiers cloud pour le Gestionnaire de Médias par défaut. Avec l'API précédente, créer des systèmes de fichiers personnalisés était une tâche difficile. Grâce à la nouvelle API, il est maintenant facile de créer un système de fichiers personnalisé. Si vous souhaitez utiliser un service cloud avec le nouveau Gestionnaire de Médias, il est conseillé d'utiliser OAuth2.0.

Ce document vous guidera à travers les étapes importantes pour créer votre propre Plugin de Système de Fichiers afin d'étendre le Gestionnaire de Médias. Avant de continuer, assurez-vous d'avoir les connaissances de base sur le développement d'un plugin pour Joomla. Ce tutoriel devrait vous aider.

Créez votre plugin de système de fichiers

Configuration

Tout d'abord, nous devons créer un plugin de système de fichiers pour étendre le Gestionnaire de Médias. Ce plugin doit contenir certaines attributs importants pour qu'il puisse fonctionner avec le Gestionnaire de Médias.

Assurez-vous que votre plugin contient group="filesystem". Ainsi, dans votre fichier [nom-du-plugin].xml, vous devriez avoir :

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

Le paramètre display_name aide le Gestionnaire de Médias à afficher le nom de votre Système de Fichiers en tant que nœud racine dans le Navigateur de Fichiers. Tous les adaptateurs appartenant à votre Système de Fichiers seront affichés en tant qu'enfants sous la racine.

Incluez tous les paramètres nécessaires que vous pourriez avoir besoin, tels que App Secret, avec les champs de formulaire appropriés.

Plugins Evénements

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

onFileSystemGetAdapters()

Tout plugin de système de fichiers doit contenir un événement appelé onFileSystemGetAdapters() pour fonctionner. Cet événement devrait retourner un tableau de Joomla\Component\Media\Administrator\Adapter\AdapterInterface lorsqu'il est appelé. L'événement est déclenché lorsque vous ouvrez le Gestionnaire de Médias. Chaque AdapterInterface sera monté sous le nœud racine de votre système de fichiers.

onFileSystemOAuthCallback()

Cet événement est déclenché lorsque vous utilisez le OAuthCallbackHandler du Gestionnaire de Médias pour le processus d'autorisation et d'authentification OAuth2.0 décrit ci-dessous dans le document. L'événement est uniquement déclenché sur le plugin demandé. Il n'est donc pas nécessaire de vérifier $context dans un scénario typique.

Un exemple d'utilisation de l'événement ressemble à ceci :

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 contient l'entrée transmise à l'URI de rappel OAuthCallback du Gestionnaire de Médias. $event->getInput() retourne un objet Input.

$result définit comment Joomla se comporte après une redirection vers le rappel. Il existe plusieurs solutions possibles disponibles :

• 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)

After setting everything, set the $result argument of the $event to pass it back to the caller.

An example to display a message to user would be:

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

This will redirect to the Media Manager and raise a notice with the text in message.

This method can be typically used to obtain authorization codes for the OAuth2.0 process. In case of any error, Joomla! will fallback to the control panel adn will display an error message.

Authentication and Authorization

Joomla! 4.x advices you to use OAuth2.0 for this process. It is a common scenario that OAuth2.0 requires a redirect url to pass authentication data to the Application. This is typically done by a callback handler. For your plugin, no need to reinvent the wheel, you can use the Callback Handler of Media Manager for fulfilling the task.

All you have to do is to set the Redirect URI to following in your OAuth2.0 Provide and Implement the onFileSystemOAuthCallback(\Joomla\Component\Media\Administrator\Event\OAuthCallbackEvent $event) in your plugin.

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

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

Now when you do a redirect from your provider once it reaches the URL provided, the Controller for Media Manager will ensure that your plugin implements onFileSystemOAuthCallback(\Joomla\Component\Media\Administrator\Event\OAuthCallbackEvent $event) before passing any data to it. If not, you will be redirected to the Control Panel with an error message.

If you have implemented all the inputs that are passed with, the Cloud Provider will be included in the $event. You can access them using $event->getInput() and treat it as an usual input to Joomla.

After you received the input, you can use it to obtain the details of your cloud service such as Access Token, Refresh Token etc.

If you want to distinguish multiple accounts, you can use Session for that.

Note: It is advised to check against CSRF token before you proceed your request. Most cloud providers support state parameter that can be used to fulfill the task.

Common Pitfalls

It is required to urlencode() your redirect uri when you're sending it to the cloud provider. Please use it to avoid misbehaviours of your cloud.

File Serve from your Adapter

To serve your media files from the Media Manager to Joomla! Site Joomla\Component\Media\Administrator\Adapter\AdapterInterface helps you. This Interface contains a special method called getUrl($path).

$path : Path is relative to your root

The intention of the method is to provide a Public Absolute URL for the file you requested to insert in the site. For example assume your file path is /path/to/me.png in the cloud server. Now a public URL might be something like mycloud.com/share/u/myusername/path/to/me.png. How it is being served, is completely up to you. When an user wants to insert a media generated URL, this method will be used.

More details about Adapter Interface can be found in administrator/componenents/com_media/Adapter/AdapterInterface.php