Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
[DOCS] Add documentation for system extension adminpanel
This change should allow users to:
*  Discover the extension via docs.typo3.org
*  Allow different target groups like administrator,
   integrator and editor to get an idea about the feature
   set and how to use the extension.

Resolves: #93260
Releases: master, 10.4
Change-Id: I90a8f356231cc49baf3c8fbedd9625300827c094
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/68939
Tested-by: core-ci <typo3@b13.com>
Tested-by: Christian Kuhn <lolli@schwarzbu.ch>
Reviewed-by: Christian Kuhn <lolli@schwarzbu.ch>
  • Loading branch information
flicstar authored and lolli42 committed May 1, 2021
1 parent 70619f6 commit 09b5d89
Show file tree
Hide file tree
Showing 25 changed files with 664 additions and 0 deletions.
15 changes: 15 additions & 0 deletions typo3/sysext/adminpanel/Documentation/Configuration/Index.rst
@@ -0,0 +1,15 @@
.. include:: ../Includes.txt

.. _configuration:

=============
Configuration
=============

When the `admPanel` property is set, the Admin Panel displays at the bottom of
pages on the frontend. See the :ref:`admPanel section of the TypoScript
Template Reference<t3tsref:setup-config-admpanel>` for more information.

You also need to set the User TSconfig to enable the panel for the user. See
the :ref:`admPanel section of the TSconfig Reference<t3tsconfig:useradmpanel>`
for more information.
124 changes: 124 additions & 0 deletions typo3/sysext/adminpanel/Documentation/Extending/Index.rst
@@ -0,0 +1,124 @@
.. include:: ../Includes.txt

.. _extending:

=========================
Extending the Admin Panel
=========================

With EXT:fe_edit you can extend the Admin Panel.

Extension authors can write their own modules or add submodules to existing
modules.

Creating additional modules
===========================

An admin panel module commonly has:

* An icon, an identifier, a short info and a label
* initializeModule and onSubmit methods for initialization (done early in the
TYPO3 Request) and for reacting to changes (onSubmit is executed when the
settings are updated)
* Settings that influence page rendering or page display
* Methods to provide custom CSS and JavaScript files
* Submodules

To create your own Admin Panel module
=====================================

#. Create a new PHP class extending
`\TYPO3\CMS\Adminpanel\Modules\AbstractModule`.

#. Implement at least the following methods:

* `getIdentifier` - A unique identifier for your module. For example
`mynamespace_modulename`
* `getIconIdentifier` - An icon identifier which is resolved via the icon
API. Make sure to use a registered icon here.
* `getLabel` - Speaking label for the module. You can access language
files via `$this->getLanguageService()`
* `getShortInfo` - Displayed next to the module label, may contain
aggregated infos (such as `Total Parse Time: 200ms`)

#. Register your module by adding the following in your `ext_localconf.php`

.. code-block:: php
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['adminpanel']['modules']['mynamespace_modulename'] = [
'module' => [
\Your\Namespace\Adminpanel\Modules\YourModule::class,
'before' => ['cache'],
]
];
Using `before` or `after` you can influence where your module will be
displayed in the module menu by referencing the identifier / array key of
other modules.

Modules themselves do provide settings for the page rendering and global
actions (like preview settings, clearing caches or adding action buttons for
editing the page) but do not provide further content.

If you want to display additional content in the Admin Panel (like rendering
times or backtraces), you have to add a submodule to your main module.

To provide settings in a module, implement the method `getSettings`, which has
to return rendered HTML form elements (but without the form tag), ready to be
used in the Admin Panel main form.

Adding a sub-module
===================

An Admin Panel submodule has:

* An identifier and a label.
* initializeModule and onSubmit methods for initialization (done early in
the TYPO3 Request) and reacting to changes (onSubmit is executed when the
settings are updated).
* Module content (for example the Info submodules display information about
the current page or server configuration).
* Settings influencing their module content (for example the TypoScript
Time / Rendering sub module has settings that influence whether to display
messages or not).

As soon as a module has a submodule it will be displayed in the main Admin
Panel. Modules without submodules may only provide settings, and are only
displayed in the Settings overview.

Adding a submodule is similar to adding a module.

#. First, create a new class that extends `AbstractSubModule`. Implement at
least the following methods:

* `getIdentifier` - A unique identifier for your sub module (for example
`submodulename`)
* `getLabel` - Speaking label for the module - you can access language
files via `$this->getLanguageService()`
* `getContent` - The rendered HTML content for your module

#. Register your sub module by adding the following in your
`ext_localconf.php`

.. code-block:: php
$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['adminpanel']['modules']['mynamespace_modulename']['submodules']['submodulename'] = [
'module' => \Your\Namespace\Adminpanel\Modules\YourModule\Submodule::class
];
Where `mynamespace_modulename` references the main module where you want to
add your submodule, and `submodulename` is the identifier of your sub module.
This way, you can also register new custom sub modules to existing main
modules.

Examples
========

You can find examples for main and sub modules and their registration in the
Admin Panel extension. Short ones for a quick look are:

* `adminpanel/Classes/Modules/Info/PhpInformation.php` (Submodule)
* `adminpanel/Classes/Modules/InfoModule.php` (Main module, serves as
submodule wrapper only)
* `adminpanel/Classes/Modules/EditModule.php` (Main module, custom rendering
settings)
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
17 changes: 17 additions & 0 deletions typo3/sysext/adminpanel/Documentation/Includes.txt
@@ -0,0 +1,17 @@
.. This is 'Includes.txt'. It is included at the very top of each and
every ReST source file in THIS documentation project (= manual).

