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.


Contents

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 TSRef: http://forge.typo3.org/projects/typo3v4-doc_core_tsref/issues
TSconfig property or condition TSconfig: http://forge.typo3.org/projects/typo3v4-doc_core_tsconfig/issues
TCA property TCA reference: http://forge.typo3.org/projects/typo3v4-doc_core_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/typo3v4-doc_core_api/issues
Changes relating specifically to TYPO3 services TYPO3 Services: http://forge.typo3.org/projects/typo3v4-doc_core_services/issues
Changes or improvements related to security Security Guide: http://forge.typo3.org/projects/typo3v4-doc_guide_security/issues
Skinning API Skinning Guidelines: http://forge.typo3.org/projects/typo3v4-doc_core_skinning/issues
General information about the inner working of TYPO3 Inside TYPO3: http://forge.typo3.org/projects/typo3v4-doc_core_inside/issues
Introduction Package: any change to the IP has an impact on the Getting Started tutorial Getting Started: http://forge.typo3.org/projects/typo3v4-doc_tut_quickstart/issues

Writing the documentation changes

Any change to the TYPO3 Core that requires documentation must be accompanied by the relevant changes to the proper manual (see Choosing a bug tracker below). This is especially true for new or modified features, in particular APIs, TypoScript or TSconfig properties.

Ideally the change to documentation should be submitted to the relevant bug tracker as soon as the corresponding code change is pushed to Gerrit. Once the patch has been merged in Gerrit, a confirmation should be entered in the documentation issue. If the patch eventually gets rejected, the documentation issue should be dropped.

If the required documentation is rather long, don't put it directly in the bug report. Create a page in the TYPO3 wiki and reference it in the bug report.

