[TASK] Update the Extension manual

Documentation/Configuration/Index.rst

@@ -1,79 +1,84 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
-
-.. include:: ../Includes.txt
+.. include:: ../Includes.txt
 
 
 .. _configuration:
 
+=============
 Configuration
 =============
 
-.. _configuration-rendering:
-
-Rendering
----------
-
-The rendering mechanism of this extension is very flexible since all the rendering is done with TypoScript.
-Have a look at ``Configuration/TypoScript/setup.txt`` and it will probably remind you of the setup of
-``css_styled_content``.
-
-.. _configuration-rendering-accessing-data:
+.. _configuration-manage-providers:
 
-Accessing data
-~~~~~~~~~~~~~~
+Manage providers
+================
 
-But there is something special in the TypoScript configuration because we somehow need to access the
-data of the the provider, the request and the response. This is why there is a new ``getText`` type available
-called ``registerobj``. With this type you are able to access register data like you can do with the register type.
+Providers are managed via TypoScript in :typoscript:`plugin.tx_mediaoembed.settings.providers`.
 
-The new thing about ``registerobj`` is, that you can access object getters and array data. To do that simply
-use the pipe character (|) like you know it from the GP type for example.
+There are two ways of configuring matching URLs of an provider: regular expressions or simple wildcard based schmemes.
 
-All relevant data for the oEmbed rendering is stored in a single register called tx_mediaoembed which is an
-object of the type ``Sto\Mediaoembed\Content\RegisterData`` array that contains 4 child objects:
+Regular Expressions
+-------------------
 
-::
+To make the handling of URLs simpler we use # as the regex delimer.
 
-    Sto\Mediaoembed\Content\Configuration
-    Sto\Mediaoembed\Request\Provider
-    Sto\Mediaoembed\Request\HttpRequest
-    Sto\Mediaoembed\Response\GenericResponse
+This is an example configuration using Regular Expressions:
 
-With the new ``getText`` type you can access all public available getter Methods of these object.
-
-For a complete documentation of all available methods please have a look in the code or use PHPDoc
-to generate API documentation. In the future, the most important methods will also be documented here.
+.. code-block:: typoscript
 
-If a method returns an array you can traverse the array by using the pipe character.
+    plugin.tx_mediaoembed.settings.providers {
+        some_provider {
+            endpoint = https://some-provider.tld/oembed/endpoint
+            urlRegexes {
+                10 = #https?://([a-z0-9-]+\.)?myprovider\.(org|de|dk)/embedvideo/.*#i
+                20 = #https?://([a-z0-9-]+\.)?myprovider\.(org|de|dk)/embedimage/.*#i
+            }
+        }
+    }
+
+Wildcards
+---------
 
-Example
-```````
+A simpler approach is the usage of wildcards. In that case the config option is called urlSchemes
+and not urlRegexes:
 
 .. code-block:: typoscript
 
-    video = TEXT
-    video.data = registerobj : tx_mediaoembed|response|html
-
-The above TypoScript snippet will call these PHP methods to retrieve the data:
+    plugin.tx_mediaoembed.settings.providers {
+        some_provider {
+            endpoint = https://some-provider.tld/oembed/endpoint
+            urlSchemes {
+                10 = https://*.myprovider.org/embedvideo/*
+                20 = https://*.myprovider.org/embedimage/*
+            }
+        }
+    }
 
-.. code-block:: php
+It provides less flexibility than regex but it is easier to handle.
 
-    Sto\Mediaoembed\Content\RegisterData->getResponse()->getHtml()
 
+.. _configuration-rendering:
 
-.. _configuration-function-reference:
-
-Function reference
-------------------
+Rendering
+=========
 
-TODO: Document the most important getter methods.
+The Extension uses the default Extbase template mechanisms for rendering.
 
-.. _configuration-extending-it:
+This means you can add your own template and partials paths to the configuration to overwrite
+the templates that come with this Extension:
 
-Extending it
-------------
+.. code-block:: typoscript
 
-TODO: Document how this extension can be extended.
+    plugin.tx_mediaoembed {
+        view {
+            templateRootPaths {
+                0 = EXT:mediaoembed/Resources/Private/Templates/
+                1 = EXT:mysitepackage/Resources/Private/Templates/
+            }
+            partialRootPaths {
+                0 = EXT:mediaoembed/Resources/Private/Partials/
+                1 = EXT:mysitepackage/Resources/Private/Partials/
+            }
+        }
+    }
+
+See also: :ref:`t3extbasebook:view`

Documentation/Index.rst

@@ -1,10 +1,8 @@
-.. ==================================================
-.. FOR YOUR INFORMATION
-.. --------------------------------------------------
-.. -*- coding: utf-8 -*- with BOM.
+.. include:: Includes.txt
 
-.. include:: Includes.txt
 
+.. Every manual should have a start label for cross-referencing to
+.. start page. Do not remove this!
 
 .. _start:
 
@@ -14,49 +12,54 @@ mediaoembed
 
 .. only:: html
 
-	:Version:
-		|release|
+   :Classification:
+      mediaoembed
 
-	:Language:
-		en
+   :Version:
+      |release|
 
-	:Description:
-		Manual covering TYPO3 extension mediaoembed
+   :Language:
+      en
 
-	:Keywords:
-		oembed, video, audio, image, youtube, flickr, external
+   :Description:
+      Manual covering TYPO3 extension mediaoembed
 
-	:Copyright:
-		2014
+   :Keywords:
+      oembed, video, audio, image, youtube, flickr, external
 
-	:Author:
-		Alexander Stehlik
+   :Copyright:
+      2013-2019
 
-	:Email:
-		[email protected]
+   :Author:
+      Alexander Stehlik
 
-	:License:
-		This document is published under the Open Content License
-		available from http://www.opencontent.org/opl.shtml
+   :Email:
+      [email protected]
 
-	:Rendered:
-		|today|
+   :License:
+      This document is published under the Open Publication License
+      available from http://www.opencontent.org/openpub/
 
-	The content of this document is related to TYPO3,
-	a GNU/GPL CMS/Framework available from `www.typo3.org <http://www.typo3.org/>`_.
+   :Rendered:
+      |today|
 
+   The content of this document is related to TYPO3,
+   a GNU/GPL CMS/Framework available from `www.typo3.org <https://typo3.org/>`__.
 
-	**Table of Contents**
+
+   **Table of Contents**
 
 .. toctree::
-	:maxdepth: 5
-	:titlesonly:
-	:glob:
-
-	Introduction/Index
-	UsersManual/Index
-	Administrator/Index
-	Configuration/Index
-	KnownProblems/Index
-	ToDoList/Index
-	Targets
+   :maxdepth: 3
+
+
+   Introduction/Index
+   User/Index
+   Installation/Index
+   Configuration/Index
+   Developer/Index
+   KnownProblems/Index
+   ToDoList/Index
+   ChangeLog/Index
+   Support/Index
+   Links