Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

TYPO3Viewport

From TYPO3Wiki
Jump to: navigation, search
This page belongs to the Core Team (category Core Team)

General

The TYPO3 viewport can be found inside the files typo3/js/extjs/viewport*. It consists of a configuration file and the viewport component code itself. The viewport component is an extension of the Ext.Viewport component, whereby you can use all methods and functionalities from that component. The next few sections just describe the added features and some nice features that can be retrieved with the viewport now.

Viewport Structure:

Top Menu
Module Menu

Navigation Widget

Content Area
Debug Panel


You can find the code of the examples below, inside the demo extension that is available for download as an attachement to the bug tracker entry of the viewport patch.
22319: TYPO3 Core - Add Viewport layout to BE [Closed; assigned to Steffen Kamper]

Navigation Components

In TYPO3 4.5 we implemented a new possibility to add custom components like a navigation tree, information box or whatever to the navigation container of the viewport. This replaces the formerly described method that never worked like expected (for more informations just have a look at the history of this page).

You add custom components to a backend module with a simple registration call inside the ext_tables.php of your extension. You can find an example extension at the bugtracker entry that adds three modules with components: 24071: TYPO3 Core - Support for Custom Navigation Components [Closed; assigned to Steffen Kamper]

The registration method (addNavigationComponent()) takes two required parameters:

  1. Module name
  2. Component id and event name (explanation follows later)

An example:

  • ext_tables.php*
PHP script:
 
t3lib_extMgm::addNavigationComponent('tools_txpagetreeM1', 'typo3-pagetree');

As the directory structure is predefined, it's not neccessary to pass any path information to the register call:

- myExt
  |- components
     |- pagetree
        |- css
        |- javascript

The "components" directory contains all navigation components of your module. Any files inside the "css" and "javascript" directories are added automatically during the backend initialisation. For efficiency, the components are created lazily.

The component must be named without "typo3-" prefix.

One of your JavaScript files needs to contain the following code to create the component if requested.

  • someJS.js*
JavaScript:
Ext.ns('TYPO3.Components.PageTree');

TYPO3.Components.PageTree = Ext.extend(Ext.Panel, {
  id: 'typo3-pagetree',
  html: 'Hello World!'
});

TYPO3.ModuleMenu.App.registerNavigationComponent('typo3-pagetree', function() {
	return new TYPO3.Components.PageTree();
});

The created component's id is the component name with the given prefix.

Global Navigation Components

If you have written a navigation component that should be used by a whole group of modules that share the same prefix like "web" or "tools", you just need to register the component like in the following example. Anything else must be done like in the example above.

  • ext_tables.php*
PHP script:
 
t3lib_extMgm::addNavigationComponent('web', 'typo3-pagetree');

Note that you still can use more specialized navigation components for the submodules of a group.

ExtBase

If you want to register a component in an ExtBase module, you need to write the registration code like this (copied from the workspaces module):

PHP script:
 
Tx_Extbase_Utility_Extension::registerModule(
        $_EXTKEY,
        'web',  // Make module a submodule of 'web'
        'workspaces',   // Submodule key
        'before:info', // Position
        array(
                // An array holding the controller-action-combinations that are accessible
            'Review'        => 'index,fullIndex,singleIndex',
            'Preview'       => 'index,help,newPage'
        ),
        array(
            'access' => 'user,group',
            'icon'   => 'EXT:workspaces/Resources/Public/Images/moduleicon.gif',
            'labels' => 'LLL:EXT:' . $_EXTKEY . '/Resources/Private/Language/locallang_mod.xlf',
            'navigationComponentId' => 'typo3-pagetree', // navigation component
        )
    );

Loading Order

Sometimes you will need to define the loading order of CSS and JavaScript files. You can do this by creating a file called loadingOrder.txt in the designated directory, which has to contain the names of your files in the needed order. You don't need to define all files, because the remaining ones are loaded in their natural order.

Extending the Viewport

You can extend the TYPO3 viewport yourself if you need some special configuration options. The next example demonstrates this by adding a collapse/expand functionality to the module menu.

PHP script:
# ext_localconf.php
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['t3lib/class.t3lib_pagerenderer.php']['render-preProcess'][] =
  'EXT:' . $_EXTKEY . '/class.tx_typo3viewportdemo.php:tx_typo3viewportdemo->renderPreProcess'; 

# class.tx_typo3viewportdemo.php
<?php
class tx_typo3viewportdemo {
	public function renderPreProcess($parameters, $pageRenderer) {
		$pageRenderer->addExtOnReadyCode('
			Ext.apply(TYPO3.Viewport.configuration.items[1], {
				split: true,
				collapsable: true,
				collapseMode: "mini",
				hideCollapseTool: true,
				animCollapse: false
			});
		', true);
        }
}

?>

Debug Console

The newly introduced debug console is located inside the debug panel position at the south of the viewport. It's based upon an extended ExtJS tabPanel component. You can add a new tab to the debug console by using t3lib_div::debug() or directly with JavaScript.

PHP script:
debug('New Debug Console Entry', 'Info', 'Information');
$GLOBALS['error']->debug('New Debug Console Entry', 'Info', 'Information');
JavaScript:
TYPO3.Backend.DebugConsole.addTab('New Debug Console Entry', 'Info', 'Information');

If you need to add another tab widget, you can use the alternative method addTabWidget(), but note that you need to instantiate the component yourself.

JavaScript:
TYPO3.Backend.DebugConsole.addTabWidget(new Ext.Panel({
    title: 'Test',
    html: 'Test',
    closable: true,
    draggableTab: true
}), 'Special');

As you can see in the example above, there is a new property for the added widgets. It's called draggableTab and must be set to true if you want the tab to be draggable inside the group. Also, there is a common optional last parameter (a 0-based integer) for both JavaScript adding methods that can be used to specify the position of the tab in it's group.