Important information to include

  • The version numbers of the main core manuals follow the numbering scheme of the TYPO3 Core (at least for major version numbers). Choose the relevant version number in the "Target version" field (contact the Documentation Team if it's missing).
  • Use the "Related issues" to create a relationship between the Forge issue related to the patch and the documentation issue.

Documentation Status

The update progress of the Core Documentation can be followed on the Documentation Maintenance page.

Pending documentation (4.5)

doc_core_api (4.5)

Pagetree documentation
Documentation

23768: Core - API for Trees and ContextMenus [Closed to Steffen Kamper]

Tree API UML Diagram

UML Diagram

Context Menu API UML Diagram

UML Diagram

Adding of Custom Navigation Components
24071: Core - Support for Custom Navigation Components [Closed to Steffen Kamper]
Wiki Page

Workspace related changes
24361: Core - t3ver_stage should be int(11) instead of tinyint(4) [Closed to Tolleiv Nietsch]
t3ver_stage should have the type "int(11)" besides that the meaning changes since everything > 0 now references an actual "workspace stage" record. In addition to that it can have the values "0" which still refers to "edit", "-10" now refers to "ready to publish". Users should never really use these values to refer to these states, they should use the constants Tx_Workspaces_Service_Stages::STAGE_EDIT_ID, Tx_Workspaces_Service_Stages::STAGE_PUBLISH_ID

(francois 17:57, 29 October 2011 (CEST)) The above was taken into account for doc_core_tca but is left here as it also applies to doc_core_api.

Extension Architecture

ext_emconf.php

[1] 

key: docPath
data type: string
description: Path to manual.swx. Path is relative to extension directory and has no trailing slash. If not defined, the docPath is "doc"
             Example: 'docPath' => 'ressources/documentation',

t3lib_mail

23735: Core - Create a new API based on SwiftMailer to replace t3lib_htmlmail [Closed to Ernesto Baschny]

Since 4.5 TYPO3 provides a RFC compliant mailing solution, based on SwiftMailer. In the Install Tool ("All Configuration") several settings affect the sending process:

  • $TYPO3_CONF_VARS['MAIL'][transport] =
    • 'mail': default and backwards compatible setting. This is the most unreliable option. If you are serious about sending mails, consider using "smtp" or "sendmail".
    • 'smtp': Sends messages over SMTP. It can deal with encryption and authentication. Requires a mail server and configurations in transport_smtp_* settings. Works exactly the same on Windows, Unix and MacOS.
      • [transport_smtp_server]: <server:port> of mailserver to connect to. <port> defaults to "25".
      • [transport_smtp_encrypt]: Connect to the server using encryption and TLS. Requires openssl library.
      • [transport_smtp_username]: If your SMTP server requires authentication, the username.
      • [transport_smtp_password]: If your SMTP server requires authentication, the password.
    • 'sendmail': Sends messages by communicating with a locally installed MTA - such as sendmail. See setting transport_sendmail_command.
      • [transport_sendmail_command]: The command to call to send a mail locally. The default works on most modern UNIX based mail server (sendmail, postfix, exim)
    • 'mbox': This doesn't send any mail out, but instead will write every outgoing mail to a file adhering to the RFC 4155 mbox format, which is a simple text file where the mails are concatenated. Useful for debugging the mail sending process and on development machines which cannot send mails to the outside.
      • [transport_mbox_file]: The file where to write the mails into. Path must be absolute.

Creating Mails

This is how to generate and send a mail in TYPO3 starting with 4.5:

PHP script:
$mail = t3lib_div::makeInstance('t3lib_mail_Message');
$mail->setFrom(array($email => $name))
     ->setTo(array($email => $name))
     ->setSubject($subject)
     ->setBody($body)
     ->send();

Or if you prefer, don't concatenate the calls:

PHP script:
$mail = t3lib_div::makeInstance('t3lib_mail_Message');
$mail->setFrom(array($email => $name));
$mail->setTo(array($email => $name));
$mail->setSubject($subject);
$mail->setBody($body);
$mail->send();

Adding Attachments

PHP script:
	// Create the attachment
	// * Note that you can technically leave the content-type parameter out
$attachment = Swift_Attachment::fromPath('/path/to/image.jpg', 'image/jpeg');
 
	// (optional) setting the filename
$attachment->setFilename('cool.jpg');
 
	// Attach it to the message
$mail->attach($attachment);

Adding Inline Media (e.g. Images)

PHP script:
	// Attach the message with a "cid"
$cid = $mail->embed(Swift_Image::fromPath('image.png'));
 
	// Create a HTML body refering to it
$mail->setBody(
	'<html><head></head><body>' .
		'  Here is an image <img src="' . $cid . '" alt="Image" />' .
		'  Rest of message' .
		' </body></html>',
	'text/html' //Mark the content-type as HTML
);

Default Sender

For mails generated by TYPO3, a configuration option in the Install Tool allows the user to define a default email sender ("From:").

  • $TYPO3_CONF_VARS['MAIL'][defaultMailFromAddress]
  • $TYPO3_CONF_VARS['MAIL'][defaultMailFromName]

To make use of this setting in your extension, use the following code:

PHP script:
$from = t3lib_utility_Mail::getSystemFrom();
$mail = t3lib_div::makeInstance('t3lib_mail_Message');
$mail->setFrom($from);
...

Documentation Details

For more information about available methods for creating messages, refer to SwiftMail documentation:

Deprecated Methods

All other ways of sending emails in TYPO3 have been deprecated in 4.5, since they don't generate RFC conformant emails or don't allow flexible sending configuration:

  • t3lib_htmlmail: Deprecated.
  • t3lib_utility_Mail::mail(): Deprecated. Calls to it are routed to t3lib_mail via a hook, so that the configured transport (e.g. "smtp" or "mbox") is also respected for these legacy calls. Please make sure you test your mail sending routines before upgrading a production site to 4.5!

The back-end and install tool form protection

24097: Core - Introduce a form protection API [Closed to Ernesto Baschny]

The Core now provides a form protection against Cross-Site-Request Forgery (XSRF/CSRF).

Using the form protection in the back end

For each form in the BE (or link that changes some data), create a token and insert is as a hidden form element. The name of the form element does not matter; you only need it to get the form token for verifying it.

PHP script:
$formToken = t3lib_formprotection_Factory::get()
	->generateToken('BE user setup', 'edit')
);
$this->content .= '<input type="hidden" name="formToken" value="' . $formToken . '" />';

