Context-sensitive menus
Contextual menus exist in many places in the TYPO3 backend. Just try your luck clicking on any icon that you see. Chances are good that a contextual menu will appear, offering useful functions to execute.
The context menu shown after clicking on the Content Element icon
API usage in the Core
Several TYPO3 Core modules are already using this API for adding or modifying items. See following places for a reference:
- EXT:impexp module adds import and export options for pages, content elements
and other records. See item provider
\TYPO3\and ES6 moduleCMS\ Impexp\ Context Menu\ Item Provider @typo3/.impexp/ context- menu- actions. js - EXT:filelist module provides several item providers for files, folders,
filemounts, filestorage, and drag-drop context menu for the folder tree.
See following item providers:
\TYPO3\,CMS\ Filelist\ Context Menu\ Item Providers\ File Drag Provider \TYPO3\,CMS\ Filelist\ Context Menu\ Item Providers\ File Provider \TYPO3\,CMS\ Filelist\ Context Menu\ Item Providers\ File Storage Provider \TYPO3\and the ES6 moduleCMS\ Filelist\ Context Menu\ Item Providers\ Filemounts Provider @typo3/filelist/ context- menu- actions. js
Tutorial: How to add a custom context menu item
Follow these steps to add a custom menu item for pages records. You will add a "Hello world" item which will show an info after clicking.
Context menu with custom item
Step 1: Implementation of the item provider class
Implement your own item provider class. Provider must implement
\TYPO3\ and
can extend \TYPO3\
or any other provider from EXT:backend.
See comments in the following code snippet clarifying implementation details.
EXT:examples/Classes/ContextMenu/HelloWorldItemProvider.php
<?php
namespace T3docs\Examples\ContextMenu;
/**
* This file is part of the TYPO3 CMS project.
*
* It is free software; you can redistribute it and/or modify it under
* the terms of the GNU General Public License, either version 2
* of the License, or any later version.
*
* For the full copyright and license information, please read the
* LICENSE.txt file that was distributed with this source code.
*
* The TYPO3 project - inspiring people to share!
*/
use TYPO3\CMS\Backend\ContextMenu\ItemProviders\AbstractProvider;
/**
* Item provider adding Hello World item
*/
class HelloWorldItemProvider extends AbstractProvider
{
/**
* This array contains configuration for items you want to add
* @var array
*/
protected $itemsConfiguration = [
'hello' => [
'type' => 'item',
'label' => 'Hello World', // you can use "LLL:" syntax here
'iconIdentifier' => 'actions-lightbulb-on',
'callbackAction' => 'helloWorld', //name of the function in the JS file
],
];
/**
* Checks if this provider may be called to provide the list of context menu items for given table.
*
* @return bool
*/
public function canHandle(): bool
{
// Current table is: $this->table
// Current UID is: $this->identifier
// return $this->table === 'pages';
return true;
}
/**
* Returns the provider priority which is used for determining the order in which providers are processing items
* to the result array. Highest priority means provider is evaluated first.
*
* This item provider should be called after PageProvider which has priority 100.
*
* BEWARE: Returned priority should logically not clash with another provider.
* Please check @see \TYPO3\CMS\Backend\ContextMenu\ContextMenu::getAvailableProviders() if needed.
*
* @return int
*/
public function getPriority(): int
{
return 55;
}
/**
* Registers the additional JavaScript RequireJS callback-module which will allow to display a notification
* whenever the user tries to click on the "Hello World" item.
* The method is called from AbstractProvider::prepareItems() for each context menu item.
*
* @param string $itemName
* @return array
*/
protected function getAdditionalAttributes(string $itemName): array
{
return [
'data-callback-module' => '@t3docs/examples/context-menu-actions',
// Here you can also add any other useful "data-" attribute you'd like to use in your JavaScript (e.g. localized messages)
];
}
/**
* This method adds custom item to list of items generated by item providers with higher priority value (PageProvider)
* You could also modify existing items here.
* The new item is added after the 'info' item.
*
* @param array $items
* @return array
*/
public function addItems(array $items): array
{
$this->initDisabledItems();
// renders an item based on the configuration from $this->itemsConfiguration
$localItems = $this->prepareItems($this->itemsConfiguration);
if (isset($items['info'])) {
//finds a position of the item after which 'hello' item should be added
$position = array_search('info', array_keys($items), true);
//slices array into two parts
$beginning = array_slice($items, 0, $position+1, true);
$end = array_slice($items, $position, null, true);
// adds custom item in the correct position
$items = $beginning + $localItems + $end;
} else {
$items = $items + $localItems;
}
//passes array of items to the next item provider
return $items;
}
/**
* This method is called for each item this provider adds and checks if given item can be added
*
* @param string $itemName
* @param string $type
* @return bool
*/
protected function canRender(string $itemName, string $type): bool
{
// checking if item is disabled through TSConfig
if (in_array($itemName, $this->disabledItems, true)) {
return false;
}
$canRender = false;
switch ($itemName) {
case 'hello':
$canRender = $this->canSayHello();
break;
}
return $canRender;
}
/**
* Helper method implementing e.g. access check for certain item
*
* @return bool
*/
protected function canSayHello(): bool
{
//usually here you can find more sophisticated condition. See e.g. PageProvider::canBeEdited()
return true;
}
}
Copied!
Step 2: JavaScript actions
Provide a JavaScript file (ES6 module) which will be called after clicking on the context menu item.
EXT:examples/Resources/Public/JavaScript/context-menu-actions.js
/**
* Module: @t3docs/examples/context-menu-actions
*
* JavaScript to handle the click action of the "Hello World" context menu item
*/
class ContextMenuActions {
helloWorld(table, uid) {
if (table === 'pages') {
//If needed, you can access other 'data' attributes here from $(this).data('someKey')
//see item provider getAdditionalAttributes method to see how to pass custom data attributes
top.TYPO3.Notification.error('Hello World', 'Hi there!', 5);
}
};
}
export default new ContextMenuActions();
Copied!
Register the JavaScript ES6 modules of your extension if not done yet:
examples/Configuration/JavaScriptModules.php
<?php
return [
'dependencies' => ['core', 'backend'],
'tags' => [
'backend.contextmenu',
],
'imports' => [
'@t3docs/examples/' => 'EXT:examples/Resources/Public/JavaScript/',
],
];
Copied!
Step 3: Registration
If you have autoconfigure: true set in your extension's Services. file all
classes implementing \TYPO3\
get registered as context menu items automatically:
EXT:examples/Configuration/Services.yaml
services:
_defaults:
autowire: true
autoconfigure: true
public: false
Copied!
If autoconfigure is disabled you can manually register a context menu item provider
by adding the tag backend.:
EXT:my_extension/Configuration/Services.yaml
services:
_defaults:
autoconfigure: false
MyVendor\MyExtension\ContextMenu\SomeItemProvider:
tags:
- name: backend.contextmenu.itemprovider
Copied!