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

Pending Documentation

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

warning - Message

This page is not used anymore!

TYPO3 4.6 was the last version for which the changes were temporarily documented here. From now on the relevant bug trackers of each core manual must be used. Please refer to the instructions below.

Documenting changes

Any change to the TYPO3 CMS Core that requires documentation or has an impact on existing documentation must be accompanied by the relevant changes to the proper manual. This is especially true for new or modified features, in particular APIs, TypoScript or TSconfig properties.

When you push such a change to Gerrit, you are requested to take the following steps:

  1. Open an issue in the manual(s) that is(are) impacted (if unsure which, look at the list below for help).
  2. In this issue set a relation to the Core issue using the Related issues field
  3. Set the Target Version to the one corresponding to the TYPO3 CMS Core (if it's missing, please content the Documentation Team, we will add it).
  4. Document the change in the Description of the issue. If it's lengthy, feel free to set up a wiki page and point to it. If you don't feel at ease writing about the change, don't worry, go ahead and the Documentation Team will improve on it. On the contrary, if you're fine writing, you're welcome to go the whole way and push a patch to the corresponding Git repository (see the section about contributing to the documentation).

Should the Core patch be dropped after all, please also mention this in the issue. This saves the Documentation Team quite a bit of looking things up.

Choosing a bug tracker

There exists one bug tracker per core manual. Use the chart below to help you choose which bug tracker to use in case you are unsure:

Type of change Bug tracker
TypoScript property or condition TypoScript Reference (TSref):
TSconfig property or condition TSconfig:
TCA property TCA Reference:
API or other way of interacting with TYPO3, information for extension developers (but see below for more specific topics) Core APIs:
Changes relating specifically to TYPO3 services TYPO3 Services:
Changes or improvements related to security Security Guide:
Skinning API Skinning Reference:
General information about the inner working of TYPO3 Inside TYPO3:
Introduction Package: any change to the IP has an impact on the Getting Started tutorial Getting Started:

Pending documentation (4.4)

Skinning Reference (4.4)

(Francois (talk) 12:09, 11 November 2012 (CET)) All information related to skinning should be move to the dedicated manual (including what is left in Core API).

2010-02-19 by Benjamin Mack (on behalf of Steffen Gebert) (I think this can be removed again, as this functionality was changed, haven't checked though) to be placed in the table of chapt. 6 in TYPO3 APIs


Add all *.css files of a directory.
Example: $TBE_STYLES['stylesheetDirectories'][$_EXTKEY][] = 'EXT:myskin/stylesheets/custom/';

It is encouraged  to separate the styles in two parts, once for the "structure" and the second for the "visual":
$TBE_STYLES['stylesheetDirectories'][$_EXTKEY]['structure'] = 'EXT:myskin/stylesheets/structure/';
$TBE_STYLES['stylesheetDirectories'][$_EXTKEY]['visual'] = 'EXT:myskin/stylesheets/visual/'; 

SPRITE ICON API. Added on 2010-05-02 by Benjamin Mack - Should be a new section right after the skinning API part. Edited on 2010-05-25 by Steffen Ritter

The sprite icons are a completely different approach than using single file images for each icon. In order to get an icon you don't need to know anything about the file, its location or size or whatever. The only thing you need to know are the CSS classes used. This API even helps you with that by only needing a single string name for an icon. You should always look up this "iconName" in the skinning manual.

== Example for creating HTML for icons in the TYPO3 backend ==

$icon = t3lib_iconWorks::getSpriteIcon('actions-document-new');
Returns: <span class="t3-icon t3-icon-actions-document t3-icon-document-new"> </span>

$icon = t3lib_iconWorks::getSpriteIcon('actions-document-new', array('title' => 'Create new record'));
Returns: <span class="t3-icon t3-icon-actions-document t3-icon-document-new" title="Create new record"> </span>

$icon = t3lib_iconWorks::getSpriteIcon('actions-document-new', array(
	'tagName' => 'a',
	'title'   => 'Create new record',
	'class'   => 'download-link',
	'html'    => 'Inner Code',
	'style'   => 'margin-left: 20px;'
Returns: <a class="t3-icon t3-icon-actions-document t3-icon-document-new download-link" title="Create new record" style="margin-left: 20px;">Inner Code</a>

The second parameter "$options" specifies the tag attributes, except for three special options "tagName", "html" (the inner HTML part) and "class" (additional CSS classes).
== Files ==

Icons for files or filetypes will work through the additional function "getSpriteIconForFile". The first parameter either takes a full path, a file extension, a filename or one of the two special keywords "folder" or "mount" (for file mounts). The second parameter takes the same array of options as the generic method.

$icon = t3lib_iconWorks::getSpriteIconForFile('EXT:t3skin/icons/options.gif');
$icon = t3lib_iconWorks::getSpriteIconForFile('options.gif');
$icon = t3lib_iconWorks::getSpriteIconForFile('gif');
Result:  <span class="t3-icon t3-icon-mimetype-media t3-icon-media-image"> </span>
$icon = t3lib_iconWorks::getSpriteIconForFile('EXT:t3skin/icons');
$icon = t3lib_iconWorks::getSpriteIconForFile('/');
$icon = t3lib_iconWorks::getSpriteIconForFile('folder');
Result:  <span class="t3-icon t3-icon-apps-filetree t3-icon-filetree-folder-default"> </span>

$icon = t3lib_iconWorks::getSpriteIconForFile('mount');
Result:  <span class="t3-icon t3-icon-apps-filetree t3-icon-filetree-mount"> </span>

== TCA database records ==

Icons for DB rows and table-based records are rendered through the additional function "getSpriteIconForRecord". The first parameter takes the name of the TCA table, the second parameter the array of the current row of the table to find out if any kind of overlay is necessary. The third parameter is the options array with the same functionality as in the other two methods.

Example: generate icon for current table and row
Usage:   t3lib_iconWorks::getSpriteIcon('pages', $row);
Result:  <span class="t3-icon t3-icon-apps-pagetree t3-icon-pagetree-page-not-in-menu"> </span>
(Note: This is depending on table and row)

== Overlays ==

There is also a third parameter for "t3lib_iconWorks::getSpriteIcon" that allows you to define overlays to an icon: Overlays are implemented by placing two spans on top of each other. To use them, you can just add an overlay as associative array where the keys of the array are the iconNames (like 'actions-document-download') and the options are the parameter.

$icon = t3lib_iconWorks::getSpriteIcon('actions-document-new', array('tagName' => 'a'), array('actions-document-download' => array('title' => 'Download now')));
Returns: <a class="t3-icon t3-icon-actions-document t3-icon-document-new"><span class="t3-icon t3-icon-actions-document t3-icon-document-download" title="Download now"> </span></a>

Currently the "t3lib_iconWorks::getSpriteIconForFile" API function does not allow for an overlay, and t3lib_iconWorks::getSpriteIconForRecord is taking care of the overlay automatically.

This system for the DB records is supposed to be only used with one overlay. The graphical icon guideline shows that subtypes of icons are defined through a overlay in the right bottom corner. The left bottom area is then used to show the most important state of the icon (just one). If the element has more than one state it will be displayed on hover currently just with text in the title tag - hopefully in the future with with some javascript overlay containing icons.

In order to select the most important state there is a priority list at

$TYPO3_CONF_VARS['BE']['spriteIconRecordOverlayPriorities'] => array('hidden', 'starttime', 'endtime', 'fe_group', 'protectSection', 'futuretiming')

As multiple states may have the same icon and the state name is not compatible with the css there is a mapping array at
$TBE_STYLES['spriteIconApi']['spriteIconRecordOverlayNames'] = 
    'hidden'       => 'status-overlay-hidden',
    'fe_group'     => 'status-overlay-access-restricted',
    'starttime'    => 'status-overlay-scheduled',
    'endtime'      => 'status-overlay-scheduled',
    'futuretiming' => 'status-overlay-scheduled',
    'readonly'     => 'status-overlay-locked',
    'deleted'      => 'status-overlay-deleted',
    'missing'      => 'status-overlay-missing',
    'translated'   => 'status-overlay-translated',
    'protectedSection' => 'status-overlay-includes-subpages',
== Extending TCA for Icon Names ==

The spriteGenerationApi automatically takes care of building css-classes and iconnames for your tca-records. They are in form of tcarecords-TABLENAME-TYPE and tcarecords-TABLENAME-default.

In order to generate special configuration or you ship your own sprites with the extension, you may to add the following configuration for you TCA ctrl-section of your table:
Note: If you use typeicon_classes, no sprites will be generated for this table, the icons have to be provided somewhere else! Furthermore the "default" entry as a fallback is mandatory.

This is an example for the table "pages":

$TCA['pages']['typeicon_classes'] = array(
    '1' => 'apps-pagetree-page-default',
    '3' => 'apps-pagetree-page-shortcut-external',
    '255' => 'actions-edit-deleted',
    'default' => 'apps-pagetree-page-default',

The array can be anything (doesn't need to be a number) it depends on $TCA['pages']['typeicon_column'] (like "CType" for tt_content)
Another example from tt_content:

$TCA['tt_content']['typeicon_classes'] = array(
    'header'  => 'mimetypes-x-content-header',
    'textpic' => 'mimetypes-x-content-text-picture',
    'image'   => 'mimetypes-x-content-image',

'''Example: How to extend typeicons for tt_content with an icon from your own extension'''
Place this code in ext_tables.php:

$TCA['tt_content']['ctrl']['typeicons'][$_EXTKEY . '_pi1'] = t3lib_extMgm::extRelPath($_EXTKEY) . '/icon_xyz.png';
$TCA['tt_content']['ctrl']['typeicon_classes'][$_EXTKEY . '_pi1'] =  'extensions-'.$_EXTKEY.'-type-xyz';
if (TYPO3_MODE == 'BE') {
  $icons = array(
    'type-xyz' => t3lib_extMgm::extRelPath($_EXTKEY) . 'icon_xyz.png',
  t3lib_SpriteManager::addSingleIcons($icons, $_EXTKEY);

Changes committed to CoreDocs

When a pending documentation change is committed to the Core Documentation, it is removed from this page and moved to: