Skip to content

Commit ef559f9

Browse files
author
Konrad Michalik
authored
Merge pull request #18 from xima-media/documentation
Documentation
2 parents 771ddb3 + 75cc0ab commit ef559f9

18 files changed

Lines changed: 533 additions & 5 deletions

File tree

‎.editorconfig‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,6 @@ indent_style = tab
2222
[package.json]
2323
indent_size = 2
2424

25-
# ReST files
26-
[{*.rst,*.rst.txt}]
27-
indent_size = 4
28-
max_line_length = 80
29-
3025
# SQL files
3126
[*.sql]
3227
indent_style = tab

‎CODE_OF_CONDUCT.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Code of Conduct
2+
3+
This project uses the
4+
[TYPO3 Code of Conduct](https://typo3.org/community/values/code-of-conduct).
5+
6+
When you contribute to this project or interact with community members,
7+
you agree to adhere to this code of conduct.

‎Documentation/Configuration/Index.rst‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
.. include:: /Includes.rst.txt
2+
3+
.. _configuration:
4+
5+
=============
6+
Configuration
7+
=============
8+
9+
The extension is ready to use without any further setup.
10+
11+
You can also adapt the extension to your needs, switch single menu entries and also disable the functionality.
12+
13+
Learn what configuration options are available on the following pages:
14+
15+
.. toctree::
16+
:maxdepth: 3
17+
18+
TypoScript
19+
UserSettings

‎Documentation/Configuration/TypoScript.rst‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
.. include:: /Includes.rst.txt
2+
3+
.. _typoscript:
4+
5+
=======================
6+
TypoScript
7+
=======================
8+
9+
Adjust the typoscript constants to restrict the usage of the frontend edit:
10+
11+
.. code-block:: typoscript
12+
:caption: setup.typoscript
13+
14+
plugin.tx_ximatypo3frontendedit {
15+
settings {
16+
# Ignore content elements by several criteria
17+
ignorePids =
18+
ignoreCTypes =
19+
ignoreListTypes =
20+
ignoreUids =
21+
22+
# Adjust the default menu structure by setting an entry to "0" to disable it
23+
defaultMenuStructure {
24+
div_info =
25+
header =
26+
div_edit =
27+
edit =
28+
edit_page =
29+
div_action =
30+
hide =
31+
move =
32+
info =
33+
history =
34+
}
35+
}
36+
}

‎Documentation/Configuration/UserSettings.rst‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
.. include:: /Includes.rst.txt
2+
3+
.. _user-settings:
4+
5+
=======================
6+
User Settings
7+
=======================
8+
9+
Go to :guilabel:`User Settings > Edit and advanced functions > Disable frontend edit`
10+
11+
The following options can be set in the user settings:
12+
13+
.. _user-settings-tx_ximatypo3frontendedit_disable:
14+
15+
.. confval:: tx_ximatypo3frontendedit_disable
16+
:type: boolean
17+
:Default: 0
18+
19+
Backend user can easily disable the whole frontend edit functionality within their user settings.

‎Documentation/DeveloperCorner/CustomStyling.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
.. include:: /Includes.rst.txt
2+
3+
.. _custom-styling:
4+
5+
=======================
6+
Custom Styling
7+
=======================
8+
9+
The dropdown was styled to not disturb the frontend layout. You can easily adjust the styling by providing an additional css or js file within your :code:`ext_localconf.php` which will be loaded together with the frontend edit resources:
10+
11+
.. code-block:: php
12+
:caption: ext_localconf.php
13+
14+
$GLOBALS['TYPO3_CONF_VARS']['EXTENSIONS']['xima_typo3_frontend_edit']['registerAdditionalFrontendResources'][] = 'EXT:custom_extension/Resources/Public/Css/Custom.css';

‎Documentation/DeveloperCorner/DataAttributes.rst‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
.. include:: /Includes.rst.txt
2+
3+
.. _data-attributes:
4+
5+
=======================
6+
Data Attributes
7+
=======================
8+
9+
Additionally, there is an option to extend your fluid template to provide data for extra dropdown menu entries, e.g. edit links to all news entries within a list plugin.
10+
11+
.. code-block:: html
12+
:caption: Custom Fluid Template
13+
14+
<div class="news-item">
15+
...
16+
<xtfe:data label="{news.title}" uid="{news.uid}" table="tx_news_domain_model_news" icon="content-news" />
17+
</div>
18+
19+
This generates a hidden input element with the provided data (only if the frontend edit is enabled). Within the parent content element (e.g. the whole list plugin), a new "data" section will show up on the dropdown menu to list all edit links.
20+
21+
.. figure:: /Images/data.png
22+
:alt: Frontend Edit Extended Data Entries
23+
24+
Keep in mind, that this only works if the parent content element has a c-id and offer one of the following data combinations:
25+
26+
- Edit record link (provide :code:`uid` and :code:`table` of the desired record, the link to the TYPO3 backend will be generated automatically)
27+
- Custom edit url (provide a custom :code:`url`)
28+
29+
30+
.. note::
31+
Keep in mind, that this option will add additional html elements to your dom, which can causes style issues.
32+
33+
.. seealso::
34+
35+
View the sources on GitHub:
36+
37+
- `DataViewHelper <https://github.com/xima-media/xima-typo3-frontend-edit/blob/main/Classes/ViewHelpers/DataViewHelper.php>`__

‎Documentation/DeveloperCorner/Events.rst‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
.. include:: /Includes.rst.txt
2+
3+
.. _events:
4+
5+
=======================
6+
PSR-14 Events
7+
=======================
8+
9+
Use the :code:`FrontendEditDropdownModifyEvent` to modify the edit menu to your needs. You can add, remove or modify buttons for specific content elements. See the example below:
10+
11+
.. code-block:: php
12+
:caption: Classes/EventListener/ModifyFrontendEditListener.php
13+
14+
<?php
15+
16+
declare(strict_types=1);
17+
18+
namespace Vendor\Package\EventListener;
19+
20+
use TYPO3\CMS\Backend\Routing\UriBuilder;
21+
use TYPO3\CMS\Core\Imaging\IconFactory;
22+
use TYPO3\CMS\Core\Utility\GeneralUtility;
23+
use Xima\XimaTypo3FrontendEdit\Enumerations\ButtonType;
24+
use Xima\XimaTypo3FrontendEdit\Event\FrontendEditDropdownModifyEvent;
25+
use Xima\XimaTypo3FrontendEdit\Template\Component\Button;
26+
27+
class ModifyFrontendEditListener
28+
{
29+
public function __construct(protected readonly IconFactory $iconFactory, protected readonly UriBuilder $uriBuilder)
30+
{
31+
}
32+
33+
public function __invoke(FrontendEditDropdownModifyEvent $event): void
34+
{
35+
$contentElement = $event->getContentElement();
36+
$menuButton = $event->getMenuButton();
37+
38+
// Example 1
39+
// Append a custom button (after the existing edit_page button) for your plugin to e.g. edit the referenced entity
40+
if ($contentElement['CType'] === 'list' && $contentElement['list_type'] === 'custom_plugin_name') {
41+
$menuButton->appendAfterChild(new Button(
42+
'Edit entity',
43+
ButtonType::Link,
44+
$this->uriBuilder->buildUriFromRoute(
45+
'record_edit',
46+
[
47+
'edit' => [
48+
'custom_entity' => [
49+
$contentElement['custom_entity_uid'] => 'edit',
50+
],
51+
],
52+
'returnUrl' => $event->getReturnUrl(),
53+
],
54+
)->__toString(),
55+
$this->iconFactory->getIcon('content-idea', 'small')
56+
),
57+
'edit_page',
58+
'edit_custom_entity'
59+
);
60+
}
61+
62+
// Example 2
63+
// Remove existing buttons
64+
$menuButton->removeChild('div_action');
65+
66+
$event->setMenuButton($menuButton);
67+
}
68+
}
69+
70+
Don't forget to register your event listener via PHP attributes (TYPO3 >= 13):
71+
72+
73+
.. code-block:: php
74+
:caption: Classes/EventListener/ModifyFrontendEditListener.php
75+
76+
#[AsEventListener(
77+
identifier: 'ext-some-extension/modify-frontend-edit-listener',
78+
)]
79+
80+
or register the event listener in your :code:`Services.yaml`:
81+
82+
.. code-block:: yaml
83+
:caption: Configuration/Services.yaml
84+
85+
services:
86+
Vendor\Package\EventListener\ModifyFrontendEditListener:
87+
tags:
88+
- name: event.listener
89+
identifier: 'ext-some-extension/modify-frontend-edit-listener'