The three parameters $formName, $action and $formInstanceName can be arbitrary strings, but they should make the form token as specific as possible. For different forms (e.g. BE user setup and editing a tt_content record) or different records (with different UIDs) from the same table, those values should be different.

For editing a tt_content record, the call could look like this:

PHP script:
$formToken = t3lib_formprotection_Factory::get()
	->generateToken('tt_content', 'edit', $uid);

At the end of the form, you need to persist the tokens. This makes sure that generated tokens get saved, and also that removed tokens stay removed:

PHP script:
t3lib_formprotection_Factory::get()->persistTokens();

In BE lists, it might be necessary to generate hundreds of tokens. So the tokens do not get automatically persisted after creation for performance reasons.

When processing the data that has been submitted by the form, you can check that the form token is valid like this:

PHP script:
if ($dataHasBeenSubmitted &&
	t3lib_formprotection_Factory::get()->validateToken(
		(string) t3lib_div::_POST('formToken'),
		'BE user setup', 'edit'
	) ) {
	// processes the data
} else {
	// no need to do anything here as the BE form protection will create a
	// flash message for an invalid token
}

Note that validateToken invalidates the token with the token ID. So calling validate with the same parameters two times in a row will always return FALSE for the second call.

It is important that the tokens get validated before the tokens are persisted. This makes sure that the tokens that get invalidated by validateToken cannot be used again.

Using the form protection in the install tool

For each form in the install tool (or link that changes some data), create a token and insert is as a hidden form element. The name of the form element does not matter; you only need it to get the form token for verifying it.
PHP script:
$formToken = $this->formProtection->generateToken('installToolPassword', 'change');
// then puts the generated form token in a hidden field in the template

The three parameters $formName, $action and $formInstanceName can be arbitrary strings, but they should make the form token as specific as possible. For different forms (e.g. the password change and editing a the configuration), those values should be different.

At the end of the form, you need to persist the tokens. This makes sure that generated tokens get saved, and also that removed tokens stay removed:

PHP script:
$this->formProtection()->persistTokens();

When processing the data that has been submitted by the form, you can check that the form token is valid like this:

PHP script:
if ($dataHasBeenSubmitted &&
	$this->formProtection()->validateToken(
		(string) $_POST['formToken'],
		'installToolPassword',
		'change')
) {
	// processes the data
} else {
	// no need to do anything here as the install tool form protection will
	// create an error message for an invalid token
}

Note that validateToken invalidates the token with the token ID. So calling validate with the same parameters two times in a row will always return FALSE for the second call.

It is important that the tokens get validated before the tokens are persisted. This makes sure that the tokens that get invalidated by validateToken cannot be used again.

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)

doc_core_api (4.4)

Ext Direct API
22000: Core - ExtDirect API [Closed to Steffen Kamper]
Ext Direct Wiki Page

TYPO3 ExtJS Viewport
22319: Core - Add Viewport layout to BE [Closed to Steffen Kamper]
Wiki Page

Debug Panel
22642: Core - Rewrite of the debug panel (More Features!, More Stability!, More Usability!) [Closed to Steffen Kamper]
Wiki Page

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 doc_core_api 

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)

doc_core_media

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 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:

Errata

Please don't report errors in the Core Documentation here. Go to the Official documentation project on Forge, select the relevant manual in the left-hand menu and use the corresponding bug tracker to report the issue.

 

Retrieved from "http://wiki.typo3.org/wiki/index.php?title=Pending_Documentation&oldid=59726"
Personal tools
Namespaces
Variants
Actions