.. role:: aspect (emphasis)
.. role:: html(code)
.. role:: js(code)
.. role:: php(code)
.. role:: sep (strong)
.. role:: sql(code)
.. role:: typoscript(code)
.. role:: yaml(code)

.. role:: ts(typoscript)
:class: typoscript

.. default-role:: code
.. highlight:: php
63 changes: 63 additions & 0 deletions typo3/sysext/adminpanel/Documentation/Index.rst
@@ -0,0 +1,63 @@
.. every .rst file should include Includes.txt
.. use correct path!
.. include:: Includes.txt

.. Every manual should have a start label for cross-referencing to
.. start page. Do not remove this!
.. _start:

===========
Admin Panel
===========

:Extension key:
adminpanel

:Version:
|release|

:Language:
en

:Description:
Manual for the TYPO3 Admin Panel.

:Keywords:
admin panel, frontend, debug

:Copyright:
2021

:Authors:
Felicity Brand

:License:
This extension documentation is published under the `CC BY-NC-SA 4.0 <https://creativecommons.org/licenses/by-nc-sa/4.0/>`__ (Creative Commons) license.

:Rendered:
|today|

**TYPO3**

The content of this document is related to TYPO3 CMS,
a GNU/GPL CMS/Framework available from `typo3.org <https://typo3.org/>`_ .

**For Contributors**

You are welcome to help improve this guide.
Just click on "Edit me on GitHub" on the top right to submit your change
request.

.. toctree::
:maxdepth: 3

Introduction/Index
Installation/Index
Configuration/Index
Inspecting/Index
Settings/Index
Extending/Index
Changelog/Index
Sitemap
79 changes: 79 additions & 0 deletions typo3/sysext/adminpanel/Documentation/Inspecting/Debug/Index.rst
@@ -0,0 +1,79 @@
.. include:: ../Includes.txt

.. _debug:

================
Debugging a page
================

Click :guilabel:`Debug` on the Admin Panel bar to show general information
about the page.

.. figure:: ../../Images/Events.png
:alt: The Events tab of the Debug section of the Admin Panel
:class: with-border

The **Events** tab of the Debug section of the Admin Panel

There are four tabs in the **Debug** section.

Events
------

The Events list shows all events that were dispatched while the current page
was rendered. A developer can use this list while extending TYPO3 to find out
which event to use on any given page.

Click the arrow to expand the details for an event to see basic information
about the event's parameters.

.. figure:: ../../Images/EventDetails.png
:alt: An expanded event showing extra detail
:class: with-border

An expanded event showing extra detail

Log
---

The log tab shows all log entries that were generated during the current
request. You can adjust the log levels and grouping in the settings.

Click the cog icon at the top right of the Admin Panel bar to configure the
settings.

.. figure:: ../../Images/LogSettings.png
:alt: The settings for the Log tab of the Admin Panel
:class: with-border

The settings for the Log entries


Page title
----------

TYPO3 has a concept of “Page Title Providers”. The section “Page title”
displays all registered providers that were checked for the current
page. This helps to debug where the currently used page title is coming from.


Query Information
-----------------

Displays a list of SQL queries that were generated on the current page and
their performance.

.. figure:: ../../Images/Query.png
:alt: The Query tab of the Debug section
:class: with-border

The **Query** tab of the Debug section of the Admin Panel

Click on a query to open a detail view with the values used for the
placeholders.

.. figure:: ../../Images/QueryDetail.png
:alt: The values used in a query on the page
:class: with-border

The values used in a query run on the page
18 changes: 18 additions & 0 deletions typo3/sysext/adminpanel/Documentation/Inspecting/Index.rst
@@ -0,0 +1,18 @@
.. include:: ../Includes.txt

.. _inspecting:

=================
Inspecting a page
=================

For every page, the Admin Panel displays information about TypoScript, load
time and requests, and errors and warnings.

.. toctree::
:maxdepth: 3
:titlesonly:

TypoScript/Index
Info/Index
Debug/Index
69 changes: 69 additions & 0 deletions typo3/sysext/adminpanel/Documentation/Inspecting/Info/Index.rst
@@ -0,0 +1,69 @@
.. include:: ../Includes.txt

.. _info:

========================
Information about a page
========================

Click :guilabel:`Info` on the Admin Panel bar to show general information
about the page. There are four tabs in the Info section.

.. figure:: ../../Images/Info.png
:alt: The General tab of the Info section of the Admin Panel
:class: with-border

The **General** tab of the Info section of the Admin Panel


General
-------

The **General** tab displays general TYPO3 related information about the
current page.

Document Size
The size of the loaded HTML document

Page
The current page ID and type.

Frontend User Group
The current frontend user group restriction. Default is 0,-1 (no login
required).

Cache
Whether the current page is cached or not.

UserIntObjects
Whether there are any USER_INT objects (uncached plugins) on the page. This
is useful for performance analysis. See the **USER_INT** tab for more
details.

Total Parsetime
The total parsetime TYPO3 needed to render the page.


PHP
---

Information about the PHP installation on the server. This helps developers to
quickly analyze available PHP Extensions, global constants or version
constraints.

REQUEST
-------

This tab contains global PHP request information, for example the current
content of the $_COOKIE variable and the $_SERVER variable.

This information helps developers to analyze the server environment further
and find ini file paths or the IP address with which a user accesses the site.


USER_INT
--------

This is the detail view of the UserIntObjects section of the **General**
tab. If there are USER_INT objects, an integrator or developer can see details
here and use it to figure out which plugins are impacting the caching behavior.

0 comments on commit 09b5d89

Please sign in to comment.