‎Documentation/DeveloperCorner/Index.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. include:: /Includes.rst.txt
2+
3+
.. _developer-corner:
4+
5+
================
6+
Developer corner
7+
================
8+
9+
Two opportunities exists to extend the dropdown menu with custom entries:
10+
11+
- Use an :ref:`event <events>` to modify the menu directly
12+
- Use a :ref:`viewhelper <data-attributes>` to extend the menu with data entries
13+
14+
Additionally, you can provide a :ref:`custom css <custom-styling>` file to adjust the styling.
15+
16+
.. toctree::
17+
:maxdepth: 3
18+
19+
Events
20+
DataAttributes
21+
CustomStyling

‎Documentation/FAQ/Index.rst‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
.. include:: /Includes.rst.txt
2+
3+
.. _faq:
4+
5+
===
6+
FAQ
7+
===
8+
9+
.. rst-class:: panel panel-default
10+
11+
Why is the frontend edit menu not displayed on my page / for my content element?
12+
=======================================
13+
14+
There may be a number of reasons for this:
15+
16+
**Backend user session**
17+
18+
Are you currently logged into the TYPO3 backend? Otherwise the frontend edit will not working.
19+
20+
**Backend user permission**
21+
22+
Does your user have all permissions to edit the page as well as the content elements?
23+
24+
**TypoScript**
25+
26+
Is the TypoScript template "Frontend edit" included in your sitepackage? Do you have declared the constants to restrict the usage of the frontend edit?
27+
28+
**Content Element IDs**
29+
30+
Make sure that the content element "c-ids" (Content Element IDs) are available within your frontend template, e.g. "c908".
31+
32+
**Content Element on current Page**
33+
34+
For now only all content elements on the current page are "editable". So if you're using some kind of inheritance, e.g. for your footer, this content can't be edited. Maybe I will find a smarter solution for this in the future.
35+
36+
**Debug**
37+
38+
Check the network tab for the initial ajax call (something like :code:`/?type=1729341864` with the information about the editable content elements and the according dropdown menus.
39+
40+
41+
.. rst-class:: panel panel-default
42+
43+
After closing the edit form will I redirected to the wrong frontend location, e.g. to the root page
44+
=======================================
45+
46+
This could be caused by a strict referer header in your request. If the return url could not be determined correctly, you can force the url generation by pid and language in the extension setting: :code:`forceReturnUrlGeneration`.

0 commit comments

Comments
 (0)