Translations
Info
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 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): http://forge.typo3.org/projects/typo3cms-doc-typoscript/issues
TSconfig property or condition TSconfig: http://forge.typo3.org/projects/typo3cms-doc-tsconfig/issues
TCA property TCA Reference: http://forge.typo3.org/projects/typo3cms-doc-tca/issues
API or other way of interacting with TYPO3, information for extension developers (but see below for more specific topics) Core APIs: http://forge.typo3.org/projects/typo3cms-doc-core-api/issues
Changes relating specifically to TYPO3 services TYPO3 Services: http://forge.typo3.org/projects/typo3cms-doc-typo3-services/issues
Changes or improvements related to security Security Guide: http://forge.typo3.org/projects/typo3cms-doc-security/issues
Skinning API Skinning Reference: http://forge.typo3.org/projects/typo3cms-doc-skinning/issues
General information about the inner working of TYPO3 Inside TYPO3: http://forge.typo3.org/projects/typo3cms-doc-inside-typo3/issues
Introduction Package: any change to the IP has an impact on the Getting Started tutorial Getting Started: http://forge.typo3.org/projects/typo3cms-doc-getting-started/issues

Pending documentation (4.5)

Inside TYPO3 (4.5)

CSH for FlexForms

CSH for FlexForms is handled more cleanly but requires adjustments. This has an impact in particular for FE plugins. To continue displaying
the CSH for their FlexForm, the CSH file must be declared as for other elements, i.e.

 t3lib_extMgm::addLLrefForTCAdescr('somekey', 'EXT:myext/locallang_csh.xml');

The key is defined as follows:

[table name].[field name].[DS pointer field 1](.[DS pointer field 2])

The table and the field are those where the FlexForm is used. In most cases this will be "tt_content.pi_flexform". The next elements of the key (still separated with dots) are the values of the field or fields (there may be only one) defined in the "ds_pointerField" property for the TCA of the FlexForm field. In the case of plugin options, the "ds_pointerField" property is set to "list_type,CType", so the key would be of the form:

tt_content.pi_flexform.[value of list_type field].list

"list" being the value of the CType field for a FE plugin. To give a complete example, let's assume that the plugin used is from the "comments" extension, the full key will be:

tt_content.pi_flexform.comments_pi1.list

because "comments_pi1" is the value found in the field "list_type" when using the plugin provided by the "comments" extension. So the "comments" extension would use the following call to register its FlexForm CSH:

t3lib_extMgm::addLLrefForTCAdescr('tt_content.pi_flexform.comments_pi1.list', 'EXT:comments/pi1/locallang_csh.xml');

With this new method, it is not necessary anymore to point to the CSH file from within the FlexForm's DS, though the "cshFile" tag should be left for compatibility with older versions of TYPO3.

On top of the above, it is advised (but not required) to use the "alttitle" in the CSH structure intensively, as it will improve the information displayed in the help pop-up window. In particular, don't forget to define the "general alttitle" which is used at the top of the window. Example:

<label index=".alttitle">My plugin's cool configuration options</label>

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

stylesheetDirectories

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

SPRITE ICON API
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);
}

Pending documentation (4.3)

Media manual

Manual for the new media CE (should become part of the manual of CSS Styled Content) http://forge.typo3.org/attachments/11257/doc_core_mediace_v2.sxw

The manual has been written for TYPO3 4.3 (not 4.2 as the cover says) by SteffenK and proofread by Jeff; see 20284: Core - [Feature] New Multimedia CE [Closed; assigned to Steffen Kamper].

Jeff wrote in #20284: "Still needs another pass, restructuring, and more content before its officially released but its a step the in the right direction :)"

November 2011: As far as the document above describes the TypoScript properties of the cObjects MEDIA, SWFOBJECT and QTOBJECT, it is now integrated in TSref. -Christopher.


Changes committed to CoreDocs

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