Embed Size (px)
Citation preview
Inside Typo3October 5th 2002
Typo3 3.5b3
Copyright 2001-2002, Kasper Skårhøj, [email protected]
This document is published under the Open Content License
available from http://www.opencontent.org/opl.shtml
Inside Typo3 - 1
Table of contentOverview...........................................3Introduction......................................4
This document.............................................4Other documentation....................................4
TCE ..................................................5Data-structure..................................................5How permissions work.......................................7
Backend user setup......................................9Backend usergroup setup............................10
TBE.................................................11Files and folders..............................................11
Folders in typo3_src-xxx.............................13Position of uploaded images........................13Webspace and FTPspace..............................13How does the UNIX-filesystem permissionsinteract with Typo3? ..................................13
TBE modules....................................15Modules and submodules.................................15
Configuring modules...................................15Initialization of a module.............................16conf.php....................................................16locallang.php.............................................17
How to create a userdefined module..................18Initialization..............................................18Naming.....................................................18Enabling the module...................................18Note:........................................................18
Languages.......................................19Strategy....................................................19How translations are handled by the system. 19Update current languages...........................20Introduce a new language in Typo3..............20More detailed explanation............................20
Configuring Typo3............................22localconf.php..................................................22
Configuration browser in TBE.......................24tables.php......................................................25
Customization: ..........................................25Extending standard tables.php.........................40Field Descriptions............................................40
$TCA browser in TBE..................................42Project Code Guidelines....................43
Introduction...................................................43Files..........................................................43Classes......................................................43Functions...................................................44Special care about file-functions, is_file, is_dir,is_writeable, file_exists!..............................44
Headers and footers....................................44Formatting.................................................45Documentation...........................................46Naming conventions...................................47Global variables..........................................47Constants..................................................49Typical parameters pass by the url...............50System/PHP Variables - the nightmare.........50Remember this!.........................................52php.ini-optimized:......................................53
................................................................53Extending the system classes............54Typo3 Extension API........................61
Introduction...............................................61Files and locations......................................61
Indexed searching...........................67The principle...................................................67
HTML content.............................................67Use of hashes.............................................67How pages are indexed...............................67External media...........................................68Handling extendToSubpages - or not............68Access restricted pages...............................68
Tables............................................................68index_phash..............................................68index_section.............................................70index_fulltext.............................................70index_grlist...............................................70index_words, index_rel...............................70Todo and other things.................................71
Wish lists.........................................72TCE................................................................72
WORK and FEATURES:................................72TBE................................................................72
CHECK......................................................72Known Bugs: ............................................72LOGIN SAFETY: .........................................72BUGS:.......................................................73Javascript editing interface notes:................73
TBE Modules...................................................73Notes..............................................74
Bugs, considerations, notes, .......................74Rapport of "deleted"-check in typoscripts(190500) ..................................................74
ImageMagick notes..........................75Filesystem Locations (rpms): ......................75What is wrong with ImageMagick ver. 5+? ...75
Inside Typo3 - 2
Overview
(see the PDF-file "Typo3overview.pdf")
Inside Typo3 - 3
IntroductionThis documentThis document contains all development information on Typo3. This is supposed to be the final technical referenceapart from whatever may be noted in the scripts themselves.
Other documentationApart from this document there are the following documentation on Typo3:
PDF:
• TypoScript reference (TSRef). Updated with each release of Typo3. Very reference-like.
• Series of tutorials (three at the moment). Learn how to create sites based on HTML-template files. Discussesother options too. Good beginners point.
• TypoScript by Example; Examples and practicies of TypoScript. Breaks the silence found in TSRef. For studyand education.
• Administrators Guide. User administration and other administrative tasks in Typo3.
• $TCA array standard: tc-standard.pdf (if available, else see this document).
Web/PDF:
• Introduction (UK+DK). Gives and overview of Typo3 features.
• User Manual (UK+DK). Describes how to update content.
• Technology (UK). Gives an technical overview of Typo3.
• Cases (UK + DK). Describes some cases of Typo3 implementations.
Inside Typo3 - 4
TCE tce_main.php class (B1)
Data-structureThe tce_main-class is by default used through typo3/tce_db.php. tce_db.php provides and interface through whichyou submit the data- and cmd-array as $data and $cmd HTTP_POST_VARS, $cacheCmd is the caching commandand $redirect is the URL to redirect to.
If you would like a good example for your own work with the class, study this file. But since you're probably goingto use the class from a module, you should check out the implementation in some of the modules, eg. web_ts.Search for tce_main
Typical initialization in backend:
include("init.php");typo3lib("tce_main");$tce = new tce_main;
Functions:$tce->start($data,$cmd);$tce->process_datamap();$tce->process_cmdmap();
The $cmd-array:
$cmd[ tablename ][ uid ][ command ] = value
• tablename: Name of the tables. Must be configured in $TCA.
• uid: Uid of the record that is manipulated
• command: Types: "delete", "copy", "move"
• Value: While command is "delete", this should just be true (eg. 1). If command is "copy" or "move" thevalue is an integer which absolute value specifies a page-id. If value is positive then the record is inserted asthe first element on that page (paste into). If value is negative, the record is inserted after the record with thevalue as page-id (paste after).
$cmd['tablename']['uid'][delete] = 1$cmd['tablename']['uid'][copy] = [+/-pid]$cmd['tablename']['uid'][move] = [+/-pid]
Examples:
$cmd[tt_content][54][delete] = 1 Deletes tt_content record with uid=54$cmd[pages][1203][copy] = -303 Copies page id=1203 to the position after page 303$cmd[pages][1203][move] = 303 Moves page id=1203 to the first position in p. 303
The $data-array:
$data[ tablename ][ uid ][ fieldname ] = value
• tablename: Name of the table. Must be configured in $TCA.
• uid: Uid of the record that is modified. If you're creating new records, use a random string prefix with"NEW", eg. "NEW7342abc5e6d" or so.
• fieldname: Name of the field. Must be configured for the table in $TCA
• Value: The new value of the field. Should be addslashes()'ed already.
Examples:
This creates a new page titled "The page title" as the first page inside page-id 45:
Inside Typo3 - 5
$data[pages][NEW9823be87] = array("title" => "The page title","subtitle" => "Other title stuff","pid" => "45"
)
This creates a new page titled "The page title" right after page-id 45 in the tree:
$data[pages][NEW9823be87] = array("title" => "The page title","subtitle" => "Other title stuff","pid" => "-45"
)
This creates two new pages right after each other, located right after the page-id 45:
$data[pages][NEW9823be87] = array("title" => "Page 1","pid" => "-45"
)$data[pages][NEWbe68s587] = array(
"title" => "Page 2","pid" => "-NEW9823be87"
)
This updates the page with uid=9834 to a new title, "New title for this page", and no_cache checked:
$data[pages][9834] = array("title" => "New title for this page","no_cache" => "1"
)
Clear cache:
$tce->clear_cacheCmd($cacheCmd);
$cacheCmd can be
• [integer] : clears cache for that page-id,
• "all" : clears cache for all pages, templates, etc (only admin-users)
• "pages" : clears cache for all pages (only admin-users)
Flags you can set in the class:
• $tce->deleteTree: Boolean. If this is set, then a page is deleted by deleting the whole branch underit (user must have deletepermissions to it all). If not set, then the page is delete ONLY if it has no branch.Default is false.
• $tce->copyTree: Integer. If 0 then branch is NOT copied. If 1 then pages on the 1st level iscopied. If 2 then pages on the second level is copied ... and so on. Default is zero.
• $tce->reverseOrder: Boolean. If set, the dataarray is reversed in the order, which is a nice thing if you'recreating a whole bunch of new records. Default is zero.
• $tce->copyWhichTables: This list of tables decides which tables will be copied. If empty then none will. If"*" then all will (that the user has permission to of course). Default is "*"
Inside Typo3 - 6
How permissions work
Page permissions:
• Every page has an owner, group and everybody-permission.
• The owner and group of a page can be empty. Nothing matches with an empty user/group (except "admin"users).
• Every page has permissions for owner, group and everybody in these five categories:
1 Show: See/Copy page and the pagecontent.
16 Edit pagecontent: Change/Add/Delete/Move pagecontent.
2 Edit page: Change/Move the page, eg. change title, startdate, hidden.
4 Delete page: Delete the page and pagecontent.
8 New pages: Create new pages under the page.
(Definition: "Pagecontent" means all records (except from the "pages"-table) related to that page.)
Lists:
Apart from the page permissions every usergroup has a:
• positivelist of tables that may be edited.
• positivelist of tables that are shown in the interface. This list has the list of tables for editing prepended.
• positivelist of pageTypes (pages.doktype) that may be chosen.
• positivelist of "excludefields" that are not excluded.
• positivelist of modules/submodules.
When a user is a member of more than one group, the permissions are "added" together.
"excludeFields":
Accesscontrol to certain fields in tables are done in the fashion that a field is marked "exclude" in tables.php and a
Inside Typo3 - 7
user must have explicit permission via "excludefields"-list in order to edit that field.
Modules:
Access to modules are permitted if 1) the module has no restrictions (the conf.php for the module specifies this) or2) if the user has the module included by the positivelist. Users must have access to the main module in order toaccess submodules inside.
PageTypes:
Choice of pageTypes (doktype) for a page is associated with:
• an icon.
• permitted tables on this page.
• if the pageType is 1) SysFolder (>=200, can not be seen), 2) Webpage (<200, can be seen)
Mounts
Users have
• DB-mounts (database-mounts) which are page-ids in a list that are "mounted" as rootpoints in the page-tree(web-module). Of course users must have read access to the DB-mounts pages - if not they are not mounted.
• filemounts which are filepaths "mounted" as rootpoints in the file-administration (file-module). Paths can bemounted both relative to "fileadmin/" or absolute (in which case the path must be in the folder specified with$TYPO3_CONF_VARS["BE"]["lockRootPath"]). If a "userHomePath" and/or "groupHomePath" is definedusers/groups automatically have the directory named by their uid-number (for be_users it may be prependedwith "_[username]", but without will do just fine) mounted.
"Admin" users:
There is an admin-flag for users. There should be at least one admin user on the system. Admin users are the onlyusers with access to the page-tree root and thus are the only ones to create new users.
Basically "admin"-users can do anything. There's absolutely no limitations. Like the "root"-user on a UNIX system.
Inside Typo3 - 8
Backend user setup
Inside Typo3 - 9
Backend usergroup setup
Inside Typo3 - 10
TBETypo3 Backend Interface (B2)
Files and folders
Writeaccess
You may writeprotect the whole Typo3 source installation (typo3_src-xxx) except from the "typo3/temp/" folderinto which modified icons, menu labels and panes are written. Currently this only works with the GIF-version ofGDlib though.
Files of typo3/
Please note:
Sometimes I state that a document is "sensible". That's because some of these documents are generated byJavaScript and in Netscape browsers that seem to introduce som errors from time to time. If a document issensible it's because I have experienced that very small changes - like deleting blank lines for instance - can makethe difference of a JS-error!
File: Description:
main.php/main.js This is the very core of the Typo3 interface. Many kb's of JavaScript code thatdoes almost all of the central operations in the interface. This is the framesetfor the whole interface
border.html Background-image that draw the bar between the tree-window and list-window
buttons_frame.php The document, that holds the logout and clipboard buttons in the upper rightcorner. Referenced from main.html
main_menu.php The document, that holds the pane in the upper left corner of Typo3.Referenced from main.html
md5.js This JavaScript is the md5-function needed to make md5-hashes.
palettes.php
propframe.php
CLIPBOARD
clipboard.php The frameset for the clipboard. This includes JS-functions for communicationwith the main-window
Inside Typo3 - 11
File: Description:
clipboard_content.html The document, that holds the clipboard content. Is almost empty and just callssome JS-functions in order to draw the content.
clipboard_menu.php This document is the pane and menu for the clipboard.
clipboard_content_dummy.html This is a dummy document. Just sets a proper background-color
WEB MODULE
db_frameset.html The frameset for the web-tab
db_listframe.html This is the list-window default document.
db_navframe.html Draws the tree of pages. Calls a JS-function in the main-frame from where thecontent is passed to this document.
db_new.php Lets you create a new database item
db_list.php /db_list.inc This shows the list of elements in in the listwindow.
DOCUMENT MODULE
editwin_content.html This document draw the content of the document tab! It calls some JS in thetop-frame. It's very sensible to changes. Netscape may fail if you make anychanges in this document!!
FILE TAB
file_frameset.html The frameset for the file-tab
file_listframe.html This is the file list-window default document.
file_navframe.html Draw the tree of file folders. Calls a JS-function in the main-frame.
file_newfolder.php New-folder document. Sensible.
file_rename.php Rename file/folder document. Sensible.
file_upload.php The upload-document for the file-tab
file_list.php / file_list.inc This shows the list of files from a folder.
tce_file.php Script that performs the file-operations. This corresponds to the tce_db.phpscript as this script has a syntax by which you can submit information andmake it do changes on the server! This is documented elsewhere.
MISC
debug_data.html Prints out the data loaded into the JS. This is called from main.html if you click*between* the tabs in the upper pane.
dummy.html Dummy document that just sets the background color.
dummy_debug.html Dummy document that just prints out "DUMMY" and lets you click a link thatcalls the status.php-script that'll refresh the interface. Mostly used fordebugging this one!
FUNCTIONS
palettes.php The palettes used on the document-tab
propframe.php The options - like document-choise and menus - above the palettes.
ADMINISTRATION
index.php This is the login-screen!
getunique.php This script is called to check and fetch a unique value from the database
init.php This autheticates the user and MUST be called as the very first action by anybackend script! Look in the file for more information. init.php should beincluded as the very first thing in almost all scripts.
template.php This holds functions for layout modules and other usefull stuff. If also containsfunctions for generating interfaceGraphics. The language object is alsoinitialized here. template.php should be included after init when a script is aninterface-script
load_edit.php This fetches the information from the database and lets you edit this...
load_tree.php This loads the db-tree / file-tree
tce_db.php This is the Typo Core Engine. The script includes tce_main.php from typo3liband processes the instructions sent. Afterwards it jumps to the $redirect-scriptand if this is not specified it jumps to the status.php script.
thumbs.php This script generate a GIF/PNG-thumbnail of an image
Inside Typo3 - 12
Folders in typo3_src-xxx
Folder Description:
apps Typo3-based "applications". This is additional PHP-scripts that provides acertain functionality together with a database and tables-configuration. Thiscould be a customized intranet-applications eg.
Currently there are the Freesite Creator - a system for quick creating ofwebsites.
Coming up may be "etest" (webbased multiple choise), "netprint" (digitalphotolab - for digital film developers)
misc Information, notes, database upgrades and static_template-files from previousreleases
t3lib Libraries included by both frontend and backend (TCE, TBE)
t3lib/install/ tables.php, sql-files, etc. which are updated for each new version released.
tslib Libraries included ONLY by the frontend (TS)
tslib/media/... Default media-files like bullets, icons and include-scripts for forums,guestbooks and such. Good place to study examples of PHP-include scripts soyou can write your own extensions effectively.
typo3 The standard Typo3 interface (TBE)
typo3/gfx Graphic icons
typo3/lang Language definitions. Subfoldes holds other languages than english, which isdefault.
typo3/mod Modules and submodules.
typo3/t3lib t3lib (softlinked from ../t3lib/)
typo3/temp Autogenerated pane-labels, click-menu labels and icons in the interface. Mustbe writeenabled for the webserver-user.
typo3/rte Rich Text Editor files
FILES
t3lib/install/tables.php The standard database tables.php file. Defines the tables in the database soTypo3 knows how to handle them.
Position of uploaded imagesWhen you upload images (and files in general) to the server, they are by default placed in a folder named"_temp_" (TEMP with bold). If this folder does not exist in the root of one of the filemounts of a user, files cannotbe uploaded.
When files are attached to a record the files are copied and not moved (typically to the folder "uploads/pics/"depending on the setup of tables). This means that you must delete the content of the TEMP-folder from time totime as these files are not used anymore.
Webspace and FTPspaceRestrictions:
• In webspace you cannot unzip files
• You cannot copy or move folders from ftp to webspace.
(see the classes basicfilefunctions, extfilefunctions and tce_file.php)
How does the UNIX-filesystem permissions interact with Typo3? The answer is simple: Typo3 runs as the user, Apache "runs" as. This depends on the httpd.conf file of Apache.Default is "nobody" as far as I know.
The main thing is, that Typo3 must be able to write to certain folders in order for the file-administration to work.This means that after installation of Typo3, you should alter the user of the scripts and folders, probably with the
Inside Typo3 - 13
"chown" command.
If you have access to the webserver through ftp, you might be uploading scripts with yourself as user. Thesescripts might be executable by Apache as PHP-scripts but when the scripts need to write to eg. the upload-folder,this folder might be owned by "you" and thereby Typo3 does not work. Therefore; the folders Typo3 needwriteaccess to must be writeable by the Apache-user.
Folders that requires writeaccess are fileadmin/*, uploads/* for the frontend, typo3temp/ for both frontend andbackend and typo3/temp/ for TBE only.
Another issue is if you mount user-directories (see the localconf-file). You may mount a directory to which you haveftp-access. But if you do so, files uploaded to this directory may not be deleted by Typo3. That's normally not aproblem - you can delete them again by ftp, but it's much worse if you do not enable read-access for the Apache-user to that directory. Then the directory-structure will not be read and it does not show up on the file-tab.
Inside Typo3 - 14
TBE modules(B4)
Modules and submodulesModules and submodules are defined as what appears in the "pane"s in Typo3. The submodules are also(preferably) refered to as 'modules' when combined with a full reference like “Web>List”. Otherwise you wouldrefer to this module as 'the submodule List of the Web tab' or 'the List submodule in the Web module'.
The location of the built-in modules is in typo3/mod/. You can control which modules are enabled for a specificTypo3 solution by modifying the setup from t3lib/install/tables.php through a extTableDef-script.
Configuring modules
$TBE_MODULES = Array ("web" => "layout,list,perm,ts,func,log,dmail","file" => "list,images","doc" => "", // This should always be empty!"spacer1"=>"","user" => "","tools" => "dbint,log,config","help" => "about,quick"
);
This global array configures the modules. The order also defines the order of appearance in TBE.
The syntax is
$TBE_MODULES[ module ] => "submodule_1,submodule_2,submodule_3,submodule_4"
module: Must be the exact name of the module folder in "typo3/mod/[module]"
submodule: Must be the exact name of the submodule folder in "typo3/mod/[module]/[submodule]"
The list of submodules should be without spaces. If the list is empty no submodules are generated. For the "doc"module the list must always be empty!
If a module or submodule is named "spacer...." then a little space is put in (eg. "spacer1" or "spacer2")
Description from tables.php file on module setup:
Every entry in this array represents a tab in the upper left corner pane in the Typo3 interface
Add Modules: If the key (associative key) of the entry exists as a folder by that same name in the folder "mod/"-folder AND ifthat folder holds a conf-file (with valid PHP-configuration inside!) then a tab is added to the pane. If this is not thecase the entry is regarded as a "spacer" in the pane
Add Submodules:
Inside Typo3 - 15
As long as the value of a valid (see above) module is empty ("") then no submodules are added. If not the value isregarded as a comma-sep. list of submodules. These must exist as subfolders to the modules folderand if they do not they are just regarded as spacers instead.
Initialization of a moduleStart the index.php file with at least
$BACK_PATH = “”;unset($MCONF);include ("conf.php");include ($BACK_PATH."init.php");
This is the basic requirements - that conf.php is included and init.php is then called in order to connect to thedatabase and authenticate the user. Notice that $MCONF is cleared so no extenal database is sent.
Normally a initialization like this more common:
unset($MCONF);include ("conf.php");include ($BACK_PATH."init.php");include ($BACK_PATH."template.php");include ("locallang.php");$be_user->modAccess($MCONF,1);
$perms_clause = $be_user->getPagePermsClause(1);typo3lib("page");class pageselect extends pageselect_base {
var $where_hid_del = " AND NOT pages.deleted";}function fw($string) {
return $GLOBALS[template]->fontwrap($string);}
stdlib("files");stdlib("htmlmail");
Here template.php is included. This provides a class for outputting the nice "document"-interface of Typo3.
Then locallang.php is included. This file contains labels for the interface translated to the system languages.
Finally the access to the module is verified. Important step as not every user should gain access to every module.
After that the functions are just some of the standard function use in the default modules.
conf.phpExample:
<?$TYPO3_MOD_PATH="mod/web/func/";$BACK_PATH="../../../";
$MLANG["default"]["labels"]["tablabel"] = "Advanced functions";$MLANG["default"]["tabs"]["tab"] = "Func";$MLANG["default"]["tabs_images"]["tab"] = "func.gif";
$MLANG["dk"]["labels"]["tablabel"] = "Avancerede funktioner";$MLANG["dk"]["tabs"]["tab"] = "Funk.";
$MLANG["de"]["labels"]["tablabel"] = "Erweiterte Funktionen";$MLANG["de"]["tabs"]["tab"] = "Funk.";
$MLANG["no"]["labels"]["tablabel"] = "Avanserte funksjoner";$MLANG["no"]["tabs"]["tab"] = "Funk.";
$MLANG["it"]["labels"]["tablabel"] = "Funzioni avanzate";$MLANG["it"]["tabs"]["tab"] = "Funzione";
$MLANG["fr"]["labels"]["tablabel"] = "Fonctions avancées";$MLANG["fr"]["tabs"]["tab"] = "Fonc.";
$MCONF["script"]="index.php";$MCONF[“access”]="admin";$MCONF[“name”]="web_func";
Inside Typo3 - 16
?>
This is important configuration for your module:
• $TYPO3_MOD_PATH="mod/web/func/"; - Sets up the path of the module relative the the TBE root in typo3/.Used in init.php to determine the sitepath. Very, very important. If this is not correct, your module will not passinit.php without an error.
• $BACK_PATH="../../../"; - Sets up the path "back" to the TBE root. Used by filereferences primarily.
• $MLANG["default"]["labels"]["tablabel"] = "Advanced functions"; - Defines the image-alt-text on the tab in themodule pane. (Language specific)
• $MLANG["default"]["tabs"]["tab"] = "Func"; - Defines the label of the tab in the module pane. (Languagespecific)
• $MLANG["default"]["tabs_images"]["tab"] = "func.gif"; - Defines an optional imagefile for the tab in themodule pane.
• $MCONF["script"]="index.php"; - defines the default module script
• $MCONF[“access”]="admin"; - Defines which access criteria there is. If "admin", only admin-users haveaccess. If "user", "group" or "user,group" then the module is by default inaccessible. Access is granted on eitheruserlevel and/or grouplevel. If the value is "user,group" it means that the module appears in the module list forboth users and groups. If this field is empty, everybody has access. It's not recommended to keep this fieldclear.
$MCONF[“name”]="web_func"; - Module name, defined as module_submodule or if only a module, module
Module information is gathered in main.php when the interface is loaded. At that point, the conf.php-files of allenabled modules are examined and if modules required user/group access then that is verified before the moduleis included in the interface.
locallang.phpExample:
<?$localLang = Array (
"default" => Array ("title" => "Advanced functions"
),"dk" => Array (
"title" => "Avancerede funktioner"),"de" => Array (
"title" => "Erweiterte Funktionen"),"no" => Array (
"title" => "Avanserte funksjoner"),"it" => Array (
"title" => "Funzioni avanzate"),"fr" => Array (
"title" => "Fonctions avancées")
)?>
To get the "title" in the correct language (based on the users configuration) for your modules output, call thisfunction:
echo $LANG->getLL("title");
Inside Typo3 - 17
How to create a userdefined moduleUserdefined modules are modules that is used on only some websites and therefore does not reside in typo3/mod/.
Userdefined modules are always located in subdirs to typo3conf/ (which already holds all sitespecific configurationoptions).
InitializationLike the default modules and submodules this is a very normal way to initialize and authenticate a custom module:
unset($MCONF);include ("conf.php");include ($BACK_PATH."init.php");include ($BACK_PATH."template.php");include ("locallang.php");$be_user->modAccess($MCONF,1);
The conf.php file could look like this:
<?$TYPO3_MOD_PATH="../typo3conf/web/uEtest/";$BACK_PATH="../../../typo3/";
$MLANG["default"]["labels"]["tablabel"] = "E-test module";$MLANG["default"]["tabs"]["tab"] = "Etest";$MLANG["default"]["tabs_images"]["tab"] = "etest.gif";
$MLANG["dk"]["labels"]["tablabel"] = "E-test modul";$MLANG["dk"]["tabs"]["tab"] = "Etest";
$MCONF["script"]="index.php";$MCONF[access]="user,group";$MCONF[name]="web_uEtest";?>
Especially notice how TYPO3_MOD_PATH, $BACK_PATH and $MCONF[name] is set.
NamingIn order not to use potential future default module names, please prefix your modulename with a "u", like in thisexample "web_uEtest".
Also, if you place your custom module in a subfolder to a folder, that is already registred as a module (like in thiscase, "web/uEtest/"), the module will become a submodule to that module!
Enabling the moduleFinally you must enable the module by including it in the $TBE_MODULES array in tables.php.
If you don't like to alter tables.php because you use the standard version, you can put this into your table-extension file:
$TBE_MODULES["web"].= ",uEtest";
This will add the "web_uEtest" module to the submodules of the web-module.
Note:If you're running on a PNG-based Typo3 solution, backend graphical items are not generated and therefore the tabin the pane will probably not show up!
Inside Typo3 - 18
Languages(B2,B4)
StrategyThe strategy of language implementation in Typo3 is to translate all the user-parts of the TBE interface but let theadmin-parts remain in english. The reason is that the admin part changes and expands too quickly but also that itwould be a huge task to both implement and translate. And in the end all the communication between developersis done in english anyway. So in fact there are strong reasons for NOT translating the whole system into locallanguages!
How translations are handled by the systemThe folder typo3/lang/ contains all translations for the main system parts. The “conf.php”-files holds a number ofsystem labels and there is a file for each language in its own folder. Furthermore there are “locallang”-files. Thesealways contains an array, $LOCAL_LANG, where each key is another array with keys representing labels that aretranslated.
locallang*.php:
The “locallang”-files with the $LOCAL_LANG array are the dominating way of supplying translations in Typo3 foralmost all parts and in particular all extensions. The good thing about them is that they are easy to manage bytranslation tools and auto-write. Further they allow to group related labels together and only load relavant labelsinto memory as requested.
language-split:
An old concept called “language-split” has been around for use with typically table-names, field names etc in TCAarrays. This concept is based on a single string with labels separated by “|” according to the number of systemlanguages defined in the TYPO3_languages constant. But this approach is now depreciated for the future because itis not very scalable and it's VERY hard to maintain properly. Therefore the “locallang” concept is now also allowedfor use anywhere a value is defined to be “language-splitted”. Instead of specifying a number of labels separatedwith “|” you simply write a code, which refers to a locallang-file/label inside of that.
Syntax is “LLL:[file-reference of locallang file]:[key-name]:[extra settings]”.
File-reference should be a filename relative to PATH_site. You can prepend the reference with “EXT:[extkey]/” inorder to refer to locallang-files from extensions.
Example:
For the extension “mininews” we have a field called “title”. Normally this would be translated into danish like this inthe TCA:
"title" => Array ("exclude" => 0,"label" => "Title:|Titel:","config" => Array (
"type" => "input","size" => "30","eval" => "required",
)),
But now we would create a file, “locallang_db.php” in the root of the extension directory. This would look like this:
<?php$LOCAL_LANG = Array (
"default" => Array ("tx_mininews_news.title" => "Title:",
),"dk" => Array (
"tx_mininews_news.title" => "Titel:",),"de" => Array ()
);?>
As you can see there is an english (red) and danish (green) translation. But the german is still missing.
Now, In the TCA array we change the “language-splitted” label to this value instead:
Inside Typo3 - 19
"title" => Array ("exclude" => 0,"label" => "LLL:EXT:mininews/locallang_db.php:tx_mininews_news.title:ESQ","config" => Array (
"type" => "input","size" => "30","eval" => "required",
)),
As you can see it has now become a reference to the file “locallang_db.php” in the mininews extension. Inside thisfile we will pick the label “tx_mininews_news.title” (this associative key could be anything you decide. In this caseI have just been systematic in my naming).
Notice how the reference to the locallang file is divided into three parts marked with colors corresponding with thesyntax mentioned before: “LLL:[file-reference of locallang file]:[key-name]:[extra settings]”.
The “extra-settings” set to “ESQ” means that single quotes (') will be escaped. This is required for all labels set forfieldnames (only! - not table-names or item-lists) and the requirement is because of the classic backend which willnot load if singlequotes in field-name labels are not escaped. Strings in item lists are not required to do this. Readmore about these special requirements in the section about the TCA array.
Update current languagesYou can easily gain an overview over missing translations in Typo3 with the translation interface. When you'relogged in in the backend interface (TBE), you aim your browser at this script, "typo3/dev/translations.php". Thatguides you through.
Translation of extensions are done on typo3.org by the translation tool online there!
Introduce a new language in Typo3First do it officially by telling the developers to include a new language key. This is done by two steps:
1) Modify t3lib/config_default.php:
define("TYPO3_languages", "default|dk|de|no|it|fr|es|nl|cz|se");
(Example: To add swedish, prepend "|se" to the list in lang.php)
2) Make a copy of another language folder from "typo3/lang/" and name it like your language, eg. "se"
Start translating. But before, make sure that your new key is autorized by the development team.
More detailed explanationYou should create a file like "conf.php" found in "lang/dk/". When you open the file you'll see that it contains valuesthat override the content of the file "lang.php" in the folder "lang/". Refer to "lang.php" and substitute the valuesin "lang/dk/conf.php".
The "lang/[key]/conf.php" is only labels for the core part of Typo3. In order to translate for each module you shouldlook at the "conf.php" file of each module + all locallang*.php files.
Therefore you should also go through all folders in "typo3/mod/" + subfolders. In each you'll find a "conf.php". Thisis an example of such a file:
<? $TYPO3_MOD_PATH="mod/file/list/"; $BACK_PATH=""; $MLANG["default"]["labels"]["tablabel"] = "Listing of files in the directory"; $MLANG["default"]["tabs"]["tab"] = "List"; $MLANG["default"]["tabs_images"]["tab"] = "list.gif"; $MLANG["dk"]["labels"]["tablabel"] = "Listning af filer i kataloget"; $MLANG["dk"]["tabs"]["tab"] = "Liste"; $MCONF[script]="../../../file_list.php"; $MCONF[name]="file_list"; $MCONF[access]="group"; ?>
Inside Typo3 - 20
As you see, there is a "default"-configuration. This is always in english. But there is also the danish translation.This works in this way: If there is a danish substitute to the default value, the danish value is used instead of thedefault (if danish language is chosen that is!)
This means if you would like to translate a module, you should deliver translated values for your language - like thedanish lines!
The default language of Typo3 is english.
Please notice that the typo3/dev/translations.php is a tremendous help in translating and you should definitelyuse that to generate the translations!
If you do a translation, please submit it to the development team. Send it to [email protected]
Inside Typo3 - 21
Configuring Typo3(C1)
localconf.phpThis file defines the database name, username, password and host.
It also configures a lot of options for both frontend and backend, even modules. For a full list of options plus theirdetails see "tslib/index_ts.php" for newest front-end options and "typo3/init.php" for the newest back-end options.
This is a subtract from a standard typo3conf/localconf.php file:
// Database-variables are set$typo_db = "t31_xxxxx";$typo_db_username = "xxxxx"; // !!! ENTER USERNAME TO DATABASE HERE !!!$typo_db_password = "xxxxx"; // !!! ENTER PASSWORD TO DATABASE HERE !!!$typo_db_host = "localhost";$typo_db_extTableDef_script = "extTables.php"; // extended table-definitions
****************** TYPO3_CONF_VARS is a global array with configuration for the Typo3 libraries******************See tslib/index_ts.php for frontend specific parametersSee typo3/init.php for backend specific parametersGeneral options should appear in both scripts with same values
THESE VARIABLES MAY BE OVERRIDDEN FROM WITHIN localconf.php
- "IM" is short for "ImageMagick", which is an external image manipulation package available fromwww.imagemagick.org. Version is ABSOLUTELY preferred to be 4.2.9, but may be 5+. See the installnotes for Typo3!!- "GD" is short for "GDLib/FreeType", which are libraries that MUST be compiled into PHP4. GDLib<=1.3 supports GIF, while the latest version 1.8.x supports only PNG. GDLib is available fromwww.boutell.com/gd/. Freetype has a link from there.
Graphics
Path to the IM tools "convert", "combine", "identify". Version 4.2.9 of ImageMagick is HIGHLY recommended at thispoint, due to features and speed!
$TYPO3_CONF_VARS["GFX"]["im_path"] = "/usr/X11R6/bin/";
Path to the IM tool "convert" with LZW enabled! See "gif_compress". If your version 4.2.9 of ImageMagick iscompiled with LZW you may leave this field blank AND disable the flag "gif_compress" !
$TYPO3_CONF_VARS["GFX"]["im_path_lzw"] = "/usr/bin/";
Boolean. SET THIS if you're using IM 5+. If this is set, "im_negate_mask", "im_no_effects" and"im_mask_temp_ext_gif" is automatically configured for use with ImageMagick version 5 +
$TYPO3_CONF_VARS["GFX"]["im_version_5"] = 0;
System
Name of the base-site. This title shows up in the root of the tree-structure if you're an admin-backend user.
$TYPO3_CONF_VARS["SYS"]["sitename"] = "Typo3 Website";
Backend
Path to unzip.
Inside Typo3 - 22
$TYPO3_CONF_VARS["BE"]["unzip_path"] = "";
Path to the fileadmin dir.
$TYPO3_CONF_VARS["BE"]["fileadminDir"] = "fileadmin/";
First part of the userHomePath/groupHomePath. OBSERVE that the first part of "userHomePath" and"groupHomePath" must be the value of "lockRootPath"!. Eg. "/home/typo3/"
$TYPO3_CONF_VARS["BE"]["lockRootPath"] = "/home/typo3/";
Path to the directory where Typo3 backend-users have their home-dirs. Eg. "/home/typo3/users/". A home forbackend user 2 would be: "/home/typo3/users/2/"
$TYPO3_CONF_VARS["BE"]["userHomePath"] = "/home/typo3/users/";
Path to the directory where Typo3 backend-groups have their home-dirs. Remember that the first part of this pathmust be "lockRootPath". Eg. "/home/typo3/groups/". A home for backend group 1 would be:"/home/typo3/groups/1/"
$TYPO3_CONF_VARS["BE"]["groupHomePath"] = "/home/typo3/groups/";
Email-address that will receive a warning if there has been failed logins 4 times within an hour
$TYPO3_CONF_VARS["BE"]["warning_email_addr"] = "";
Front end
Boolean. If set, the output html-code will be passed through "tidy" which is a little program you can get fromhttp://www.w3.org/People/Raggett/tidy/. "Tidy" cleans the HTML-code for nice display! The feature does NOT workwith Windows!
$TYPO3_CONF_VARS["FE"]["tidy"] = 0;
Path where Typo3 should write webserver-style logfiles to. This path must be write-enabled for the webserver.Doesn't work for Windows! Remember slash AFTER! Eg: "fileadmin/" or "/var/typo3logs/". Please see theTypoScript reference!
$TYPO3_CONF_VARS["FE"]["logfile_dir"] = "";
If set, some HTML-comments are output in the end of the page. Can also be set by TypoScript.
$TYPO3_CONF_VARS["FE"]["debug"] = 0;
Userdefined (examples!)
pid of the page containing the etests
$TYPO3_CONF_VARS["USER"]["etest_pid"] = 20;
pid of the page containing the archive with users in folders.
$TYPO3_CONF_VARS["USER"]["userArchive_pid"] = 26;
usergroup of the testusers
$TYPO3_CONF_VARS["USER"]["test_userGroup"] = "2";
Number of days to let user live from creation (setting endtime = currenttime + 5 days)
Inside Typo3 - 23
$TYPO3_CONF_VARS["USER"]["test_userAliveDays"] = "5";
....
Configuration browser in TBEIn the module Tools>Configuration (tools_config), you can browse the $TYPO3_CONF_VARS array and its values:
Inside Typo3 - 24
tables.php
Customization: tables.php holds all customized values that makes Typo work against a given MySQL database.
This is the setup of tables and fields
Legend:R means "Required"O means "Optional"
$PAGES_TYPES
this array defines the different types of pages (the obligatory table "pages"!)
Here you can set the icons and especially you can define which tables are allowed on a certain pagetypes (doktype)
NOTE: The "default" entry in the $PAGES_TYPES-array is the "base" for all types, and for every type the entriessimply overrides the entries in the "default" type!!
Example of PAGES_TYPES from standard tables.php
$PAGES_TYPES = Array( // This array must reflect the doktype-configuration in the pages-table"2" => Array( // This points at the doktype, that this setup is good for.
"type" => "O: [web sys]: web = webpage, sys = systemfolder","icon" => "O: filename of icon from the dbicons-folder","allowedTables" => "O: commalist with tables allowed on this page doktype. * = all","onlyAllowedTables" => "O: boolean: if set then we can absolutely not shift the pagetype if records from other tables
than the allowed are present"),"default" => Array( // If no values are defined for the pageType itself then these are used.
"type" => "[*web sys]: web = webpage, sys = systemfolder","icon" => "filename of icon from the dbicons-folder","allowedTables" => "commalist with tables allowed on this page doktype. * = all","onlyAllowedTables" => "boolean: if set then we can absolutely not shift the pagetype if records from other tables
than the allowed are present")
);
type Can be "sys" or "web"icon The icon used for that valueallowedTables The tables that may reside on pages with that "doktype"onlyAllowedTables If set, the tce_main class will not allow a shift of doktype if unallowed records are on thepage.
Notice: The four options must be set for the default type while the rest can choose as they like.
$PAGES_TYPES = Array("3" => Array(
"icon" => "pages_link.gif","allowedTables" => ""
),"4" => Array(
"icon" => "pages_shortcut.gif","allowedTables" => ""
),"5" => Array(
"icon" => "pages_notinmenu.gif"),"199" => Array( // TypoScript: Limit is 200. When the doktype is 200 or above, the page WILL NOT be regarded as a
"page" by TypoScript. Rather is it a system-type page"type" => "sys","icon" => "spacer_icon.gif","allowedTables" => ""
),"254" => Array(
"type" => "sys","icon" => "sysf.gif","allowedTables" => "*"
),"255" => Array( // Typo3: Doktype 255 is a recycle-bin. Documents will be put here when deleted.
"type" => "sys","icon" => "recycler.gif","allowedTables" => "*"
),"default" => Array(
"type" => "web","icon" => "pages.gif","allowedTables" =>
"pages,tt_content,tt_links,tt_board,tt_guest,tt_address,tt_calender,tt_products,sys_template,sys_domain,sys_note",
"onlyAllowedTables" => "0")
);
Inside Typo3 - 25
$TCA:
This array defines the tables and the relationship between them and how the fields in tables are treated and so on.
tables in general:must contain "uid", "pid", ("tstamp"?)
table "pages":must ALSO contain "deleted", ("doktype"?)
Read the "Technology" document for more background information on the way Typo3 handles tables. NOTE: • You cannot use the single-quote (') in textlabels for fieldsnames (unless you escape it like this: (\')). This will
not work out when the label is transferred to JavaScript in ti_inc.php. You MAY use double-qoute (")! Labels foritem-lists may include single-quotes and they MUST NOT be escaped!!
• The (default) icon for a table is defined 1) as a giffile named "gfx/i/[tablename].gif" or 2) as the value of[table][ctrl][iconfile]
• [table][ctrl][rootLevel] goes NOT for pages. Apart from that if rootLevel is true, records can ONLY be created onrootLevel. If it's false records can ONLY be created OUTSIDE rootLevel
• You may not show the same field more than once in the editing form (types). If you do, the field will not detectthe value properly
• You should not show the same field on more than one palette! If you do, the images (required and changed)will not work in MSIE
Languages:All labels are split by "|". The order of the languages can be seen in typo3/lang/lang.php. Please read the section about translation for an description of the best way to place labels using the “locallang”concept!Example:
default | Danish | German | Norwegian | Italian | French
The word "column" and "field" means the same wherever it's used. "commalist" refers to list of values with nospaces between!
$TCA[some_tablename] = Array ("ctrl" => Array (
"label" => "R: fieldname with the label used in the recordlists in TBE",“label_alt” => “O: list of fieldnames, which are holding alternative values to the labelfield if that is empty. May
not be used consistently in the system, but should apply in most cases.”,“label_alt_force” => “O: Boolean. If set, then the label_alt fields are always shown in title separated by comma”,"tstamp" => "O: fieldname to be updated with a timestamp (UNIX-time in seconds) by each modification of the record.
(int)","crdate" => "O: fieldname to be set with a timestamp of the creating time. Is never modified again. (int)","cruser_id" => "O: fieldname to be set with the uid of the backend user (be_user) that originally created the record.
Is never modified again. (int)","type" => "O: fieldname that defines the 'recordtype'. The value of this field determines which of the 'types'
configurations are used. This value affects how records are displayed in TBE and may -depending on implementation - affect the use of the record elsewhere.",
“requestUpdate” => “O: (Commalist of fields with NO spaces between) This is a list of fields additional to the typefield which will request the user to update the form due to some content having changeand which til affect the layout. Fx. you could add any of the subtype fields you mighthave configured.“,
"sortby" => "O: fieldname used to sort the records. Be aware (!), this defines which column TCE should use to managethe specific order of eg. 'pages'-record and thus the value is altered by TCE as needed.Therefore do not list this field in the 'columns' section of the tc-array. (int)",
"default_sortby" => "O: (string): If 'sortby' is defined, this is ignored. Otherwise this is used as 'ORDER BY'statement to sort the records in the table when listed in TBE. Example: 'ORDER BYparent,crdate DESC'.",
"rootLevel" => "O: (boolean/-1): Records may only exist with pid=0 (root). The consequence is that only admin can editthis record. Actually this is the options: -1: records both root and pages, 0: recordsonly on pages, 1: records only in root. Notice that the -1 value will still selectforeign_table records for selectox boxes only from root (pid=0)",
"readOnly" => "O: (boolean): Records may not be changed. Static tables that is..., eg static_template","adminOnly" => "O: (boolean): Records may be changed ONLY by admin-users. Eg. sys_template and static_template",“is_static” => “O: (boolean): This table is static meaning that it should not be updated for individual databases
because it is meant to be centrally updated and distributed. For instance static tablescould contain country-codes used in many systems. The foremost property of a statictable is that the uid's used are the SAME across systems. Import/Export of recordsexpects static records to be common for two systems.”,
"title" => "O: System name of the table. Appears in the record-lists. Eg. 'Page content', 'Products', 'Frontendusers'. Value is language-split.",
“hideAtCopy” => “O: (boolean): If this is set then records from tables with the enablecolumns.disabled flag will bedisabled/hidden when they are copied.”,
“copyAfterDuplFields” => “O: (list of fields) The fields in this list will get the value of the 'previous' record ifthey are copied or moved after another record from same table”,
“setToDefaultOnCopy” => “O: (list of fields with NO spaces) These fields are restored to the default value of therecord when they are copied.”,
"thumbnail" => "O fieldname that holds the value for any thumbnails of the records",“selicon_field” => “O: fieldname that holds the icon image used in selectboxes wherever this table is a foreign table.
The icons must be an ordinary webformat, like gif,png,jpeg,jpg. No scaling is done.“,“selicon_field_path” => “O: The path of the value from 'selicon_field'. This is similar to (and thereby redundant) the
upload_path of that field.”,"delete" => "O: fieldname that indicates if a record is deleted or not. If the value of the field is set, then the
record is 'deleted'. If this fieldname is given, then records are not really deleted,but just marked 'deleted'",
"mainpalette" => "O: (int): Points to the palette-number that should be attached to the 'Options'-icon of the record",“canNotCollapse” => “O: boolean: If set, then the extended mode switch will not affect this table - no matter what,
all fields and palettes are displayed in the main form at all times.”,
Inside Typo3 - 26
"iconfile" => "O: (gif-filename from gfx/i/). The alternative icon to use for the template. By default the icon withgfx/i/[tablename].gif is used. If the icon specified contains a slash '/' it's expectedthat the icon is given with a path relative to typo3/ folder. You may start that pathwith '../' if you like to get your icon from a folder in the PATH_site path.",
"enablecolumns" => Array ( // In the frontend libraries the enableFields() function automatically detectswhich of these fields are configured for a table. Thus it's easy to make correct querieson records.
"fe_group" => "O: fieldname, defining fe_group of record","starttime" => "O: fieldname, defining starttime of record","endtime" => "O: fieldname, defining endtime of record","disabled" => "O: fieldname, defining hidden of record"
),"typeicon_column" => "O: fieldname, the value of which decides alternative icons for the table. Default is the
'iconfile' value. Any icon in the 'typeicons' array may override that. These options(typoicon_column and typeicons) does not work for the pages-table, which is configuredby the PAGES_TYPES array",
"typeicons" => Array ("columnvalue1" => "O: dbicon 1","columnvalue2" => "O: dbicon 2","columnvalue3" => "O: dbicon 3","columnvalue4" => "O: dbicon 4"
),“fe_cruser_id” => “O: fieldname used to store the uid of a front-end user if he created the record through
fe_adminLib”,“fe_crgroup_id” => “O: fieldname storing the uid of a fe_group record, where the members of that record are allowed to
edit through fe_adminLib”,“fe_admin_lock” => “O: fieldname: Points to the fieldname which - as a boolean - will prevent any editing by the
fe_adminLib if set. Say if the fe_cruser_id field matches the current fe_user normallythe field is editable. But with this option, you could make a check-box in the backendthat would lock this option.”,
"useColumnsForDefaultValues" => "O: (commalist of fields): When a new record is created, this defines the fields fromthe 'previous' record that should be used as default values.Eg.'doktype,fe_group,hidden'. Use by TBE.",
“dynamicConfigFile” => “O: Filename of the file in typo3conf/ which contains the full configuration of the table in$TCA. The [ctrl] part (and [feInterface] if used) are always mandatory, but the rest maybe placed in such a file. See later for details. If the filename is prepended with thestring 'T3LIB:' this indicates that it's position is in t3lib/install/”
),"interface" => Array ( // Configurations for TBE and modules there
"showRecordFieldList" => "O: (commalist of fields): Defines which field are shown in the show-item dialog. Eg.'doktype,title,alias,hidden,....'",
“always_description” => “O: boolean: If set, the description/helpicons are always shown regardless of theconfiguration of the user. Works only in TCEFORMs and for tables loaded viat3lib_BEfunc::loadSingleTableDescription()”,
"maxDBListItems" => "O: (int): Max number of items shown in the web_list module","maxSingleDBListItems" => "O: (int): Max number of items shown in the web_list module, IF only that table is listed",
),"feInterface" => Array (
"editableRecordFields" => "O: List of fields, example: '*name, *type, biography, filmography'. Used for front-end editmodule created by Rene Fritz <[email protected]>",
"fe_admin_fieldList" => "O: List of fields allowed for editing/creation with the fe_admin module, seemedia/scripts/fe_admin, example: 'pid,name,title,address'"
),"columns" => Array ( // All fields must be defined in order to appear in the TBE interface. If a fieldname does not
appear here, then that field cannot be edited."fieldname_all" => Array ( // The definitions 'label' and 'exclude' goes for all fields
"label" => "O: (string): Fieldname as it appears in the interface. Value is language-split.","exclude" => "O: (boolean): If set, this options ensures, that only usergroups with this field marked as
non_excluded can edit it.","type" => "R: (type): 'type' defines which kind the field is and thereby which options are valid"
),
// This is the various types:
"fieldname_group" => Array ( // Foreign-keys and file-upload"config" => Array (
"type" => "group","internal_type" => "R: [file db]","allowed" => "{file}___ O: (commalist): List of fileextensions that are permitted. Eg. 'jpg,gif,txt'. Also
see 'disallowed'{db}___ R: (commalist) names of SQL-tables from Typo. Value from these tables are always the
'uid' field. Eg. 'pages,be_users'. First table in list is the standard table, if atable-name is not prepended to the value. If value is '*' then all tables are allowed(IN this case you SHOULD set prepend_tname so all tables are prepended for sure).",
“disallowed” => “O: (See above). {file} Default value is '*' which means that anything file-extension which isnot allowed is denied. If you set this value (eg. 'php,php3') AND allowed is blank ''all extensions are permitted except php and php3 files. Works like the[BE][fileExtensions] config option. In other words: If you want to permit certain file-extentions only, use 'allowed' and not disallowed. If you want to permit all extensionexcept a few, set 'allowed' to blank ('') and enter the list of denied extensions in'disallowed'. If you wish to allow all extensions with no exceptions, set 'allowed' to'*' and disallowed to ''”
“MM” => “O: (tablename). If this field is set, it means that the relation to the files/db is done with a M-Mrelation with a secondary table. That table has typically four columns: uid_local,uid_foreign for uids respectively. tablenames is required if you use multitable-relations and this field must be a varchar of like 30, sorting is a required field usedfor ordering the items.If the media-type are files then the uid_foreign should be a varchar or 60 or so (forthe filename) instead of an unsigned integer as you would use for the uid. In case offiles, the tablenames field is never used.The fieldname of the config is not used for data-storage anymore but rather it's set tothe number of records in the relation on each update, so the field should be aninteger.”,
// 'file' only options:"max_size" => "O: (int): max filesize in kb","uploadfolder" => "R: Filefolder under sitePath in which the files are stored. Exg. 'uploads' or
'uploads/pictures'",// 'db' only options:
"prepend_tname" => "O: (boolean: [*false])",“dontRemapTablesOnCopy” => “O: (list of tables) This is a list of tables which should not be remapped to
the new elements if the field holds elements that are copied in the session.”,// Options for all internal-types:
"show_thumbs" => "O: (boolean): Show thumbsnails for the field","size" => "O: (int): Height of the selectorbox in TBE","multiple" => "O: (boolean [*false]): Allows the same item more than once in a list","maxitems" => "O: (int+): Maximum number of items in the selector box. Default = 1","minitems" => "O: (int+). Minimum number of items in the selector box. Default = 0"
)),
Inside Typo3 - 27
"fieldname_select" => Array ("config" => Array (
"type" => "select","items" => Array ( // -Required if not foreign_table or special. Values must not contain , and |. The special
value "--div--" is used to insert a non-selectable value that appears as a label.Array("Label (language-split)", "Value", “O: iconimage, default from t3lib/gfx/ but if prepended with
../typo3conf/ it will be taken from there (+ any subdir)”),Array("Label2 (language-split)", "Value2", “O: iconimage”),Array("Label3 (language-split)", "Value3", “O: iconimage”)
),“itemsProcFunc” => “O: Name of a PHP userfunction (void) which has an array of parameters passed to it (where
the item-array is passed by reference in the key 'items'). By modifying the array ofitems, you alter the list of items. See how user-functions are specified in the sectionabout 'wizards' some pages below here. Notice that the function is also called frommain.php (Classic Backend initialization) where NO TSconfig, $ref variable and $rowcontent is defined for the function. This is because the function is called from a'neutral' point not related to the page tree whereas in all other cases the function ISrelated to the page tree (in that there is a database row involved).”,
“selicon_cols” => "O: (int+): Enter the number of rows in which to position the iconimages for theselectorbox. Default is to render as many columns as iconimages.",
"foreign_table" => "O: (tt_*table): If this is set then the item-array is prepended with the content of thistable",
"foreign_table_where" => "O: (WHERE-clause). The items from foreign_table are selected with this WHERE-clause.The table is joined with the pages-table and items are selected only from pages wherethe user has access! Eg 'AND [foreign_table].pid=0 ORDER BY [foreign_table].sorting'.You can use markers by the way: ###REC_FIELD_[fieldname]###, ###THIS_UID###,###CURRENT_PID###, ###STORAGE_PID###, ###SITEROOT###, ###PAGE_TSCONFIG_ID###,###PAGE_TSCONFIG_IDLIST###, ###PAGE_TSCONFIG_STR###. They are active ONLY with TCEFORM(that is the Alternative Backend). ###THIS_UID### is current element uid (zero if new),###CURRENT_PID### is the current page id (pid of the record) and ###PAGE_TSCONFIG_xxx###are values you can set from Page TSconfig dynamically. The markers are preprocessed sothat the value of CURRENT_PID and PAGE_TSCONFIG_ID are always integers (default iszero), PAGE_TSCONFIG_IDLIST will always be a commalist of integers (default is zero) andPAGE_TSCONFIG_STR will be addslashes'ed before substitution (default is blank string).",
“foreign_table_prefix” => “O: This adds a prefix to the title of the records from the foreign-table. The valueis language-splitted first, so you can separate the system langauges by | as usual.”,
“foreign_table_loadIcons” => “O: Boolean. If set, then the icons for the records of the foreign table areloaded and presented in the form. This depends on the 'selicon_field' of the foreigntables [ctrl] section being configured.”,
“neg_foreign_table*” => “O: Four options corresponding to 'foreign_table' but these records will be referencedby negative id-numbers (unless if MM in which case it works like the group-type).'neg_foreign_table' is active only if 'foreign_table' is defined also.”,
“dontRemapTablesOnCopy” => “O: (See same feature for type=group, internal_type=db) Set to the exact same valueas foreign_table if you don't want values to be remapped on copy.”,
“rootLevel” => “O: (Boolean) If set, the foreign_table_where will be ignored and a 'pid=0' will be added tothe query to select records from rootlevel only.”,
“MM” => “O: (tablename). If this field is set, it means that the relation to the records is done with a M-Mrelation with a secondary table. That table has typically three columns: uid_local,uid_foreign for uids respectively. sorting is a required field used for ordering theitems.The fieldname of the config is not used for data-storage anymore but rather it's set tothe number of records in the relation on each update, so the field should be aninteger.”,
"special" => "O: [tables pagetypes exclude modListGroup modListUser]: tables: the list of tables added(excluding adminOnly tables). pagetypes: doktype-values for the pages-table added.exclude: elements from GLOBALS[exclude_fields] added. modListGroup/modListUser: module-lists added.",
"show_thumbs" => "O: (boolean): Show thumbsnails for the field (Classic TBE only)","default" => "O: defaultvalue. false = [first in items-array]","size" => "O: (int): Height of the selectorbox in TBE","multiple" => "O: (boolean [*false]): Allows the same item more than once in a list","maxitems" => "O: (int+): Maximum number of items in the selector box. Default = 1","minitems" => "O: (int+). Minimum number of items in the selector box. Default = 0"
)),"fieldname_text" => Array (
"config" => Array ("type" => "text","cols" => "O: (int): cols-attrib. in textarea-tag. Value for MSIE is calculated relative to this figure. Don't
set above 48","rows" => "O: (int): rows-attrib. in textarea-tag. Value for MSIE is calculated relative to this figure.","wrap" => "O: (string): 'virtual' is default. Blank is none. 'OFF' is used to disable wrap in fields unless
setup in the 'types'-section where 'nowrap' results in wrap=OFF. See examples intables.php",
"default" => "O: defaultvalue",“wizards” => “O: For details, see below.”
)),"fieldname_input" => Array (
"config" => Array ("type" => "input","size" => "O: (int): size-attrib. in input-tag. Value for MSIE is calculated relative to this figure. Don't
set above 48","max" => "O: (int): max-attrib. in input-tag.","default" => "O: defaultvalue","eval" => "O: (commalist of [*required unique trim date datetime time timesec year int upper lower alpha num
alphanum alphanum_x nospace md5 is_in password double2 uniqueInPid]. The eval-functionswill be executed in the list-order. 'unique' is special, because it's evaluated on theserver. 'uniqueInPid' as well (this requires the record to be unique on the page it'son)",
"checkbox" => "O: (string): If defined (even empty), a checkbox is placed before the input field. If a valueother than the value of 'checkbox' (this value) appears in the input-field the checkboxis checked.",
"range" => Array ( // Optional"upper" => "O: (int): Max value. Works only with the 'eval'-option set to 'integer' or 'date'.","lower" => "O: (int): Min value. Works only with the 'eval'-option set to 'integer' or 'date'."
),"is_in" => "O: If is_in is used for evaluation, then the chars should be in this string",“wizards” => “O: For details, see below.”
)),"fieldname_check" => Array (
"config" => Array ("type" => "check","items" => Array (// If this array is omitted, the checkbox is regarded as only one choise (on/off). Also you
should know that you can have only 10 elements in this array anyway.Array("Label1", "bit 0"),Array("Label2", "bit 1"),Array("Label3", "bit 2")
Inside Typo3 - 28
),"cols" => "O: (int): How many columns, the check-fields are divided into. Default is 1 (=0 eller 1)",“showIfRTE” => “O: (boolean): If set, this field will show ONLY if the RTE editor is enabled (which includes
correct browserversion and user-rights altogether.)”,"default" => "O: (int: [binary true/false])"
)),"fieldname_radio" => Array (
"config" => Array ("type" => "radio","items" => Array ( // -Required!
Array("Label", "Value"),Array("Label2", "Value2"),Array("Label3", "Value3")
),"default" => "O: defaultvalue. false = [first in items-array]",
)),"fieldname_none" => Array (
"config" => Array ("type" => "" // Nothing. Cannot be edited, but can be shown in TBE
))"fieldname_passthrough" => Array (
"config" => Array ("type" => "passthrough" // Can be edited, value is not evaluated, field is NOT loaded into TBE. Use
this to register fields in a table as editable by modules that does not use the dok-module to edit records.
))
),"types" => Array ( // First type is mandatory. From 0 and forth! Default is 1
"1" => Array("showitem" => "R: Configuration of the displayed order of fields in TBE. 1) Separate field-configurations with
','. 2) Every field-configuration is divided with ';'. The exploded parts represents a)(R) fieldname , b) (O) alternative fieldlabel, c) (O) palette-number, d) specialconfiguration (separated by :), eg. 'nowrap' and 'richtext[(list of keys or *), seeadmin guide, RTEkeyList for options]', e) a code for form-style, see below. A specialfieldname, '--div--', can be used to insert a divider line in the forms (only ClassicBackend, Doc-module). Another special fieldname, '--palette--', will insert a link to apalette (of course you need to specify a palette and title then...)",
“subtype_value_field” => “O: fieldname that holds a value being a key in the 'subtypes_excludelist' array. This isused to specify a secondary level of 'types' - basically hiding certain fields of thosefound in the types-configuration, based on the value of another field in the row.”,
“subtypes_excludelist” => Array (“[value]” => “[commalist of fields (from the main types-config) excluded]”
),“subtypes_addlist” => Array (
“[value]” => “[commalist of fields which is added] Notice that any transformation configuration used by TCEwill NOT work because that configuration is visible for the TCEFORMs class only duringthe drawing of fields. In other words any configuration in this list of fields will workfor display only.”
),“bitmask_value_field” => “O: fieldname that holds a value being the integer (bit-mask) for the
'bitmask_excludelist_bits' array. It works much like 'subtype_value_field' but excludesfields based on whether a bit from the value field is set or not. See'bitmask_excludelist_bits'; [+/-] indicates whether the bit [bit-number] is set ornot.”,
“bitmask_excludelist_bits” => Array (“[+/-][bit-number]” => “[commalist of fields (from the main types-config) excluded]”
)),"2" => Array (
"showitem" => "(same again, next type)")
),"palettes" => Array ( // From 1 and forth
"1" => Array("showitem" => "R: Configuration of the displayed order of fields in the palette. Remember that a fieldname must
not appear in more than one palette!. Eg. 'hidden,starttime,endtime'",“canNotCollapse” => “O: Boolean. If set, then this palette is not allowed to 'collapse' in the tceforms-display.
This basically means that if extended mode is not on, this palette is still displayed inthe main form and not linked with an icon.”
))
);
(this array is also available as a pdf-document, tc-standard.pdf, printed from a webbrowser)
Examples from standard tables.php
$TCA[pages] = Array ("ctrl" => Array (
"label" => "title","tstamp" => "tstamp","sortby" => "sorting","title" => "Page|Side|Seite|Side|Pagina|Page","type" => "doktype","delete" => "deleted","crdate" => "crdate","cruser_id" => "cruser_id","enablecolumns" => Array (
"fe_group" => "fe_group","disabled" => "hidden","starttime" => "starttime","endtime" => "endtime"
),"mainpalette" => 1,"useColumnsForDefaultValues" => "doktype,fe_group,hidden"
),"interface" => Array (
"showRecordFieldList" =>
Inside Typo3 - 29
"doktype,title,alias,hidden,starttime,endtime,fe_group,url,target,no_cache,shortcut,keywords,description,newUntil,lastUpdated,cache_timeout",
"maxDBListItems" => 30,"maxSingleDBListItems" => 50
),"columns" => Array (
"doktype" => Array ("exclude" => 1,"label" => "Type:|Type:|Typ:|Type:|Tipo:|Type:","config" => Array (
"type" => "select","items" => Array (
Array("Standard|Standard|Standard|Standard|Standard|Standard", "1"),Array("Advanced|Avanceret|Erweitert|Avansert|Avanzato|Avancé", "2"),Array("External URL|Extern URL|Externe URL|Ekstern URL|URL esterno|URL externe", "3"),Array("Shortcut|Genvej|Shortcut|Snarvei|Collegamento|Raccourci", "4"),Array("Not in menu|Ikke i menu|Nicht im Menü|Ikke I Meny|Non presente nel menu|Absent du menu", "5"),Array("-----", "--div--"),Array("Spacer|Mellemrum|Abstand|Mellomrom|Spacer|Délimiteur", "199"),Array("SysFolder|SysFolder|SysOrdner|SysMappe|Cartella di sistema|Dossier système", "254"),Array("Recycler|Papirkurv|Papierkorb|Papirkurv|Cestino|Corbeille", "255")
),"default" => "1"
)),"hidden" => Array (
"exclude" => 1,"label" => "Hide page:|Skjul side:|Seite verstecken:|Skjul side:|Nascondi pagina:|Cacher page:","config" => Array (
"type" => "check","default" => "1"
)),
.....
"keywords" => Array ("exclude" => 1,"label" => "Keywords (,):|Nøgleord (,):|Stichworte (,):|Nøkkelord (,):|Parole chiavi:|Mots-clé (,):","config" => Array (
"type" => "text","cols" => "40","rows" => "3"
)),"description" => Array (
"exclude" => 1,"label" => "Description:|Beskrivelse:|Beschreibung:|Beskrivelse:|Descrizione:|Descrition:","config" => Array (
"type" => "input","size" => "40","max" => "80","eval" => "trim"
)),"media" => Array (
"exclude" => 1,"label" => "Files:|Filer:|Dateien:|Filer:|Files:|Fichiers:","config" => Array (
"type" => "group","internal_type" => "file","allowed" => "gif,jpg,jpeg,tif,bmp,pcx,html,htm,ttf,txt,css","max_size" => "500","uploadfolder" => "uploads/media","show_thumbs" => "1","size" => "3","maxitems" => "5","minitems" => "0"
))
),"types" => Array (
"1" => Array("showitem" => "hidden, doktype;;2;button, title;;3, subtitle"),"2" => Array("showitem" => "hidden, doktype;;2;button, title;;3, subtitle, keywords, description, media"),"3" => Array("showitem" => "hidden, doktype, title;;3, url;;4"),"4" => Array("showitem" => "hidden, doktype, title;;3, shortcut"),"5" => Array("showitem" => "hidden, doktype;;2;button, title;;3, subtitle"),"199" => Array("showitem" => "hidden, doktype, title"),"254" => Array("showitem" => "hidden, doktype, title"),"255" => Array("showitem" => "hidden, doktype, title")
),"palettes" => Array (
"1" => Array("showitem" => "starttime,endtime,fe_group"),"2" => Array("showitem" => "layout, lastUpdated, newUntil, no_search"),"3" => Array("showitem" => "alias, target, no_cache, cache_timeout"),"4" => Array("showitem" => "urltype")
));
Note on files and groups
Interface: pages_45|label,pages_35|label,pages_23|label,pages_45|label,tt_images_45|label
DB: pages_45,pages_35,pages_23,pages_45,tt_images_45or: (if pages is the default table (the first table listed in the config):)46,35,23,45,tt_images_45
Interface: pages_45|label,pages_35|label,pages_23|label,pages_45|label,tt_images_45|label
Inside Typo3 - 30
-----------------Interface serverfilepath1|filename1,serverfilepath2|filename2
column: orig_filename: serverfilepath1,serverfilepath2
the file is copied from the serverfilepath to their destination catalog in the webroot. (New values are recognized bycontaining a slash - which indicates there is a path to the file...)
1: test.gif -> test.gif2: test.gif -> test_01.gif
DB: serverfilnavn1,serverfilnavn2(ex. "test.gif,test_01.gif")
Interface serverfilnavn1|orig_filename1,serverfilnavn2|orig_filename2
Loading table descriptions dynamically:
You may load table descriptions dynamically (as needed) from separate files using the functiont3lib_div::loadTCA($tablename) where $tablename is the name of the table you wish to load a completedescription of.
Dynamic tables must always be configured with a FULL [ctrl]-section (and [feInterface] section if needed). That is,it must be represented by $TCA[$table][ctrl]. If the table is dynamic, the value of [ctrl][dynamicConfigFile] pointsto an includefile with the full array in.
The loadTCA-function determines whether a table is fully loaded based on whether the [config] is an array. If it isfound to be an array the function just returns - else it loads the table if there is a value for “dynamicConfigFile”
The table “pages” must not be dynamic. All others can be in principle. You can also define more than table in adynamicConfigFile - as long as the $TCA array is correct updated with table information it doesn't matter if a filecontains configuration for more than the requested table - although the requested table should of cause always beconfigured, because it's expected to be. In fact there is not much error checking; The function loadTCA simplyincludes the file in blind faith that this action will fully configure the table in question. If that does not happ
To find places in your backend code where this should probably be implemented search for:
"each($TCA)" - This is potentially dangerous in a construction like this:
while(list($table,$config)=each($TCA))where $config would obtain non-complete content. Instead it should look like:
while(list($table)=each($TCA)) {t3lib_div::loadTCA($table);$config=$TCA[$table]...
}
\[“?(palettes|types|columns|interface)”?\] (regex) - to find places where the palettes, types, columns andinterfaces keys are used - which would require the whole array to be loaded!
It's recommended to always call the function t3lib_div::loadTCA() before using the non-[ctrl] sections of the $TCAarray. The function returns immediately if the table is already loaded, so the overhead should be small and theimportance is great.
Some benchmarks on dynamic tables:
Module tables.php with all configuration Dynamic loadingCache No cache Cache No cache
Web>List (loads all) 173 ms 322 ms 177 ms 328 ms
Web>Info (loads none) 72 ms 174 ms 66 ms 136 ms
Benchmarks on a PIII/500 MHz Linux PHP4.1.2/Apache, 256 MB RAM. PHP-Cache is PHP-accelerator. Dynamicloading is with the default loading of tbl_tt.php, tbl_users.php, tbl_sys.php and tbl_content.php. tbl_content.phpwas loaded by default all the time. All figures are parsetimes in milliseconds.
Analysis:
What we see is, that when showing a page in Web>List where all tables are loaded, the dynamic loading of tablesincludes a little overhead (177-173=4 ms) regardless of script-caching. This seems fair, probably due to fileoperations. It's also evident that the script-caching boosts the parsing considerably in both cases, savingapproximately 150 ms in parsetime!
The Web>Info module does not load any tables (at least not in the mode, this was tested). This is the whole pointof all this - that the full table definitions are loaded only if needed (as they were by the Web>List module). Againthe point of caching is clear. But the main thing to look at is, that the Web>Info module is loaded in 66/136seconds (cache/non-cache) with dynamic loading (was later tested to 60/118 ms when tt_content was not loaded
Inside Typo3 - 31
by default) which is LOWER than if the whole tables.php was included (72/174 ms).
At this point the performance gain is not significant but welcomed. However the mecanism of dynamic loading oftables provides the basis for much greater number of tables in Typo3. Testing 31 duplicates of the tt_content tableadded to the default number of configured tables (total of 62 tables configured) gave this benchmark:
Module Dynamic loadingCache No cache
Web>List (loads all) 580 ms 1090 ms
Web>Info (loads none) 67 ms 139 ms
This shows once again the work of the caching (1090-580 ms gained by PHPA) but clearly demonstrates the mainobjective of dynamic loading; The Web>Info module is not at all affected by the fact that 31 big tables has beenadded.
The serialized size of the $TCA in this case was measured to approx 2MB. The total number of KB in table-definitionPHP-files was approx. 1.7 MB.
Extreme tests of this configuration has also been done.
A duplicate of tt_content was added x number of times and yielded these results:
Number oftt_content dupl.
Serialized size of$TCA
Max size of httpdproces (from “top”)
Parsetime of theincluded documents
100 5,9 MB 23 MB 380 ms
250 14,5 MB 52 MB 12000 ms
500 28,8 MB 100 MB x
The configuration of tt_content is approx. 52 kb PHP code. The testing was done just loading the content into $TCA- no further processing. However serializing the $TCA array (when that was tested) gave a double up on theamount of memory the httpd process allocated. This was to expect of course.
From this table we learn, that PHP does not crash testing this. However it makes not much sense to use 500 tablesof this size. 250 tables might be alright and 100 tables is a more realistic roof over the number of tables in Typo3of the size of tt_content!
Conducting the same experiment with a table configuration of only 8 kb with 9 fields configured (a reducedconfiguration for the tt_content duplicate - which represents a more typical table) yielded these results:
Number oftables
Serializedsize of $TCA
Max size of httpdproces (from “top”)
Parsetime of theincluded
documents
Web>Listlisting
1 240 kB 12 MB 0 ms 174 ms (12 MB)
100 1,0 MB 12 MB 77 ms 550 ms (12 MB)
250 2,4 MB 12 MB 200 ms 1050 ms (12 MB)
500 4,7 MB 22 MB 450 ms 1900 ms (20 MB)
1000 9,3 MB 33 MB 900 ms 5000 ms (34 MB)
2000 18,6 MB 51 MB 2000 ms 18000 ms (60 MB)
Classic backend with many tables:
It's not advisable to use the classic backend with many tables. Here all table configuration is loaded into JavaScriptupon start which obviously will slow not only startup down but also slow down the browser in general because hugeamounts of memory will be needed.
A test with 31 duplicates of tt_content added to the configuration was possible, but extremely slow of course. Theprocess (MSIE 6 / WinNT) took up over 70 MB ranging to 90 MB if data was loaded into the Doc-module.
The main.php which loads all the table configuration into JavaScript took up 1,6 MB in this case. The normal sizewould be like 200 kb or so.
Inside Typo3 - 32
Rich Text Editor configuration:
The rich text editor may be configured with special options in the “types” lists. Good examples are found intt_content in tables.php.
richtext[*] = all RTE options
richtext[cut|copy|paste] = only cut, copy and paste options are shown. (See full list in adminguide!)
rte_transform[key1=value2|key2=value2|key3=value3|...]
key: flag = [fieldname] This points to a field (boolean) in the row which determines whether ornot the RTE is disabled. If the value of the field is set, then the RTE is disabled. Any transformation options willcheck this field and only proces the data if the flag is not set.
key: mode=['ts','images'] This determines the kind of processing that is done.
key: imgpath = (path relative to site root, eg. “uploads/rte_test/”) This sets an alternative path for RichText Editor images. Default is configured by the value TYPO3_CONF_VARS["BE"]["RTE_imageStorageDir"] (defaultis “uploads/”)
For more information on configuration of the RTE, see the section on the topic found in the admin-guide document.
Static-file-write configuration:
This allows to configure a field value to be written to a file. Please study how the default table in Typo3,sys_staticfile_edit is configured!
static_write[f1|f2|f3|f4|f5]
f1 is the fieldname which contains the name of the file being edited. This filename should be relative to the pathconfigured in $TYPO3_CONF_VARS[“BE”][“staticFileEditPath”].
f2 is the fieldname which will also recieve a copy of the content (in the database)
f3 is the fieldname containing the alternative subpart marker used to identify the editable section in the file. Thedefault marker is ###TYPO3_STATICFILE_EDIT### and may be encapsulated in HTML comments. There must betwo markers, one to identify the begining and one for the end of the editable section.
f4 is the fieldname which which - if true - indicates that the content should always be loaded into the form fromthe file and not from the duplicate field in the database.
f5 is the fieldname which will recieve a status message as a short textstring.
Wizards:
Wizards are configurable for “input” and “text” types. They provide a way to insert helper-elements, links to wizardscripts etc.
The value of the “wizards” key in the config-array is an array. Each key is yet an array which configures the wizardin question. The order of the keys determines the order the wizards are displayed. The key-values themselves playno important role (except from a few reserved words):
Reserved words (keys):
Key Type Description_POSITION string Determines the position of the wizard-icons/titles.
Default is “right”.
Possible values are “left”, “top”, “bottom”.
_ VERTICAL boolean If set, the wizard icons (if more than one) will be positioned in a column (vertically) and nota row (horizontally, which is default)
_ DISTANCE int+ The distance in pixels between wizard icons (if more than one).
_PADDING int+ The cellpadding of the table which keeps the wizard icons together.
_VALIGN string valign attribute in the table holding things together.
_HIDDENFIELD boolean If set, the field itself will be a hidden field (and so not visible...)
[any other key] PHP-Array Configuration of the wizard types, see below.
Wizard: script
Inside Typo3 - 33
Key Type DescriptionGeneral keys for (almost) all wizards:
type string Defines the type of wizard. The options are listed in this table.
title string, language-splitted
This is the title of the wizard. For those wizards which require a physical representation - ega link - this will be the link if no icon is presented.
icon fileref This is the icon representing the wizard.
If the first 3 chars are NOT “../” then the file is expected to be in “t3lib/gfx/”. So to insertcustom images, put them in “../typo3conf/” or so...
enableByTypeConfig
boolean If set, then the wizard is enabled only the in special configuration in the types are set to“wizards[list of wizard-keys]”.
RTEonly boolean if set, then this wizard will appear only if the wizard is presented for a RTE field.
Type: script
notNewRecords boolean If set, the link will appear ONLY if the record is not new (that is, it has a proper UID)
script PHP-script filename If the first 3 chars are NOT “../” then the file is expected to be in “typo3/”. So to link tocustom script, put it in “../typo3conf/” or so...
A lot of parameters are passed to the script as GET-vars in an array, P. Please use debug()to print out the contents of the array, so you can see, what is there.
params ?? Here you can put values which are passed to your script
popup_onlyOpenIfSelected
boolean If set, then an element (or more) from the list MUST be selected. Otherwise the popup willnot appear and you will get a message alert instead. This is supposed to be used with thewizard_edit.php script.
Type: popup (+colorbox)
notNewRecords boolean See above, type “script”
script PHP-script filename See above, type “script”
params See above, type “script”
JSopenParams string Parameters to open JS window:
Example:
"JSopenParams" =>"height=300,width=250,status=0,menubar=0,scrollbars=1",
Type: userFunc
notNewRecords boolean See above, type “script”
userFunc string Calls a function or a method in a class.
Methods: [classname]->[methodname]
Functions: [functionname]
The function/class must be included on beforehand. This is adviced to be done within thelocalconf.php file.
Two parameters are passed to the function/method: 1) An array with parameters, much likethe ones passed to scripts. One key is special though: the “item” key, which is passed byreference. So if you alter that value it is reflected BACK! 2) $this (reference to the tceform-object).
The content returned from the function call is inserted at the position where the the icon/titlewould normally go.
Type: colorbox
Renders a square box (table) with the background color set to the value of the field. The id-attribute is set to a md5-hash so youmight change the color dynamically from pop-up- wizard.
The icon is not used, but the title is given as alt-text inside the color-square.
dim W x H, pixels Determines the dimensions of the box. Default is 20 pixels.
"dim" => "50x20",
tableStyle style-attributecontent in table-tag
Sets the border style of the table, eg:
"tableStyle" => "border:solid 1px black;"
Type: select
This renders a selectorbox. When a value is selected in the box, the value is transferred to the field and the field (default) element isthereafter selected (this is a blank value and the label is the wizard title).
“select” wizards make no use of the icon.
The “select” wizard's select-properties can be manipulated with the same number of TSconfig options which are available for “real”select-types in TCEFORM.[table].[field]. The position of these properties is “TCEFORM.[table].[field].wizards.[wizard-key]”.
Inside Typo3 - 34
Key Type Descriptionmode append, prepend,
[blank]Defines how the value is processed: Either added to the front or back or (default)substitutes the existing.
items,
foreign_table_
etc...
Options related tothe selection ofelements knownfrom “select” form-element type in$TCA.
Example:
"items" => Array(Array("8 px","8"),Array("10 px","10"),Array("11 px","11"),Array("12 px","12"),Array("14 px","14"),Array("16 px","16"),Array("18 px","18"),Array("20 px","20")
)
Available wizardscripts:
There are a number of vizard scripts available in typo3/ folder:
wizard_add.php
This script links to a form which allows you to create a new record in a given table which may optionally be set asthe value on return to the real form.
Params-array:
table string Table to add record in
pid int pid of the new record.
You can use the “markers” (constants) as values instead if you wish:
###CURRENT_PID######THIS_UID######STORAGE_PID######SITEROOT###
(see TCA/select for description)
setValue “prepend”, “set”,“append”
“set” = the field will be force to have the new value on return
“append”/“prepend” = the field will have the value appended/prepended.
You must set one of these values.
Example:
"add" => Array("type" => "script","title" => "Add Author","icon" => "add.gif","params" => Array(
"table"=>"user_authors","pid" => "1","setValue" => 1
),"script" => "wizard_add.php"
),
wizard_list.php
This links to the db_list.php script for only one table and allows the user to manipulate stuff there.
Params-array:
table string Table to manage records for
pid int id of the records you wish to list.
You can use the “markers” (constants) as values instead if you wish:
###CURRENT_PID######THIS_UID######STORAGE_PID######SITEROOT###
(see TCA/select for description)
Example:
See wizard_add.php which is very alike, but remember to add the key “popup_onlyOpenIfSelected” tothe array, eg:
Inside Typo3 - 35
"edit" => Array("type" => "popup","title" => "Edit usergroup","script" => "wizard_edit.php","popup_onlyOpenIfSelected" => 1,"icon" => "edit2.gif","JSopenParams" => "height=350,width=580,status=0,menubar=0,scrollbars=1",
),
Form style:
The design of the autogenerated forms in Typo3 can be controlled down to fine detail. The fifth parameter in the$TCA/types configuration is used for this. The value consists of three pointers separated by a dash (“-”). The firstparameter points to colorscheme, the second points to stylescheme for the form elements and the third points tothe borderscheme for the table surrounding all form elements until the next border is defined.
Anyways, this is really not possible to explain without an example:
This is from the testsite's photo marathon table. The “types” configuration in $TCA looks like this:
"types" => Array ("0" => Array("showitem" => "title;;1,photodate,description,images,fe_cruser_id")
),
... and it renders this form:
Now I modify the types config to include the fifth parameters:
"types" => Array ("0" => Array("showitem" => "title;;1;;1--,photodate,description;;;;2--,images;;;;1--,fe_cruser_id")
),
This looks like:
Inside Typo3 - 36
As you see the first two main fields are green (colorscheme 1), the “Description” field yellow (colorscheme 2), andthen the last two are green (colorscheme 1 again).
Now we want to add css-styling to the form elements and also add borders to sections in the form:
"types" => Array ("0" => Array("showitem" => "title;;1;;1--0,photodate;;;;-4-,description;;;;2-0-,images;;;;1--0,fe_cruser_id")
),
And this looks like:
Here we added pointers to both styleschemes and borderschemes.
Stylescheme 4 is added to the photodate-field, but is reset to the default (0) at the description field. This gives theblue background of the “Date” field.
Inside Typo3 - 37
Borderscheme 0 (the default) is set for the title field and later it is set again for the images-field. Setting theborder-pointer to the same value again makes it “break-up” the table and apply a new “group of fields”. Settingthe first pointer to the default border scheme was actually not necessary but served to illustrate that the sameborder was applied twice.
It should also be clear now, that setting an empty pointer (blank string) will just let the former value pass through.
The default tables.php file uses these pointers by default but typically points to the same number ofcolor/style/borderscheme in each case to keep it simple. This is roughly like this configuration shows:
"types" => Array ("0" => Array("showitem" => "title;;1;;1-1-1,photodate;;;;2-2-2,description;;;;3-3-3,images,fe_cruser_id;;;;5-5-5")
),
Now you know how to connect the field-list in the types configuration with the different schemes. However we havein these examples accepted the example-scheme below as implicitly being set (in extTables.php file for example):
$TBE_STYLES = array("colorschemes" => Array (
"0" => "#F7F7F3,#E3E3DF,#EDEDE9", // Default. Always used on main-palettes in the bottom of the forms"1" => "#94A19A,#7C8D84,#7C8D84", // Typically hidden, type and other primary "meta" fields"2" => "#E4D69E,#E7DBA8,#E9DEAF", // For headers"3" => "#C2BFC0,#C7C5C5,#C7C5C5", // For main content"4" => "#B2B5C3,#C4C6D1,#D5D7DE", // For extra content, like images, files etc."5" => "#C3B2B5,#D1C4C6,#DED5D7" // For special content
),"styleschemes" => Array (
"0" => array("all"=>"background-color: #F7F7F3;border:#7C8D84 solid 1px;", "check"=>""),"1" => array("all"=>"background-color: #94A19A;border:#7C8D84 solid 1px;", "check"=>""),"2" => array("all"=>"background-color: #E4D69E;border:#7C8D84 solid 1px;", "check"=>""),"3" => array("all"=>"background-color: #C2BFC0;border:#7C8D84 solid 1px;", "check"=>""),"4" => array("all"=>"background-color: #B2B5C3;border:#7C8D84 solid 1px;", "check"=>""),"5" => array("all"=>"background-color: #C3B2B5;border:#7C8D84 solid 1px;", "check"=>""),
),"borderschemes" => Array (
"0" => array("border:solid 1px black;",5),"1" => array("border:solid 1px black;",5),"2" => array("border:solid 1px black;",5),"3" => array("border:solid 1px black;",5),"4" => array("border:solid 1px black;",5),"5" => array("border:solid 1px black;",5)
),"mainColors" => Array ( // Always use #xxxxxx color definitions!
"bgColor" => "#F7F3EF", // Light background color"bgColor2" => "#9BA1A8", // Steel-blue"bgColor3" => "#F6F2E6", // dok.color"bgColor4" => "#D9D5C9", // light tablerow background, brownish"bgColor5" => "#ABBBB4", // light tablerow background, greenish"bgColor6" => "#E7DBA8", // light tablerow background, yellowish, for section headers. Light."hoverColor" => "#254D7B" // Link hover
),// "background" => "../typo3conf/background.gif", // Background image generally in the backend// "logo" => "../typo3conf/the_logo_image.gif", // Logo in alternative backend, top left: 129x32 pixels// "logo_login" => "../typo3conf/login_logo_image.gif" // Login-logo: 333x63 pixels
Inside Typo3 - 38
);
So this leads to a formal description of the global backend array $TBE_STYLES:
$TBE_STYLES
This array can be configured in tables.php or an “extTables.php” file. This is the main keys:
$TBE_STYLES[“colorschemes”][numerical index] =
“[bgcolor general],[bgcolor of header],[bgcolor of palette header],[font color of header],[font color ofpalette header]”
- omitting a color (blank value) will use the default value (from index 0 and if index 0 is not defined, based on thegeneral mainColors in the backend)
- setting a color value to dash (“-”) will make it transparent (or just not set).
Example:
$TBE_STYLES[“colorschemes”][0]=”red,yellow,blue,olive,green”;
Not pretty, but shows the point...
$TBE_STYLES[“styleschemes”][numerical index][elementPointer] =
'value for the STYLE=”” attribute of the form element specified by elementPointer'
The elementPointer is either a pointer to the field type from $TCA...[“config”][“type”] (eg. “text”, “input”, “group”,“select”, “check”, “radio”) or it is the value “all” (which defines the default value used for all element IF not analternative is set.
Example:
$TBE_STYLES["styleschemes"][0][“all"] = "background-color:#F7F7F3;";$TBE_STYLES["styleschemes"][0][“check"] = “”;
This sets the background-color CSS attribute of all form elements except checkboxes!
$TBE_STYLES[“borderschemes”][numerical index] =
array with keys 0-2, where 0 is the table-style defining the border, 1 is an integer defining the distance inpixels after the wrapping table, and 2 a reference to a background image of the table relative to the typo3/ folder.
Example:
$TBE_STYLES["borderschemes"][0][0] = "border:solid 1px black;";$TBE_STYLES["borderschemes"][0][1] = 5;$TBE_STYLES["borderschemes"][0][2] = "../typo3conf/freestyler_transp.gif";
This renders the form fields like this:
... where there is a black border, the distance to the next section is 5 pixels and a background image.
$TBE_STYLES[“mainColors”][colorname]
Inside Typo3 - 39
This defines the general color scheme in the backend. The colorname list is bgColor, bgColor2-6, hoverColor.
IMPORTANT: All colors here should be in hexadecimal form! (That is the “#0066cc” type).
Example (the default scheme):
$TBE_STYLES["mainColors"] => Array ( // Always use #xxxxxx color definitions!"bgColor" => "#F7F3EF", // Light background color"bgColor2" => "#9BA1A8", // Steel-blue"bgColor3" => "#F6F2E6", // dok.color"bgColor4" => "#D9D5C9", // light tablerow background, brownish"bgColor5" => "#ABBBB4", // light tablerow background, greenish"bgColor6" => "#E7DBA8", // light tablerow background, yellowish, for section headers. Light."hoverColor" => "#254D7B" // Link hover
),
$TBE_STYLES[“background”] = general background image relative to typo3/ folder
$TBE_STYLES[“logo”] = Logo in alternative backend, top left: 129x32 pixels
$TBE_STYLES[“logo_login”] = Login-logo: 333x63 pixels
Extending standard tables.phpThat's easy:
1. In localconf.php, set $typo_db_extTableDef_script = "extTables.php";
2. Create "extTables.php" in "typo3conf/" and put this in:
<? $TCA[pages][columns][layout] = Array (
"exclude" => 1,"label" => "Layout:|Layout:|Layout:|Layout:|Layout:|Préparation-type:","config" => Array (
"type" => "select","items" => Array (
Array("1 spalte, baggrund 1", "0"),Array("1 spalte, baggrund 2", "1"),Array("1 spalte, baggrund 3", "2"),Array("1 spalte, baggrund 4", "3"),Array("1 spalte, baggrund 5", "4"),Array("1 spalte, baggrund 6", "5"),Array("2 spalter, baggrund 1", "6"),Array("2 spalter, baggrund 2", "7"),Array("2 spalter, baggrund 3", "8"),Array("2 spalter, baggrund 4", "9"),Array("2 spalter, baggrund 5", "10"),Array("2 spalter, baggrund 6", "11")
),"default" => "0"
));
$TCA[pages][types][1] = Array("showitem" => "hidden, doktype;;2;button, title;;3, layout, media,subtitle; Skabelon:");$TCA[pages][palettes][2] = Array("showitem" => "lastUpdated, newUntil, no_search");
?>This modifices the standard table.
If you're confused about the keys in the arrays, you may find help by using the debug() function on the array.
Field DescriptionsIf you want extra descriptions of the fields than the title provided by tables.php you can enter such descriptions -actually help-texts - in another fileset:
extTables_descr.php - is the extension filed, provided that 'extTables.php' is the file actually used. This filemust be in typo3conf/
Local language extensions:
extTables_descr.[langkey].php - is the localized version, eg. “dk” for danish. Here $TCA_DESCR_[LANGKEY] isset. Must be located in typo3conf/. You MAY add localized arrays in extTables_descr.php as well.
The database tables sys_tabledescr_[langkey] contains default values.
Inside Typo3 - 40
If a language file was included the array from it is merged upon $TCA_DESCR and returned. The array structure isgiven like this:
$TCA[tableName][columns][fieldName] = Array (“description” => “Enter the lengthy description here. All chars allowed. HTML is preserved
and may be used for simple formatting.”,“more_url” => “URL for more details.”
);
Inside Typo3 - 41
$TCA browser in TBEIn the submodule tools_config, you can browse the $TCA array and its values. This is very handy under TypoScriptdevelopment, but also if you want to check your configuration through $typo_db_extTableDef_script.
Inside Typo3 - 42
Project Code Guidelines(Section reviewed and updated 27/9 2002 by Kasper)
IntroductionThis part of the document is intended for those who are interested in helping with the Typo3 project byprogramming libraries or modifications. You should also follow these guidelines for your extensions programmed forTypo3.
FilesThe Typo3 code-library consists of these folders:
typo3src_[xxx]/
tslib/ - class-files and scripts for the TypoScript based frontend of Typo3. (TSFE)
media/ - media like image-bullets and masks, but most importantly the scripts-folder. Howeverthe use of the media/ folder is slowing being depreciated as extensions should hold all material in the future.
t3lib/ - class-files for both the front-end and backend (TBE).
t3lib/stddb/
tables.php/tbl_be.php - the tables.php file for the core
tables.sql - The standard database tables for Typo3 core
typo3/ - the default Typo3 backend interface (TBE)
t3lib -> softlink to ../t3lib
gfx -> softlink to t3lib/gfx/
misc/ - history of Typo3 releases. Contains e.g. upgrade information from version to version
No filename may be longer than 31 characters. Keep them in lowercase as much as possible.
ClassesOne class in each class-file
A classfile is named:
class.[classname].php
classname corresponds to the name of the class in the file, but in lowercase.
classnames are on the form:
[library]_[nameInStudlyCaps]
library is currently either "tslib" (TypoScript library) or "t3lib" (Typo3 library - general + backend). If it's anextension the class is always prefixed “tx_” and then the extension key (with underscores removed) and possiblysome prefix. Classes prefixed “ux_” is reserved for being extension classes to existing classes.
studlyCaps means that you separate words with uppercase letters, first word lowercase, like "studlyCaps"
(Remember, function and classnames are case-INsensitive in PHP)
Prefer:
class tslib_makeInterestingOutput {....
}Avoid:
class Im_doing_whateverIWant{
....}
Exceptions:
Inside Typo3 - 43
The class tslib_content.php contains the classes tslib_cObj, tslib_frameset, tslib_tableOffset, tslib_controlTable.
The class tslib_menu.php contains the classes tslib_menu, tslib_tmenu, tslib_gmenu, tslib_imgmenu,tslib_jsmenu
These two class-files differ from the rest, because they include more than one class. Why is that? Because thealternative is to split them up in 9 include-files which depend on each other anyway. So for the sake of efficiencythese are still kept together. But the general rule is "one class per class-file":
Finally all class files should be ended with a few codelines checking for and possibly including an extending-classfile. Please see the section about extending classes for details.
Instantiating a class - or retrieving a classname to instantiate if you need to pass variables to the constructor -should ALWAYS be done by t3lib_div::makeInstance() as that function will check for the existence of an extensionclass first.
FunctionsThere should be practically no functions in Typo3. Only classes.
Function should be put into a class and used with the :: -syntax
Examples of this is a class like t3lib_div. Check that out and see how the functions herein is used from otherclasses.
Example of how this works:
class tslib_makeInterestingOutput {function getName () {
return “Kasper”;}
}
echo “My name is “.tslib_makeInterestingOutput::getName();
Why?
To keep the function and class-namespaces well-defined and structured and compatible with other libraries. Allclasses are systematically named with prefixes tslib_ or t3lib_ and putting functions into the classes helps keepingthe namespace clean and easy to overview.
There are a few exceptions:
Common functions
debug() - prints an array in a table for debugging purposes.
defined in t3lib/config_default.php
Please notice that this function has REMOTE_ADDR dependant output. It willoutput content only if your IP address as client matches a certain list found inTYPO3_CONF_VARS[SYS][devIPmask]
TypoScript Front End, TSFE (tslib/)
(none)
TBE (Typo3 default Backend)
(none)
Special care about file-functions, is_file, is_dir, is_writeable, file_exists!These functions may result in a warning like “Warning: stat failed in line ...” if they are used on a file path whichdoes not exist. This behavious is detected for PHP 4.0.7+ and ironically these functions are in fact used to detectwhether or not a certain path is valid! The solution is to prepend the function call with @, so with these functions,please prepend the function name like this example: @is_file(), @is_dir(), @file_exists(), etc.
Headers and footersAlways use “<?php” as opening tags (not only “<?”).
Every file should contain a header with a copyright notice. Just copy a header from one of the other files.
Remember to put your own name in as copyright holder if you write something from scratch.
The importance of the header is primarily to state that the code is GNU/GPL'ed. And remember only GPL'edsoftware is allowed to interface with Typo3 (according to GPL itself).
Inside Typo3 - 44
This is an example. Notice that the standard header is followed by a file-comment in Javadoc style.
<?php/**************************************************************** Copyright notice* * (c) 1999-2002 Kasper Skårhøj ([email protected])* All rights reserved** This script is part of the Typo3 project. The Typo3 project is * free software; you can redistribute it and/or modify* it under the terms of the GNU General Public License as published by* the Free Software Foundation; either version 2 of the License, or* (at your option) any later version.* * The GNU General Public License can be found at* http://www.gnu.org/copyleft/gpl.html.* A copy is found in the textfile GPL.txt and important notices to the license * from the author is found in LICENSE.txt distributed with these scripts.** * This script is distributed in the hope that it will be useful,* but WITHOUT ANY WARRANTY; without even the implied warranty of* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the* GNU General Public License for more details.** This copyright notice MUST APPEAR in all copies of the script!***************************************************************//** * This class holds some functions used by the Typo3 backend * * Some scripts that use this class: admin_integrity.php * Depends on: Depends on loaddbgroup from t3lib/ * * @author Kasper Skårhøj <[email protected]> */
There are no requirements for a footer.
FormattingLines are of arbitrary length. No limitations to 80 chars or such.
Lines end with a chr(10) - UNIX style.
Indentation is done with TAB's - and NOT spaces!
Functions / braces:
Prefer:
function makeMyDay ($punk) {return “Do you feel lucky? Well, do you... punk!”;
}
Avoid:
function makeMyDay ($punk){return “Do you feel lucky? Well, do you... punk!”;}
Control structues:
Prefer:
if ($someStuff) {echo “Hello world”;
}Avoid:
if ($someStuff)echo “Hello world”;
Inside Typo3 - 45
DocumentationPlease always include a little description of your function before it, like:
/** * Returns the $integer if greater than zero, otherwise returns zero. */function intval_positive($theInt) {
$theInt = intval($theInt);if ($theInt<0){$theInt=0;}return $theInt;
}
We are generally in favour of a comment more than in favour of total adherance to the JavaDoc style which we areformally trying to follow. It's more important you get something written than not!
A really good habit is to always include the 3 comment lines before a function, even if you write no comment! Itjust adds to the beauty of the document!
Follows the Javadoc style. For general description of this, refer to
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
This is some snippets from this website:
General Form of a Doc CommentA doc comment is made up of two parts -- a description followed by zero or more tags, with a blankline (containing a single asterisk "*") between these two sections: /** * This is the description part of a doc comment * * @tag Comment for the tag */
The first line is indented to line up with the code below the comment, and starts with the begin-comment symbol (/**) followed by a return.
Subsequent lines start with an asterisk *. They are indented an additional space so the asterisksline up. A space separates the asterisk from the descriptive text or tag that follows it.
Insert a blank comment line between the description and the list of tags, as shown.
Insert additional blank lines to create "blocks" of related tags (discussed in greater detailbelow).
The last line begins with the end-comment symbol (*/) indented so the asterisks line up and followedby a return. Note that the end-comment symbol contains only a single asterisk (*). Break any doc-comment lines exceeding 80 characters in length, if possible. If you have more thanone paragraph in the doc comment, separate the paragraphs with a <p> paragraph tag. Also seeTroubleshooting Curly Quotes (Microsoft Word) at the end of this document.
Tags:
* @author (classes and interfaces only, required)* @version (classes and interfaces only, required) (see footnote 1)* * @param (methods and constructors only)* @return (methods only)* @exception (@throws is a synonym added in Javadoc 1.2)* @see * @since * @serial (or @serialField or @serialData)* @deprecated (see How and When To Deprecate APIs)
Required TagsAn @param tag is required for every parameter, even when the description is obvious. The @return tagis required for every method that returns something other than void, even if it is redundant withthe method description. (Whenever possible, find something non-redundant (ideally, more specific) touse for the tag comment.)
The way we do it in PHP-files differ a little bit, so in general do like you see in the documents.
The Javadoc style comments are supposed to be parsed by the script found at:
Inside Typo3 - 46
http://www.phpdoc.de/
Naming conventionsFor classes see above. Variables in classes, studlyCaps is preferred.
For functions in classes, use studlyCaps as far as possible. But if you use underlining to delineate the words, that'sok too. Variables internally in function, do what you like. Still, use meaningfull names.
Most importantly use meaningful names for the functions that convey an idea of what they do and return.
See http://www.zend.com/zend/art/mistake1.php#Heading3 for good guidelines
Database tables: Keep it lowercase! On Windows tablenames are case-insensitive as opposed to UNIX.
New project-specific tables and project specific fields in existing standard tables should be prepended “user_”. Butplease consider making your stuff as extensions and if you do so, please see the extension API for guidelines onnaming there!
Guide to tablenames: Tables prepended “sys_” are not meant to be directly displayed on webpages as content,rather they are stuff like logging-data or relations. “cache_” is tables which may be totally deleted at any time,because they contain cached information that will be regenerated if it does not exist. “tt_” is a prefix indicatingthat the table holds records meant for direct display on the pages. Tables/Fields prefixed “tx_” are certainlybelonging to an extension.
Global variablesGlobal vars should be named in uppercase
Do NOT expect in your scripts that input from outside is found in the global vars. It's recommended to use thephp.ini-optimized with Typo3 and that means that the content of HTTP_POST/GET_VARS is NOT transferred to theglobal name-space.
By calling the function t3lib_div::GPvar(“[varname]”) you'll get the value of varname from the global GET/POSTarrays with priority to POST (that is, if a value is send with POST, that's the one returned). This function removesslashes if needed.
Example:
Prefer:
$myName = t3lib_div::GPvar(“myname”);or
$myName = $GLOBALS[“HTTP_POST_VARS”][“myname”];
Avoid:
$myName = $GLOBALS[“myname”];
Common global vars
(typ. defined in t3lib/config_default.php)
EXEC_TIME is set so that the rest of the script has a common value for the script executiontime
SIM_EXEC_TIME is set to $EXEC_TIME but can be altered later in the script if we want tosimulate another execution-time when selecting from eg. a database
TYPO_VERSION Typo3 version
TCA
LANG_GENERAL_LABELS
PAGES_TYPES
Typo3 table configuration.
$LANG_GENERAL_LABELS and $PAGES_TYPES are set if TSFE->includeTCAincludes the $TCA array.
Inside Typo3 - 47
TYPO3_CONF_VARS Typo3 configuration
Keys:
GFX: Configuration of the image processing features in Typo3!!
SYS: System related.
EXT: Extension related
BE: Backend
FE: Frontend
MODS: Backend, modules (depreciated because of extensions/EXT[extConf])
USER: Frontend, userdefined (depreciated because ofextensions/EXT[extConf])
TYPO3_LOADED_EXT Array with loaded extensions. You can check if an extension is loaded by thefunction t3lib_extMgm::isLoaded($key) where $key is the extension key of themodule.
BE_USER Backend user object
CLIENT Client information array: “BROWSER” = msie,net,opera or blank, “VERSION” =browser version as double, “SYSTEM” = win,mac,unix
(system) Don't use any system-global vars, except these:
HTTP_GET_VARS, HTTP_POST_VARS, HTTP_SERVER_VARS,HTTP_COOKIE_VARS.
Any other variables may not be accessible if php.ini-optimized is used!
IMPORTANT: Official System/PHP Variables you can use
It is a nightmare to deliver a set of system variables which will be the same onall systems. Therefore Typo3 features an “abstraction method”,t3lib_div::getIndpEnv(), which should be used to get any system value.Please see description in table below here.
TCA_DESCR
LANG
LOCAL_LANG
These are loaded if the admin-panel edit feature is enabled and forms aredisplayed on the website.
TypoScript Front End (tslib/)
TSFE TypoScript Front End base-object
Herein:
->cObj
TT TimeTracking
TYPO3_MISC Various variables, eg. some global parsetime tracking.
TBE (Typo3 default Backend)
(From typo3/init.php) $WEBMOUNTS: Array of uid's to be mounted in the page-tree
$FILEMOUNTS: Array of filepaths on the server to be mountet in the directorytree
$FILEICONS: Assoc. array; keys are the type (eg. "tif") and values are thefilename (without path)
$PARSETIME_START: Time in milliseconds right after inclusion of theconfiguration.
Variables which are registered asglobals in the end oftypo3/init.php
$AB: This flag indicates that the page/module is called from the AlternativeBackend. The flag should be passed on by the modules themselves IF theyrequire to know whether they are running in the Alternative Backend or not.For instance the file- and database list modules need to know because theyinitialize JavaScript in the top-frame - JavaScript which does not exist if theAlternative Backend is loaded!
Inside Typo3 - 48
t3lib/install/tables.php $PAGES_TYPES
$ICON_TYPES
$LANG_GENERAL_LABELS
$TBE_MODULES
$TBE_MODULES_EXT
$TBE_STYLES
$TCA
backend modules $MLANG: Contains a limited amount of language labels: THe title of themodule.
$MCONF: Contains a few module-cofiguration informations like the name,access and which script to use.
$BACK_PATH: Tells the back “back” to the main directory. Used primarily forimages and other media
$LOCAL_LANG: Stores language specific labels and messages.
Template class $LANG: Object used to generate language specific labels
$TBE_TEMPLATE: Object used to print the “document” design in the backend
$TBE_iGraphics: Object used to generate the graphical tabs, clickmenus andbuttons
ConstantsConstants are either defined in t3lib/config_default.php, typo3/init.php (backend) or tslib/index_ts.php (frontend).The constant TYPO3_MOD_PATH is also defined in module configuration files.
Constants normally define paths and database information. These values are global and cannot be changed whenthey are first defined. This is why constants are used for such vital information.
Note on paths in Typo3 (UNIX / WINDOWS):
In the frontend paths are normally relative, in backend absolute. Absolute paths are necessary in the backend inorder to support softlinking of the backend code (Unix).
All paths are using single forward slashes (mydir/myfile.php - right!) opposed to backslashes (mydir\\myfile.php -WRONG!).
All absolute paths should begin with either “/” or “x:/”, eg. “/mydir/myfile.php” (unix) or “C:/mydir/myfile.php”(windows). Please use the function t3lib_div::isAbsPath($path) to check absolute paths. This function will returntrue if absolute.
Common
TYPO3_db Name of database, eg “t31_testsite”. Must be defined after inclusion of theconfiguration scripts.
TYPO3_db_username Username for database
TYPO3_db_password Password for database
TYPO3_db_host Host for database, eg. “localhost”
TYPO3_tables_script By default t3lib/install/tables.php is included as the main table definition file.Alternatively this constant can be set to the filename of an alternativetables.php file. Must be located in typo3conf/
TYPO3_extTableDef_script Name of a php-include script found in typo3conf/ that contains php-code thatmodifies the content of the standard file, tables.php
TYPO3_languages Defines the system languages in Typo3.
TYPO3_OS Operating systen; Windows = “WIN”, other = “”
TYPO3_MODE Mode of Typo3: Set to either “FE” or “BE” depending on frontend or backendexecution.
PATH_thisScript Filename to current script.
PATH_t3lib Path to t3lib/.
PATH_typo3conf Path to typo3conf/ dir. Must be defined for t3lib/config_default.php to return.
PATH_site Absolute path to the site (the folder right before the typo3/ folder)
TypoScript Front End (tslib/)
Inside Typo3 - 49
PATH_tslib Path to tslib/
TBE (Typo3 default Backend)
TYPO3_mainDir This is the directory of the backend administration for the sites of this Typo3installation. Hardcoded to “typo3/”
TYPO3_MOD_PATH Path to module relative to PATH_typo3 (as defined in the moduleconfiguration)
PATH_typo3 Absolute path to the typo3 folder
PATH_typo3_mod Relative path to a properly configured module! (seen from the PATH_typo3).Based on TYPO3_MOD_PATH.
PATH_temp Path to temporary folder used for gifs and stuff in the interface
Typical parameters pass by the urlThese are values normally passed by GET-method. This list is the result of a search for the functiont3lib_div::GPvar() in the front-end scripts. If this function is consistently used to fetch the values from GET orPOST data, then this list will be easy to keep updated.
The list gives you an idea, which var-names are already used. Many of them apply only to pages incorporating ashopping basket, message-board, frontend admin or search-dialog. But at all times you cannot use the four vars,id, type, no_cache, jumpurl and recs! Remember that!
TypoScript Front End (tslib/)
TSFE (!) regular: id, type, no_cache, jumpurl, cHash, ftu, MP,RDCT
session data: recs[]
mid,rid: jumpurl/directmailer
TSFE_ADMIN_PANEL[]: Used by the admin panel in the bottom of pages.
TSFE_EDIT[]: Used by the front end editor
media/scripts/fe_admin key,fetch,fD,cmd, FE (array),aC,rU,backURL,preview,doNotSave
media/scripts/board notify_me, tt_board_uid
media/scripts/products General: update_code, tracking, orderRecord, update_code, begin_at,swords, backPID, products_*
DIBS: transact,orderid,authkey,reason,products_cmd
tslib_cObj swords,stype,spointer,scount,sword_list[]
Extensions Are required to submit variables in an array named “tx_[extkey]”[key1][key2]etc.
TBE (Typo3 default Backend)
(yet to come...)
Extensions See TSFE section above.
System/PHP Variables - the nightmareIn any case you want to use any of the system variables below, please DO NOT use getenv(), preferably notHTTP_SERVER_VARS either, but call the API function t3lib_div::getIndpEnv().
Follow these guidelines:
• Never use getenv()
• Always use the t3lib_div::getIndpEnv() function if you can. You can depend on those values, that they will workon any platform Typo3 supports.
• If you really need a variable from HTTP_SERVER_VARS for some reason, you can most like to so. You may thenhelp us testing the availability of this variable on a variety of systems and suggest to include it as a key int3lib_div::getIndpEnv().
The whole point of this is to have an “abstraction method” for returning these values regardless of Typo3 runningon a UNIX or WINDOWS server, Apache or ISS, CGI or module. Some of these variables are different from systemto system, some does not even exist on some servers, some are swapped around depending on SAPI-type and thestory goes on. The declared target of this function, t3lib_div::getIndpEnv(), is to deliver a system independantvalue which you can always trust to be correct. It's its not, we are going to fix it.
Many, many reported bugs in Typo3 has been due to these variables returning different values. People have thentried to fix it and found a fix which works on their system, but which would break another system. Therefore this
Inside Typo3 - 50
function is really necessary.
If you need a system variable which is not listed below, please investigate the cross-platform/cross-webserveravailability and suggest an addition.
Please see the documentation inside the t3lib_div::getIndpEnv() function for the most up-to-date information.
t3lib_div::getIndpEnv()
First some definition of terms:
output from parse_url():URL: http://username:[email protected]:8080/typo3/32/temp/phpcheck/index.php/arg1/arg2/arg3/?arg1,arg2,arg3&p1=parameter1&p2[key]=value#link1 [scheme] => 'http' [user] => 'username' [pass] => 'password' [host] => '192.168.1.4'
[port] => '8080' [path] => '/typo3/32/temp/phpcheck/index.php/arg1/arg2/arg3/' [query] => 'arg1,arg2,arg3&p1=parameter1&p2[key]=value' [fragment] => 'link1'
Further definition: [path_script] = '/typo3/32/temp/phpcheck/index.php'[path_dir] = '/typo3/32/temp/phpcheck/'[path_info] = '/arg1/arg2/arg3/'[path] = [path_script/path_dir][path_info]
URI:
SCRIPT_NAME [path_script]++ = /typo3/32/temp/phpcheck/index.php
NOTICE THAT SCRIPT_NAME will return the php-script name ALSO.[path_script] may not do that (eg. "/somedir/" may result in SCRIPT_NAME"/somedir/index.php")!
PATH_INFO [path_info] = /arg1/arg2/arg3/
(Does not work with CGI-versions AFAIK)
HTTP_HOST [host][:[port]] = 192.168.1.4:8080
REQUEST_URI [path]?[query] =/typo3/32/temp/phpcheck/index.php/arg1/arg2/arg3/?arg1,arg2,arg3&p1=parameter1&p2[key]=value
Suggestion. This is very usefull to make self-referencing URLs or “returnUrl”'sin scripts! Eg in a parameter string:
returnUrl=".rawurlencode(t3lib_div::getIndpEnv("REQUEST_URI"))
QUERY_STRING [query] = arg1,arg2,arg3&p1=parameter1&p2[key]=value
HTTP_REFERER [scheme]://[host][:[port]][path] =http://192.168.1.4:8080/typo3/32/temp/phpcheck/index.php/arg1/arg2/arg3/?arg1,arg2,arg3&p1=parameter1&p2[key]=value
CLIENT:
REMOTE_ADDR (client IP)
REMOTE_HOST (client host)
HTTP_USER_AGENT (client user agent)
HTTP_ACCEPT_LANGUAGE (client accept language)
SERVER:
SCRIPT_FILENAME Absolute filename of script (Differs between windows/unix). Onwindows "C:\\blabla\\blabl\\" will be converted to "C:/blabla/blabl/"
DOCUMENT_ROOT Absolute path of root of documents: DOCUMENT_ROOT.SCRIPT_NAME =SCRIPT_FILENAME
Special Typo3 extras:
TYPO3_HOST_ONLY [host] = 192.168.1.4
TYPO3_PORT [port] = 8080 (blank if 80, taken from host value)
TYPO3_REQUEST_URL [scheme]://[host][:[port]][path]?[query] (sheme will by default be "http"until we can detect if it's https -
TYPO3_REQUEST_SCRIPT [scheme]://[host][:[port]][path_script]
TYPO3_REQUEST_DIR [scheme]://[host][:[port]][path_dir]
TYPO3_SITE_URL [scheme]://[host][:[port]][path_dir] of the Typo3 website
Inside Typo3 - 51
Remember this!General PHP
• Always check by is_array() and reset() an array before introducing it in a while(list()=each()) loop
• In comparing strings, use strcmp() (returns false if strings matches!) OR prefix supposed string variables with'(string)'. Reason: Consider this: $id==”my_string”. This will return true if 1) $id is a string, “my_string” OR if 2) $id isan integer of zero in which case “my_string” is converted to an integer - which will be zero! So instead do oneof these: '(string)$id==”my_string”' or '!strcmp($id,”my_string”)'. The same with switch-constructs:'switch((string)$id) {....'
Typo3 Specific
• Always call t3lib_div::loadTCA($tablename) before you use any other parts of the $TCA array than the [ctrl]-section (loads the table should it happen to be dynamicly configured.
• Always get system/PHP variables (such as REQUEST_URI or REMOTE_ADDR or SCRIPT_FILENAME) byt3lib_div::getIndpEnv(). Avoid getenv(). See table above.
• Always make a new object instance using t3lib_div::makeInstance($className)
• Always format content for a <TEXTAREA>-field with t3lib_div::formatForTextarea()
• Backend: Try to use the functions $TBE_TEMPLATE->formWidth() [input fields] and $TBE_TEMPLATE->formWidthText() [textarea] to get the proper cols/rows/size/style attributes for fields. This not only secures ahomogenous display across browsers, but it also makes sure that wrapping/no-wrapping will occur correctlyacross browsers as well! (which is really a plague to make happen correctly...)
• Using GD functions imageTTFBBox and imageTTFtext you should pass the font-size parameter throught3lib_div::freetypeDpiComp() - this will compensate the size if FreeType2 is used (and configured for inTYPO3_CONF_VARS)
• Don't expect 'index.php' to be a default document; Always link to “../index.php?param=...” instead of“../?param=...” (which may not work for some configurations)
• http/https handling: When detecting absolute urls either use parse_url() and look for the “scheme” key in thearray or make a 'substr($str,0,4)==”http”' - dont test for 'http://' unless you are certain you want to fail“https://” connections!If you need to know the current scheme, subtract if from TYPO3_REQUEST_HOST or another var fromt3lib_div::getIndpEnv()If you need to prefix a scheme to an “un-schemed” url (eg. 'www.typo3.com') use “http://” (this is the mostcommon anyways).
Cross platform issues (Windows/Unix)
• Paths in Typo3 are always with forward single slashes like this:
Relative (win/unix) path/to/a/file.phpAbsolute (unix) /my/path/to/a/file.php Absolute (win) C:/my/path/to/a/file.php
(Exceptions include paths to external programs like ImageMagick (single-backslash) and uploaded fileswhich comes with single-backslash and should NOT be changed before processing. But all internal filesshould follow the scheme above)
• Check absolute paths with t3lib_div::isAbsPath($path) - this will test both Unix (“/”) and Windows (“x:/”)absolute paths.
• If you (for some reason) need to convert a windows path with backslashes (sometimes double-backslashes)you can pass it to t3lib_div::fixWindowsFilePath() which will return it with single forward slashes. Thefunction does not harm paths without backslashes, so you can use it in general.
• Don't use the “:” (colon) as a explode-token if there is any chance a component might be a path - in thatcase it breaks on windows!
• Uploading filesUploading files may be tricky for some reasons: On Windows the paths are WITH backslashes (not forwardslashes) and those must not be converted before processing. And then in safe_mode you MUST usemove_uploaded_file() to move it from the temp-dir. Read these notes for how to deal with this:
• Note that uploaded files on windows comes in the HTTP_POST_FILES array with backslashes! You shouldNOT convert this path, but let the system handle the file with the name given in HTTP_POST_FILES.However if you need to evaluate the path (eg. check for “/” slash in it...) use t3lib_div::fixWindowsFilePath()(see above. Searching for places where such a check is done may be successfull with this regex:strstr[[:space:]]*\([^,]*,"\/"\))
Inside Typo3 - 52
• If you pass an uploaded file as a resource to tcemain-class you should pass the original path fromHTTP_POST_FILES of course. But it's VERY important (for windows paths with backslashes) that thehandling of slashes is correct. You may need to set '->stripslashes_values=0;' so that tcemain does not stripthe backslashes of the filenames if you call tcemain directly from your scripts! But then all ordinary datamust also be without slashes. Alternatively you should pass the resource-list through addslashes() functionbefore passing on to tcemain.
• For copying/moving (possibly uploaded) files, you should uset3lib_div::upload_copy_move($source,$destination). This will check if the file is uploaded and if so, use themove_uploaded_file() function (works with open_base_dir/safe_mode). Otherwise it's copied plainly withthe copy() function.
• Header(“Location: ”):(Find occurencies by 'header[[:space:]]*\(["']location:' regex)
On Windows (or maybe CGI-versions in general?) it has been discovered that a header-location send to a scriptin another directory of the server does NOT inform the webbrowser about the new location. For instance if wesend a 'header(“Location: /typo3/mod/my_module/index.php”)' from the '/typo3/alt_doc.php' then the script'/typo3/mod/my_module/index.php' is correctly informed about URL etc. but the browser is not! So if you try tomake a relative reference, say, back to the alt_doc.php script like '../../alt_doc.php' it will fail, because thewebbrowser still thinks we are at the location '/typo3/'. The solution is to prefix all header-location URLS with “http://”. This may even be a requirement in the RFC - Idon't know. But anyways, that should make it work across servers/browsers.
• Always send URLS for Header(“Location: ”) through this function, t3lib_div::locationHeaderUrl($url). Thiswill prefix “http://” if needed. $url's with “/” as first character (relative to host) and $url's with no scheme(that is no “http://” part, regarded relative to current directory) will be prefixed accordingly to becomeabsolute URL's.Apparently header-locations to scripts in the same folder is not affected by this behaviour (because they arein the same path...) but although you may not see the immediate impact (because the script is in the samedir or more likely you are on UNIX servers) you should use the function as a rule of thumb. That is thecurrent policy.
php.ini-optimized:When you write your code, conform to the php.ini-optimized settings!
Notice that Typo3 currently converts the HTTP_POST_VARS and HTTP_GET_VARS arrays to being escaped (orslasheds if you like) if magic_quotes_gpc is “off”. So no matter what you do, expect these arrays to be slashed.
; - allow_call_time_pass_reference = Off; It's not possible to decide to force a variable to be passed by reference; when calling a function. The PHP 4 style to do this is by making the; function require the relevant argument by reference.; - register_globals = Off; Global variables are no longer registered for input data (POST, GET, cookies,; environment and other server variables). Instead of using $foo, you must use; $HTTP_POST_VARS["foo"], $HTTP_GET_VARS["foo"], $HTTP_COOKIE_VARS["foo"],; $HTTP_ENV_VARS["foo"] or $HTTP_SERVER_VARS["foo"], depending on which kind; of input source you're expecting 'foo' to come from.; - register_argc_argv = Off; Disables registration of the somewhat redundant $argv and $argc global; variables.; - magic_quotes_gpc = Off; Input data is no longer escaped with slashes so that it can be sent into; SQL databases without further manipulation. Instead, you should use the; function addslashes() on each input element you wish to send to a database.; - variables_order = "GPCS"; The environment variables are not hashed into the $HTTP_ENV_VARS[]. To access; environment variables, you can use getenv() instead.
Inside Typo3 - 53
Extending the system classesPractically all important scripts has their main code encapsulated in a class (typically named SC_[scriptname] andinstantiated as the global object $SOBE) and all classes used in Typo3 - both frontend and backend - can beextended by userdefined classes. This concept is a PHP-style way of extending the system. You can use it either forsingle projects or as a great way to experiment with new development, which later may go into the maindistribution. This is mostly for professionals.
Configuring user-classes works like this:
1. In localconf.php you configure for either frontend or backend that you wish to include a file with the extensionof the class. This inclusion is usually done in the end of the class-file itself based on a lookup inTYPO3_CONF_VARS.
2. Whenever the class is instantiated as an object, the sourcecode checks if a user-extension of that class exists. Ifso, then that class is instatiated and not the “normal” (parent) class.
Example:
Say you wish to make an addition to the stdWrap method found in the class “tslib_cObj” (found in the class filetslib/class.tslib_content.php).
The first thing to do is to create the extension class. So you create a file in the typo3conf/ directory named“class.ux_tslib_content.php”. “ux” is a prefix meaning “user-extension”. This file may look like this:
<?php/** * User-Extension of tslib_cObj class.** @author Kasper Skårhøj <[email protected]>*/
class ux_tslib_cObj extends tslib_cObj { function stdWrap($content,$conf) { // Call the real stdWrap function in the parent class: $content = parent::stdWrap($content,$conf); // Process according to my user-defined property: if ($conf["userDefined_wrapInRed"]) { $content='<font color=red>'.$content.'</font>'; } return $content; }}
?>
(Note: Performanceloss by passing content through the extension method of stdWrap above has measure to be 16ms for 640 method-calls on a PIII/500 MhZ. So for each method call that is 0,025 ms. Nothing to worry about...)
The next thing is to configure Typo3 to include this class file as well after the original filetslib/class.tslib_content.php:
$TYPO3_CONF_VARS["FE"]["XCLASS"]["tslib/class.tslib_content.php"]= PATH_typo3conf."class.ux_tslib_content.php";
So when the file “tslib/class.tslib_content.php” is included inside of class.tslib_pagegen.php, the extension class isincluded immediately from inside the “tslib/class.tslib_content.php” file (this is from the bottom of the file):
if (defined("TYPO3_MODE") && $TYPO3_CONF_VARS[TYPO3_MODE]["XCLASS"]["tslib/class.tslib_content.php"]) {
include_once($TYPO3_CONF_VARS[TYPO3_MODE]["XCLASS"]["tslib/class.tslib_content.php"]);}
The last thing which remains is to instantiate the class ux_tslib_cObj instead of tslib_cObj. This is done totallyautomatically, because everywhere tslib_cObj is instantiated, it is first examined if ux_tslib_cObj exists and if so,that class is instantiated instead!
This looks like this for instance:
$cObj =class_exists("ux_tslib_cObj")?new ux_tslib_cObj:new tslib_cObj;
Originally it looked like this:
$cObj = new tslib_cObj;
Inside Typo3 - 54
IMPORTANT:
When setting up the file to include, in particular from t3lib/, notice the difference between$TYPO3_CONF_VARS["BE"]["XCLASS"][...] and $TYPO3_CONF_VARS["FE"]["XCLASS"][...]. The key “FE” is usedwhen the class is included by a front-end script (those initialized by tslib/index_ts.php and tslib/showpic.php -both also known as index.php and showpic.php in the root of the website), “BE” is used by backend scripts (thoseinitialized by typo3/init.php or typo3/thumbs.php). This feature allows you to include a different extension whenthe (t3lib/-) class is used in the frontend and in the backend.
Which classes?
As said; Any class! All non-obsolete code in Typo3 resides in classes and therefore anything in the system can beextended. So you should rather say to yourself: In which script (and thereby which class) is it that I'm going toextend/change something. When you know which script, you simply open it, look inside and somewhere you'll findthe lines of code which are responsible for the inclusion of the extension.
Example; Say you wish to add a little section with help text in the bottom of the “New” dialog:
So this is what you do:
1. Find out that the script in question is “typo3/db_new.php” (rightclick frame, select “properties” and look aturl...:-)
2. Then examine the scripts for it's classes and methods in those classes. In this case you'll find two classes in thefile; “localPageTree” (extends t3lib_pageTree) and “SC_db_new”. The class “SC_db_new” is the socalled “scriptclass” - this will hold the code specifically for this script. Because you are curious, you also find that the only code executed in the global scope is this:
$SOBE = t3lib_div::makeInstance("SC_db_new");$SOBE->init();$SOBE->main();$SOBE->printContent();
3. When you examine the SC_db_new class you find that the main() method is the one you would like to extend.
4. Finally you find that immediately after the definition of the two classes there is three lines of code which willprovide you with the final piece of knowledge you need:
// Include extension?if (defined("TYPO3_MODE") && $TYPO3_CONF_VARS[TYPO3_MODE]["XCLASS"]["typo3/db_new.php"]) { include_once($TYPO3_CONF_VARS[TYPO3_MODE]["XCLASS"]["typo3/db_new.php"]);}
So now you know that the key to use is “typo3/db_new.php” when you wish to define a script which should beincluded as the extension.
So now after your investigations you do the trivial stuff:
1. Create your extension class (here typo3conf/class.test.php)
<?php
class ux_SC_db_new extends SC_db_new { function main() { global $doc; parent::main(); $this->content.=$doc->section("HELP","- make a choice!",0,1); }}
?>
2. Configure your extension class in typo3conf/localconf.php
Inside Typo3 - 55
$TYPO3_CONF_VARS["BE"]["XCLASS"]["typo3/db_new.php"] = PATH_typo3conf."class.test.php";
There is no “table of extendable classes” in this document because 1) all classes are extendable and 2) the numberof classes will grow as Typo3 is further developed and 3) finally you cannot extend a class unless you know it existsand have analyzed some of it's internal structure (methods / variables) - so you'll have to dig into the sourceanyways!
Therefore; If you wish to extend something, follow this suggestion for an analysis of the situation and you'll end upwith the knowledge needed in order to extend that class and thereby extend Typo3 without loosing backwardscompatibility with future updates. Great.
Notes on SC_* classes (script classes)
There is one more thing to note about especially the SC_* classes in the backend:
1. Global vars: They use a lot of variables from the global scope. This is due to historical reasons; The codeformerly resided in the global scope and a quick conversion into classes demanded this approach. Future policyis to keep as many variables internal as possible and if any of these SC_* classes are developed further in thefuture, some of the globals might on that occasion be internalized.
2. Large methods: There are typically a init(), main() and printContent() method in the SC-classes. Each ofthese, in particular the main() method may grow large. Processing stuff in the start and end of the methods iseasy - you just call parent::[methodname]() from your extension. But if you want to extend or processsomething in the middle of one of these methods, it would be necessary to call a dummy method at that pointin the parent class. Such a dummy method would then be used for processing in your class, but would notaffect the general use of the parent class. Such dummy-method calls are not widely included yet, but will be assuggestions for them appears. And you are very welcome to give in such suggestions.
I'll just give an example to illustrate what I mean:
class SC_example { function main() { $number = 100; echo "The number is ".$number; }}
This class prints the text “The number is 100”. If you wish to do some calculations to the $number-variablebefore it is printed, you are forced to simply include the whole original main-method in your extension script.Here it would be no problem because the method is 2 codelines long. But it could be 200 codelines! So whatyou do is that you suggest to the Typo3 development to call a “harmless” dummy method in the main()method...
class SC_example { function main() { $number = 100; $number = $this->processNumber($number); echo "The number is ".$number; } function processNumber($theNumber) { return $theNumber; }}
... and then you extend the class as follows:
class ux_SC_example extends SC_example { function processNumber($theNumber) { return $theNumber<100 ? "less than 100" : "greater than 100"; }}
... and now the main() method would print “The number is greater than 100” instead.
Notice that you'll have to make such suggestions for dummy method calls because we will include them only aspeople need them. Suggestions go to [email protected]
Extending methods
When extending a method like in the case above with stdWrap() please observe that such a method might gainnew parameters in the future without further notice. For instance stdWrap is currently defined like this:
function stdWrap($content,$conf) {
... but maybe some day this method will have another parameter added, eg:
function stdWrap($content,$conf,$yet_a_parameter=0) {
This means if you want to override stdWrap(), but still call the parent class' method, you must extend your own
Inside Typo3 - 56
method call from...:
function stdWrap($content,$conf) { // Call the real stdWrap method in the parent class: $content = parent::stdWrap($content,$conf);
...... to:
function stdWrap($content,$conf,$yet_a_parameter=0) { // Call the real stdWrap method in the parent class: $content = parent::stdWrap($content,$conf,$yet_a_parameter);
...
Also be aware of constuctors. If you have a constructor in your extension class you must observe if there is aconstructor in the parent class which you should call first / after. In case, you can do it by “parent::[original classname]”
For instance the class tslib_fe is instantiated into the global object $TSFE. This class has a constructor looking likethis:
/** * Class constructor */function tslib_fe($TYPO3_CONF_VARS, $id, $type, $no_cache="", $cHash="", $jumpurl="") { // Setting some variables: $this->id = $id; $this->type = $type; $this->no_cache = $no_cache ? 1 : 0; $this->cHash = $cHash; $this->jumpurl = $jumpurl; $this->TYPO3_CONF_VARS = $TYPO3_CONF_VARS; $this->clientInfo = t3lib_div::clientInfo(); $this->uniqueString=md5(microtime()); $this->makeCacheHash();}
So as you see, you probably want to call this method. But lets also say you wish to make sure the $no_cacheparameter is always set to 1 (for some strange reason...). So you make an extension class like this with a newconstructor, ux_tslib_fe(), overriding the $no_cache variable and then calling the parent class constructor:
class ux_tslib_fe extends tslib_fe { function ux_tslib_fe($TYPO3_CONF_VARS, $id, $type, $no_cache="", $cHash="", $jumpurl=""){ $no_cache=1; parent::tslib_fe($TYPO3_CONF_VARS, $id, $type, $no_cache, $cHash, $jumpurl); }}
User defined methods in classes:
Prefix user defined methods and internal variables with “ux_”! Thus you don't risk to choose a method name whichmay later be added to the parent class in the Typo3 distribution!
Example, continued from above:
class ux_tslib_fe extends tslib_fe { var $ux_fLPmode = 1; // If you "feelLuckyPunk" this is the no_cache value function ux_tslib_fe($TYPO3_CONF_VARS, $id, $type, $no_cache="", $cHash="", $jumpurl=""){ // setting no_cache? $no_cache=$this->ux_settingNoCache(); // Calling parent constructor: parent::tslib_fe($TYPO3_CONF_VARS, $id, $type, $no_cache, $cHash, $jumpurl); } /** * Setting the no_cache value based on user-input in GET/POST var, feelLuckyPunk */ function ux_settingNoCache() { return t3lib_div::GPvar("feelLuckyPunk") ? $this->ux_fLPmode : 0; }}
(Userdefined methods and variables are in purple)
Example: How to extend the message-board class?
Say you wish to extend the default plugin, user_board (media/scripts/boardLib.inc). What you do is:
1. Create a file in typo3conf/ which you might call “class.ux_myBoardExtension.php”
2. Insert this line in localconf.php:$TYPO3_CONF_VARS["FE"]["XCLASS"]["media/scripts/boardLib.inc"]=PATH_typo3conf."class.ux_temp.php";
Inside Typo3 - 57
- scripts/boardLib.inc is the key from the table above. This tells the boardLib.php file to include your ext.- PATH_typo3conf is a Typo3 configured constant which holds the absolute path to the typo3conf/ dir.
3. Hit it!
The file content of “class.ux_myBoardExtension.php” could be like this:
<?php
class ux_user_board extends user_board { function forum_postform($theCode) { $content = parent::forum_postform($theCode); $content = eregi_replace( '<INPUT', '<INPUT style="background-color:yellow;"', $content ); return $content; }}
?>
This will make the background color of the posting form fields yellow in a very quick-n-dirty way! Of course youcould also choose to render the form totally as you like instead of basing the output on the content from the parentmethod.
You could also allow the background color to be set through the TypoScript which controls the message board ingeneral:
<?php
class ux_user_board extends user_board { function forum_postform($theCode) { $content = parent::forum_postform($theCode); if ($this->conf["ux_myFormColor"]) { $content = eregi_replace( '<INPUT', '<INPUT style="background-color:'.$this->conf["ux_myFormColor"].';"', $content ); } return $content; }}
?>
In this example the TypoScript property “.ux_myFormColor” will control the color so from TypoScript you wouldnow be able to set the color like this:
plugin.tt_board_tree.ux_myFormColor = yellow
(The prefix “ux_” is chosen to make sure the property is not used by some later general addition.)
A few examples of extending the backend classes
The concept of extending classes in the backend can come in handy in many cases. First of all it's a brilliant way tomake your own extensions to Typo3 without spoiling the compatibility with the distribution! This is a very, veryimportant point! Stated another way: By making an extension class you can change one method in a Typo3 classand next time you update Typo3, your method is still there - but all the other Typo3 code has been updated! Great!
Also for development and experimental situations is great. Generally the concept offers you quite a lot of freedom,because you are seriously able to take action if you need something solved here and now which cannot be fixed inthe main distribution at the moment.
Anyways, here's a few simple examples:
1) Say you wish to have the backend user time out after 30 seconds instead of the default 6000.
1. In localconf.php, insert: $TYPO3_CONF_VARS["BE"]["XCLASS"]["t3lib/class.t3lib_beuserauth.php"] =PATH_typo3conf."class.ux_myBackendUserExtension.php";
2. Create the file “class.ux_myBackendUserExtension.php” in typo3conf/ folder and put this content in:
<?php
class ux_t3lib_beUserAuth extends t3lib_beUserAuth { var $auth_timeout_field = 30;}
Inside Typo3 - 58
regular methods and a lot of global-scape code around. However as it becomes necessary such things can easily beput into classes which will follow the same style of extension as these examples. Thus it might often be a questionof “cleaning up the sourcecode” by putting it into a class without really changing any thing functionally - but theadvantage gained is that those methods are now extendable for any project you might wish to extend them for!
Inside Typo3 - 60
Typo3 Extension APIIntroductionTypo3 can be extended in nearly any direction without loosing backwards compatibility. The Extension API providesa powerful framework for easily adding, removing, installing and developing such extensions to Typo3. This is inparticular powered by the Extension Manager (EM) inside Typo3.
“Extensions” is a term in Typo3 which covers two other terms, plugins and modules.
A plugin is something that plays a role on the website itself. Eg. a board, guestbook, shop etc. It is normallyenclosed in a PHP class and invoked through a USER or USER_INT cObject from TypoScript. A plugin is anextension in the frontend.
A module is a backend application which has it's own position in the administration menu. It requires backendlogin and works inside the framework of the backend. We might also call something a module if it exploits anyconnectivity of an existing module, that is if it simply adds itself to the function menu of existing modules. Amodule is an extension in the backend.
Files and locations
Files
An extension consists of 1) standard files for configuration related to Typo3 (of which some are optional) and 2)any number of additional files for the extension itself.
Standard files:
• ext_emconf.php: Not required, but if this file is not present the EM will not find the extension.Definition of extension properties: Name, category, status etc. Used by the EM. Also auto-written by EM whenextensions are imported from repository.
• ext_localconf.php: Extension to “localconf.php”. Not required, but included if found. May contain configuration of $TYPO3_CONF_VARS. All 'ext_localconf.php' files of included extensions are included right after the typo3conf/localconf.php file hasbeen included and database constants defined. Therefore you cannot setup database name, username,password though, because database constants are defined already at this point. Notice: Observe rules for content of these files. See section on caching below.
• ext_tables.php: Extension to “tables.php”. Not required, but included if found. May contain configuration of tables, modules, backend styles etc. Everything which can be done in the an“extTables” file is allowed here. Same thing.All 'ext_tables.php' files of loaded extensions are included right after the 'tables.php' file in the order they aredefined in the global array TYPO3_LOADED_EXT but right before a general “extTables” file (defined with the var$typo_db_extTableDef_script in the typo3conf/localconf.php file, later set as the constantTYPO3_extTableDef_script). Thus a general “extTables” file in typo3conf/ may overrule any settings made byloaded extensions.Notice: Observe rules for content of these files. See section below.
• ext_tables.sql: Definition of database tables. Not required.This file should contain a table-structure dump of the tables used by the extension. It is used for evaluation ofthe database structure and is therefore important to check and update the database when an extension isenabled.If you add additional fields (or depend on certain fields) to existing tables you can also put them here. In thatcase insert a CREATE TABLE structure for that table, but remove all lines except the ones defining the fields youneed. The ext_tables.sql file may not necessarily be “dumpable” directly to MySQL (because of the semi-completetable definitions allowed defining only required fields, see above). But the EM or Install Tool can handle this.The only very important thing is that the syntax of the content is exactly like MySQL made it so that the parsingand analysis of the file is done correctly by the EM.
• ext_tables_static+adt.sql: Any static tables and their data. Not required.If the extension requires static data you can dump it into a sql-file by this name.Example for dumping mysql data from telnet (being in the extension directory):
mysqldump --password=[password] [database name] [tablename] --add-drop-table > ./ext_tables_static.sql
--add-drop-table will make sure to include a DROP TABLE statement so any data is inserted in a fresh table.
• ext_typoscript_constants.txt: Preset TypoScript constants. Not required.Such a file will be included in the constants section of all TypoScript templates.
Inside Typo3 - 61
• ext_typoscript_setup.txt: Preset TypoScript setup. Not required.Such a file will be included in the setup section of all TypoScript templates.
• ext_typoscript_editorcfg.txt: Preset TypoScript editor configuration. Not required.Such a file will be included in the “Backend Editor Configuration” section of all TypoScript templates.
• ext_conf_template.txt: TypoScript setting up a series of values which can be configured for the extension inthe EM. Not required.If this file is present the EM provides you with a interface for editing the configuration values defined in the file.The result is written as a serialized array to localconf.php file in the variable$TYPO3_CONF_VARS["EXT"]["extConf"][extension_key]
• ext_icon.gif: 18x16 gif icon for the extension.
• (*/) locallang[*].php: Not required.The filename locallang.php (or any file matching locallang*.php) is used for traditional definition of languagelabels in the $LOCAL_LANG array. If you use this name consistently those files will be detected by thetranslation tool!
PLEASE DO ONLY put the definition of the variable $LOCAL_LANG into this file and don't rely on comments inthe file. The file will be automatically updated by the extension repository when translations are applied.
• pi/: Not required.Typical folder for a frontend plugin class.
• mod/: Not required.Typical folder for a backend module.
• res/: Not required.Extensions normally consist of other files: Classes, images, html-files etc. Files not related to either a frontendplugin (pi/) or backend module (mod/) might be put in a subfolder of the extension directory named “res/” (for“resources”) but you can do it as you like (inside of the extension directory that is). The “res/” folder content will be listed as files you can select in the configuration interface.
Locations of system, global and local extensions
The files for an extension are located in a folder named by the extension key. The location of this folder can beeither inside typo3/sysext/, typo3/ext/ or typo3conf/ext/. The extension must be programmed so that itdoes automatically detect where it is located and can work from all three locations.
• Local location “typo3conf/ext/”: This is where to put extensions which are local for a particular Typo3installation. The typo3conf/ dir is always local, containing local configuration (eg. localconf.php), localmodules etc. If you put an extension here it will be available for this Typo3 installation only. This is a “per-database” way to install an extension.
• Global location “typo3/ext/”: This is where to put extensions which are global for the Typo3 source codeon the web server. These extensions will be available for any Typo3 installation sharing the source code.When you upgrade your Typo3 source code you probably want to copy the typo3/ext/ directory from theformer source to the new source, overriding the default directory. In this way all global extension you usewill be installed inside the new sourcecode. After that you can always enter Typo3 and upgrade the versionsif needed. This is a “per-server” way to install an extension.
• System location “typo3/sysext/”: This is system default extensions which cannot and should not beupdated by the EM.
Loading precedence
Local extensions take precedence which means that if an extension exists both in typo3conf/ext/ and typo3/ext/the one in typo3conf/ext/ is loaded. Likewise global extension takes predence over system extensions. This meansthat extensions are loaded in the order of priority local-global-system.
In effect you can therefore have - say - a “stable” version of an extension installed in the global dir (typo3/ext/)which is used by all your projects on a server sharing source code, but on a single experimental project you canimport the same extension in a newer “experimental” version and for that particular project the locally availableextension will be used instead.
Extension key
The “extension key” is a string uniquely identifying the extension. The folder where the extension resides is namedby this string. The string can contain characters a-z0-9 and underscore. No uppercase characters should be used(keeps folder-,file- and table/field-names in lowercase). Furthermore the name must not start with an “tx” or “u”(this is prefixes used for modules) and because backend modules related to the extension should be named by theextension name without underscores, the extension name must still be unique even if underscores are removed(underscores are allowed to make the extension key easierly readable).
The naming convensions of extension keys are automatically validated by the registration at the repository, so youhave nothing to worry about here.
There are two ways to name an extension:
Inside Typo3 - 62
• Project specific extensions (not generally usable or shareable): Select any name you like and prepend it“user_” (which is the only allowed use of a key starting with “u”). This prefix denotes that this extension is alocal one which does not come from the central Typo3 Extension Repository or is ever intended to be shared.Probably this is an “adhoc” extension you have made for some special occasion.
• General extensions: Register an extension name online at the Typo3 Extension Repository. Your extensionname will automatically be validated and you are sure to have a unique name returned which nobody else in theworld uses. This makes it very easy to share your extension later on with every one else, because it ensuresthat no conflicts with other extension will happend. But by default a new extension you make is defined“private” which means nobody else but you has access to it until you permit it to be public. It's free of charge to register an extension name. By definition all code in the Typo3 Extension Repository iscovered by GPL because it interfaces with Typo3. You should really consider making general extensions!
Suggestion: It is far the easiest to settle for the right extension key from the beginning. Changing it later involvesa cascade of name changes to tables, modules, configuration files etc.
About GPL and extensions: Remember that Typo3 is GPL software and at the same moment you extend Typo3your extensions are legally covered by GPL. This does not force you to share your extension, but it should inspireyou to do so and legally you cannot prevent anyone who gets hold of your extension code from using it and furtherdevelop it. The Typo3 Extension API is designed to make sharing of your work easy as well as using others work easy.Remember Typo3 is Open Source Software and we rely on each other in the community to develop it further.
Naming convensions
Based on the extension key of an extension these naming convensions should be followed:
General Example User specific ExampleExtension key
(Lowercase “alnum”+ underscores. )
Assigned by the Typo3Extension Repository.
cool_shop Determined byyourself, but prefixed“user_”
user_my_shop
Database tables andfields
Prefix with “tx_[key]_”where key is withoutunderscores!
Prefix: tx_coolshop_
Examples:
tx_coolshop_products
tx_coolshop_categories
Prefix with “[key]_” Prefix: user_my_shop_
Examples:
user_my_shop_products
user_my_shop_categories
Backend module
(Names are alwayswithoutunderscores!)
Name: The extension keyname without underscores,prefixed “tx”
txcoolshop Name: Nounderscores, prefixed“u”
uMyShop or umyshop or ...
Frontend PHP classes (Same as database tables and fields. Prepend class file names “class.” though.)
Note on “old” and default extensions:
Some the default and “classic” extensions from before this new structure does not comply with these namingconvensions. That is not changed but accepted as it is for backwards compatibility. The assignment of new keysfrom the Typo3 Extension Repository will make sure that any of these old names are not accidentially reassigned tonew extensions.
Further some of the classic plugins (tt_board, tt_guest etc) users the “user_” prefix for their classes as well.
Import and install of extensions
There are only two (maybe three) simple steps involved in using extensions with Typo3:
1. You must import it. This simple means to copy the extensions files into the correct directory in either typo3/ext/ (global) ortypo3conf/ext/ (local). More commonly you import an extension directly from the online Typo3 ExtensionRepository. When an extension is found located in one of the extension locations, it is available to the system. The EM can take care of this process, including updates to newer versions if needed.
2. You must install it.And extension is loaded only if it's extension key is listed in comma list of the variableTYPO3_CONF_VARS["EXT"]["extList"]. The list of enabled extensions must be set and modified from insidetypo3conf/localconf.php. Extensions are loaded in the order they appear in this list. Any extensions listed inTYPO3_CONF_VARS["EXT"]["requiredExt"] will be forcibly loaded before any extensions inTYPO3_CONF_VARS["EXT"]["extList"].An enabled extension is always global to the Typo3 Installation - you cannot disable an extension from beingloaded in a particular branch of the page tree.The EM takes care enabling extensions. It's highly recommended that the EM is doing this, because the EM willmake sure the priorities, dependencies and conflicts are managed according to the extension characteristics,including clearing of the cache-files if any.
3. You might be able to configure it.
Inside Typo3 - 63
Certain extensions may allow you to configure some settings. Again the EM is able to handle the configurationof the extensions based on a certain API for this. Any settings - if present - configured for an extension isavailable as an array in the variable $TYPO3_CONF_VARS["EXT"]["extConf"][extension key].
Loaded extensions are registered in a global variable, $TYPO3_LOADED_EXT, available in both frontend andbackend of Typo3. The loading and registration process happens in t3lib/config_default.php.
This is how the datastructure for an extension in this array looks:
$TYPO3_LOADED_EXT[extension key] = Array (“type” => S, G, L for system, global or local type of availability.“siteRelPath” => Path of extension dir relative to the PATH_site constant
eg. “typo3/ext/my_ext/” or “typo3conf/ext/my_ext/”“typo3RelPath” => Path of extension dir relative to the “typo3/” admin folder
eg. “ext/my_ext/” or “../typo3conf/ext/my_ext/”“ext_localconf” => Contains absolute path to 'ext_localconf.php' file if present“ext_tables” => [same]“ext_tables_sql” => [same]“ext_tables_static+adt.sql” => [same]“ext_typoscript_constants.txt” => [same]“ext_typoscript_setup.txt” => [same]“ext_typoscript_editorcfg.txt” => [same]
)
The order of the registered extensions in this array corresponds to the order they were listed inTYPO3_CONF_VARS["EXT"]["requiredExt"].TYPO3_CONF_VARS["EXT"]["extList"] with duplicates removed ofcourse.
The inclusion of ext_tables.php or ext_localconf.php files are done by traversing (a copy of) the$TYPO3_LOADED_EXT array.
ext_tables.php and ext_localconf.php
These two files are the most important for the execution of extensions to Typo3. They contain configuration usedwithin the system on almost every request. Therefore they should be optimized for speed.
• ext_localconf.php is always included in global scope of the script, either frontend or backend. You can put functions and classes into the script, but you should consider doing that in other ways becausesuch classes and functions would always be available - and it would be better if they were included only whenneeded.So stick to change values in TYPO3_CONF_VARS only!
• ext_tables.php is not always included in global scope on the other hand. Don't put functions and classes - or include other files which does - into this script!
• Use the API of the class extMgm for various manipulative tasks such as adding tables, merging information intoarrays etc.
• Before the inclusion of any of the two files, the variables $_EXTKEY is set to the extention-key name of themodule and $_EXTCONF is set to the configuration from $TYPO3_CONF_VARS["EXT”]["extConf"][extension key]
• $TYPO3_LOADED_EXT[extension key] contains information about whether the module is loaded as local, globalog system type, including the proper paths you might use, absolute and relative.
• The inclusion can happen in two ways:
1. Either the files are included individually on each request (many file includes)($TYPO3_CONF_VARS["EXT”]["extCache"]=0;)
2. or (better) the files are automatically imploded into one single temporary file (cached) in typo3conf/directory (only one file include) ($TYPO3_CONF_VARS["EXT”]["extCache"]=1; [or 2])
In effect this means:
• Your ext_tables.php / ext_localconf.php file must be designed so that it can safely be read and subsequentlyimploded into one single file with all the other configuration scripts!
• You must NEVER use a “return” statement in the files global scope - that would make the cached scriptconcept break.
• You should NOT rely on the PHP constant __FILE__ for detection of include path of the script - theconfiguration might be executed from a cached script and therefore such information should be derived fromthe $TYPO3_LOADED_EXT[extension key] array. Eg. $TYPO3_LOADED_EXT[$_EXTKEY][“siteRelPath”]
ext_emconf.php
This script configures the extension manager. The only thing included is an array, $EM_CONF[extension_key] withthese associative keys (below in table).
When extensions are imported from the online repository this file is auto-written! So don't put any custom stuff inthere - only change values in the $EM_CONF array if needed.
Inside Typo3 - 64
Key Data type Descriptiontitle string, required,
language-splittedThe name of the extension. Not unique.
In English please!
description string, required,language-splitted
Short and precise description of what the module does and for whom it might be useful.
In English please!
category string Which category the extension belongs to:
be Backend (Generally backend oriented, but not a module) module Backend modules (When something is a module or connects with one)fe Frontend (Generally frontend oriented, but not a “true” plugin)plugin Frontend plugins (Plugins inserted as a “Insert Plugin” content element) misc Miscellaneous stuff (Where not easily placed elsewhere)example Example extension (Which serves as examples etc.)
shy boolean If set, the extension will normally be hidden in the EM because it might be a defaultextension or otherwise something which is not so important. Use this flag if an extension isof “rare interest” (which is not the same as un-important - just an extension not sought forvery often...)
It does not affect whether or not it's enabled. Only display in EM.
Normally “shy” is set for all extensions loaded by default according to TYPO3_CONF_VARS.
dependencies list of extention-keys
This is a list of other extension keys which this extension depends on being loaded BEFOREit self. The EM will manage that dependency while writing the extension list to localconf.php
conflicts list of extention-keys
List of extension keys of extensions with which this extension does not work (and socannot be enabled before those other extensions are un-installed)
priority “top”, “bottom” This tells the EM to try to put the extensions as the very first in the list. Default is last.
module list of strings If any subfolders to an extension contains backend modules, those foldernames should belisted here. It allows the EM to know about the existence of the module, which is importantbecause the EM has to update the conf.php file of the module in order to set the correctTYPO3_MOD_PATH constant.
state string Which state is the extension in?
alpha: Very initial development. May do nothing at all. beta: Under current development. Should work partly but is not finished yet.stable: Stable and used in production.experimental: Nobody knows if this is going anywhere yet... Maybe still just an idea.test: Test extension, demonstrates concepts etc.
internal boolean This flag indicates that the core source code is specifically aware of the extension. In orderwords this flag should convey the message that “this extension could not be writtenindependantly of core source code modifications”.
An extension is not internal just because it uses Typo3 general classes eg. those fromt3lib/.
True non-internal extensions are characterized by the fact that they could be writtenwithout making core source code changes, but relies only on existing classes in Typo3and/or other extensions, plus its own scripts in the extension folder.
lockType char; L, G or S Locks the extension to be installed in a specific position of the three posible: L = local(typo3conf/ext/), G = global (typo3/ext/) and S = system (typo3/sysext/)
clearCacheOnLoad
boolean If set, the EM will request the cache to be cleared when this extension is loaded.
author string Author name
author_email email address Author email address
author_company string Author company (if any company sponsors the plugin).
modify_tables list of tables List of tablenames which are only modified - not fully created - by this extension. Tablesfrom this list found in the ext_tables.sql file of the extension
uploadfolder boolean If set, then the folder named “uploads/tx_[extKey-with-no-underscore]” should be present!
private boolean If set, this version of the extension is not included in the public list!
download_password
string If set, this password must additionally be specified if people want to access (import or seedetails for) this the extension.
version main.sub.dev Version of the extension.
Extending “extensions-classes”
A rather exotic thing to do but nevertheless...
If you are programming extensions yourself you should as a standard procedure include the “class extension code”in the bottom of the class file:
if (defined("TYPO3_MODE") && $TYPO3_CONF_VARS[TYPO3_MODE]["XCLASS"]["ext/class.cool_shop.php"])
Inside Typo3 - 65
{include_once($TYPO3_CONF_VARS[TYPO3_MODE]["XCLASS"]["ext/class.cool_shop.php"]);
}
Normally the key use as example here, ' ext/class.cool_shop.php ' would be the full path to the script relative tothe PATH_site constant. However because modules are required to work from both typo3/sysext/, typo3/ext/ andtypo3conf/ext/ it is policy that any path before “ext/” is omitted.
Background: What extensions are going to do for Typo3:
• Extensions are going to be the way Typo3 grows.
• All new future development by Kasper (main programmer) will be done as extensions. This means that whatcannot currently be done as an extension will be possible by extending the API of the core system.
• Any other developer has a nothing less than a perfect framework for making contributions.
• The Extension Manager combined with the online repository and connected to workgroup communicationfeatures on typo3.org will allow a totally smooth process to multiple developers on either private or publicdevelopment!
• Extensions are the true “Get rich quick” scheme; In three minutes you have a unique extension key plus ablank framework with classes, module folders etc all in place for production of customer applications. You aredone in no time, no TypoScript hassles with imlementing your user-defined stuff. Sound PHP-coding in classesfrom minute one.
• Extensions are CVS on speed for Typo3; In a single click with the mouse users can upgrade their localextensions source code to the latest version from the repository! If you cannot do this, you couldn't even be atruckdriver for a living.
• Extensions provide you with a great concept for transfer of code from your development server to removeservers with two clicks with a mouse: [Upload extension to repository] - click.... [Import extensions fromrepository] - click...
Inside Typo3 - 66
Indexed searchingThe principleIn Typo3 there's a built-in indexing mechanism that indexes the pages on-the-fly (internal extensionindexed_search).
You have several features:
• HTML data priority: 1) <title>-data 2) <meta-keywords>, 3) <meta-description>, 4) <body>
• Indexing external files: Text formats like html and txt and doc, pdf by external programs (catdoc / pdftotext)
• Wordcounting and frequency used to rate results
• exact, partially or metaphone search
• searching freely for sentences (non-indexed).
• NOT case-sensitive in any ways though.
HTML contentHTML content is prioritized as stated above. In addition you can insert markers as HTML comments which definewhich part of the body-text to include or exclude in the indexing:
The marker is <!--TYPO3SEARCH_begin--> or <!--TYPO3SEARCH_end-->
Rules:
1. If there is no marker at all, everything is included.
2. If the first found marker is an “end” marker, the previous content until that point is included and thepreceeding code until next “begin” marker is excluded.
3. If the first found marker is a “begin” marker, the previous content until that point is excluded and preceedingcontent until next “end” marker is included.
Use of hashesThe hashes used are md5 hashes where the first 7 chars are converted into an integer which is used as the hash inthe database. This is done in order to save space in the database, thus using only 4 bytes and not a varchar of 32bytes. It's estimated that a hash of 7 chars (32) is sufficient (originally 8, but at some point PHP changedbehaviour with hexdec-function so that where originally a 32 bit value was input half the values would be negative,they were suddently positive all of them. That would require a similar change of the fields in the database. To cut itsimple, the length was reduced to 7, all being positive then).
How pages are indexedFirst of all a page must be cachable. For pages where the cache is disabled, no indexing will occur.
The “phash” is a unique identification of a “page” with regard to the indexer. So an entry in the index_phash tableequals 1 resultrow in the search-results.
A phash is a combination of the page-id, type, sys_language id, gr_list and the cHash parameters of the page(function setT3Hashes()). If the phash is made for EXTERNAL media (item_type > 0) then it's a combination of theabsolute filename hashes with any “subpage” indication, for instance if a PDF-document is splitted intosubsections.
So for external media there is one phash-row for each file (except PDF-files where there may be more). But forTypo3-pages there can be more phash-rows matching one single page. Obviously the type-parameter wouldnormally always be only one, namely the type-number of the content page. And the cHash may be of importancefor the result as well with regard to plugins using that. For instance a message board may make pages cachable byusing the cHash params. If so, each cached page will also be indexed. Thus many phash-rows for a single page-id.
But the most tricky reason for having multiple phash-rows for a single Typo3-page id is if the gr_list is set! Thisworks like this: If a page has exactly the same content both with and without logins, then it's stored only once! Ifthe page-content differs whether a user is logged in or not - it may even do so based on the fe_groups! - then it's
Inside Typo3 - 67
indexed as many times as the content differs. The phash is of course different, but the phash_grouping value is thesame.
The table index_grlist will always hold one record per phash-row. But it may also hold many more records. Thesepoint to the phash-row in question in the case of other gr_list combinations which actually had the SAME content -and thus refers to the same phash-row.
External mediaExternal media (pdf, doc, html) is tricky. External media is always detected as links to local files in the content of aTypo3 page which is being indexed. But external media can the linked to from more than one page. So theindex_section table may hold many entries for a single external phash-record, one for each position it's found. Alsoit's important to notice that external media is only indexed or updated if a “parent” Typo3 page is re-indexed. Onlythen will the links to the external files be found. In a searching operation external media will be listed only once(grouping by phash), but say two Typo3 pages are linking to the document, then only one of them will be shown asthe path where the link can be found. However if both Typo3 pages are not available, then document will not beshown.
Handling extendToSubpages - or not.In the searching plugin there are two ways of searching with respect to accessible pages.
1) join_pages=1: If set, then the final result rows are joined with the pages table. This will make sure that noenableFields-hidden (but NOT extendToSubpages) pages are selected. And it will also make sure to search ALLpages within the rl0 of the index_section table. But extendToSubpages will NOT be taken into account!
2) join_pages=0 (default): Then a long list of page-ids are selected first and after that the final result-rows areselected but without joining the pages-table. This will work with a limited number of page-ids (which means mostsites). And it makes sure that any extendToSubpages-hidden pages are NOT selected along with enableFields-hidden pages. BUT it will also prevent pages down the line of a “php_tree_stop” from being selected as well.
Access restricted pagesA Typo3 page will always be available in the search result only if there is access to the page. This is secured in thefinal result query. Whether extendToSubpages is taken into account depends on the join_pages-flag (see above).But the page will only be listed if the user has access.
However a page may be indexed more than once if the content differ from usergroup to usergroup or just withoutlogin. Still the result display will display only one occurency, because similar pages (determined based onphash_grouping) will be detected.
The tricky scenario:
Say that a page has a content element with some secret information visible for only one usergroup. The page as awhole will be visible for all users. The page will be indexed twice - both without login and with login because pagecontent differs. The problem is that if a search is conducted and matching one of the secret words in the accessrestricted section, then the page will be in the search result even if the user is not logged in!
The best solution to this problem is to allow the result to be listed anyways, but then HIDE the resume if theindex_grlist table cannot confirm positively that the combination of usergroups of the user has access to the result.So the result is there, but no resume shown (The resume might contain hidden text).
External media
Equally for external media they are linked from a Typo3 page. When an external media is selected we can be surethat the page linking to it can be selected. But we cannot be sure that the link was in a section accessible for theuser. Similarly we should make a lookup in the index_grlist table selecting the phash/gr_list by the phash-value ofthe section record for the search-result. If this is not available we should not display a link to the document andnot show resume, but rather link to the page, from which the user can see the real link to the document.
Note:
These tricky scenarios exist only if the content on a page differs based on login. It does not affect situations withaccess restriction to the page as a whole. A general lesson from this is to reduce the number of hidden contentelements! Instead use hidden pages. Better, more reliable.
Tables
index_phashThis table contains references to Typo3 pages or external documents. The fields are like this:
Inside Typo3 - 68
phash 7md5/int hash. It's an integer based on a 7-char md5-hash.
This is a unique representation of the 'page' indexed.
For Typo3 pages this is a serialization of id,type,gr_list (see later) andcHashParams (which enables 'subcaching' with extra parameters). Thisconcept is also used for Typo3 caching (although the caching hash includes theall-array and thus takes the template into account, which this hash does not!It's expected that template changes through conditions would not seriouslyalter the page content)
For external media this is a serialization of 1) unique filename id, 2) anysubpage indication (parallel to cHashParams). gr_list is NOT taken intoconsideration here!
phash_grouping 7md5/int hash.
This is a non-unique hash exactly like phash, but WITHOUT the gr_list and (inaddition) for external media without subpage indication. Thus this field willindicate a 'unique' page (or file) while this page may exist twice or more dueto gr_list. Use this field to GROUP BY the search so you get only one hit perpage when selecting with gr_list in mind.
Currently a seach result does not either group or limit by this, but rather theresult display may group the result into logical units.
item_mtime Modification time:
For Typo3 pages: the SYS_LASTCHANGED value
For external media: The filemtime() value.
Depending on config, if mtime hasn't changed compared to this value thefile/page is not indexed again.
tstamp time stamp of the indexing operation. You can configure min/max ages whichare checked with this timestamp.
A min-age defines how long an indexed page must be indexed before it'sreconsidered to index it again.
A max-age defines an absolute point at which re-indexing will occur (unlessthe content has not changed according to an md5-hash)
cHashParams The cHashParams.
For Typo3 pages: These are used to re-generate the actual url of the Typo3page in question
For files this is an empty array. Not used.
item_type An integer indicating the content type,
0 is Typo3 pages
1- external files like pdf (2), doc (3), html (1), txt (4) and so on. See theclass.indexer.php file
item_title Title:
For Typo3 pages, the page title
For files, the basename of the file (no path)
item_description Short description of the item. Top information on the page. Used in searchresult.
data_page_id For Typo3 pages: The id
data_page_type For Typo3 pages: The type
data_filename For external files: The filepath (relative) or URL (not used yet)
contentHash md5 hash of the content indexed. Before reindexing this is compared with thecontent to be indexed and if it matches there is obviously no need forreindexing.
crdate The creation date of the INDEXING - not the page/file! (see item_crdate)
parsetime The parsetime of the indexing operation.
sys_language_uid Will contain the value of GLOBALS["TSFE"]->sys_language_uid, which tells usthe language of the page indexed.
item_crdate The creation date. For files only the modification date can be read from thefiles, so here it will be the filemtime().
Inside Typo3 - 69
index_sectionPoints out the section where an entry in index_phash belongs.
phash The phash of the indexed document.
phash_t3 The phash of the “parent” Typo3 page of the indexed document.
If the “document” being indexed is a Typo3 page, then phash and phash_t3are the same.
But if the document is an external file (PDF, Word etc) which are found as aLINK on a Typo3 page, then this phash_t3 points to the phash of that Typo3page. Normally it goes like this when indexing: 1) The Typo3 document isindexed (this has a phash-value of course), then 2) if any external files arefound on the page, they are indexed as well AND their phash_t3 will becomethe phash of the Typo3 they were on.
But the significance is unclear. I'm not sure this value is used for anythinganywhere. So it might not be important at all. But it can be used to derterminethe relation ship of “sub-documents” to an indexed Typo3 page, if you will.
rl0 The id of the root-page of the site.
rl1 The id of the level-1 page (if any) of the indexed page.
rl2 The id of the level-2 page (if any) of the indexed page.
page_id The page id of the indexed page.
uniqid This is just an autoincremented unique, primary key. Generally not used (ithink)
index_fulltextFor free text searching, eg with a sentence, in all content: title, description, keywords, body
phash The phash of the indexed document.
fulltextdata The total content stripped for any HTML codes.
Currently the MySQL FULLTEXT search is not used (something with MATCH ... AGAINST), but this will be added inthe future I hope.
index_grlistThis table will hold records related to a phash-row. Records in this table confirms that certain gr_lists wouldactually share the same content as represented by phash-row - even though the phash-row may be indexed underanother login. The table is used during result-display to positively confirm if the current user may see the resume(which otherwise might contain secret info). Please see discussion above.
index_words, index_relWords-table and word-relation table. Almost self-explanatory. For the index_rel table some fields requireexplanation:
count Number of occurencies on the page
first How close to the top (low number is better)
freq Frequency (please see source for the calculations. This is converted from somefloating point to an integer)
flags Bits, which describes the weight of the words:
8th bit (128) = word found in title,
7th bit (64) = word found in keywords,
6th bit (32) = word found in description,
Last 5 bits are not used yet, but if used they will enter the weight hierarchy.The result rows are ordered by this value if the “Weight/Frequency” sorting isselected. Thus results with a hit in the title, keywords or description are rankedhigher in the result list.
Inside Typo3 - 70
Todo and other things• function linkPage should be faster. Is currently quite slow because it calls the typolink function in cObj. We pass
only a id number and so we could optimize a lot. MAYBE change how the function in pibase works?
Inside Typo3 - 71
Wish listsTCEB1, t3lib/
WORK and FEATURES:• Logging is not finished for delete/copy.
• Check permissions and go through it while writing a document about it. Especially about moving...
Delete:
• delete "deleted" -support!
• recreate delete support.
• Recyclebin: If a item is deleted and is NOT in the recyclebin, then move it to the closed recyclebin in thepagetree. If that is not present, then delete normally. If you delete anything in a recycle bin, it's totally deleted.
• Remove references to records when deleting (totally) (refs to MM for both tables/files)
• submit dates in non-UNIX-time format (eg. DD-MM-YYYY)
• submit files directly / Upload to tce-db
CHECK:
• Mac / Linux CR/LF characters: It seems that textfields updated from a Mac submits wrong CR/LF- characters.Solutions: Let Typo3 correct input to the database by substituting the wrong characters with a correct PC-sequence before it goes into the database (eval-option for a textfields).
TBEB2, typo3/ (Interface)
CHECK• What if there's no content table?
Known Bugs: • Jeg har igen oplevet en fejl i en palette, hvor et valg i en selectorboks gav udtryk for at være det samme i flere
(nye?) afsnit. Prøv at lave 3 nye sideindholdselementer og tildel et af den en grafikrammer til et billede.Værdien vil nu også findes i de andre 2 elementers felt!
• Hvis man tilknytter en giffile med navnet "webpane..gif" (altså 2 punkttummer), så bliver den til et ikon idokument-modulet
• Hvis man har et IE-vindue åbent og har logget ind én gang. Og åbner et andet vindue (ved at klikke pågenvejs-ikonet igen!), så får man en fejl som "No user logget in)"
LOGIN SAFETY: • only-admin flag (only admin users can log in..)
• allow/deny IP's (normal / admin) in be_user...
• Number of levels? (still 20?) -> 100 levels
• load_edit + click-menus must reflect permissions
Inside Typo3 - 72
BUGS:Interface:
• If you switch from an input-field in a palette to a selector-box (try textbox-content type: from "image width" to"splash layout") an error occurs in line 3334
• Sometimes when you click the list-pane in the file-menu it generates a JS-error - something with "TCA[..][..]"
Javascript editing interface notes:Drop the JavaScript editing interface (still use the palette-idea!)
Pros:
• Quicker interface load (main: 182kb to 138kb, ti_inc.php 125kb to 23kb)
• Netscape doesn't crash
• Other browsers will work
• Selective lists (may be cashed in the userprofile)
• Small clients can run also
• More scalable (more tables)
Cons:
• Quicker on fast computers
• Works!
TBE ModulesB4, Modules
Modules TODO's:
web_func:
• AutoConvert: Read other homepages / Word-exported HTML and automatically submit this into Typo3
• XML-export / import
• record eksport/import
file_images:
• link til rediger: rotate / crop / gamma
tools:
• integrity for records
• clean up fields with old references
• check for potential dangerous php-extension
• delete "marked-deleted" records + files.
Inside Typo3 - 73
NotesBugs, considerations, notes,
• mail() hangs in 90 second (approx) if computer is not on the net! (deliver to mail-server)
• REWRITE of files when they already exists? shortMD5 is guilty?
• "filemtime" should be included in the hash of files (see t3lib/images.php). This ensures that renewed files areupdated
• "Fields not properly updated:" - error: Varchar(xx) cannot included spaces AFTER the last character andtherefore Typo3 interface reports an error. Solve this error by setting "eval" to "trim" in $TCA for inputfields ofthe type VARCHAR.
• mysql_query() function should not be used I think as this queries the current database. mysql() should be usedinstead.
• The fields in the tables be_user / be_group that holds the lists of modules are only 256 chars long. That meansif too many modules, exclude_fields or whatever is added to the list, then it will overflow. Probably this doesn'tmean anything except that no access is granted. The list "non_exclude_fields" has already been expanded!
• The delete flag: Well, the delete flag is used on almost all records (except sys_dmail, sys_domain) in order toensure, that unique id's of records are not reused....
• JavaScript: escape() doesn't rawurlencode the "+"-character. This can be a problem, eg. when trying to renamefiles with a plus in the name. I have made an alternative escape-function.
• PDF-files over 600 k are not rendered by ImageMagick. Less than 270 is! How come and is this true. Number ofpages?
• So far exclude-fields are not checked in the PAGE module because users should be notified if fields are set, thatthey normally cannot operate.
• Netscape demands that urls put in GET-vars are rawurlencoded. If not, it messes up links.
Rapport of "deleted"-check in typoscripts (190500)
Typo3: - "deleted" is not checked in status.php. Should it? - "deleted"-field must be set manually in userauth for user-tables!!
Hardcoding: - "pages" in load_tree.php - "sys_filemounts" in userauth_group - "user-group tables" in userauth_groups - "pages" in ti_inc.php - "pages" in transferdata.php
TypoScript: - sys_domain is NOT checked for deleted in "page.php" - getForeignRecords() (page.php) does not check for deleted!!! (this is even not used any more!!
Hardcoding: - "pages" in page.php - "pages" in t_search.php - "pages" in index_ts.php (caching) - "sys_template" in t_template.php - "fe_groups" in index_ts.php
Inside Typo3 - 74
ImageMagick notes
Filesystem Locations (rpms): NO LZW:
4.2.9: /usr/X11R6/bin/
LZW:
5.1.1: /usr/local/bin/
5.1.0, 5.2.0, 5.2.3: /usr/bin/
What is wrong with ImageMagick ver. 5+? • "combine" creates a transparent entry in GIF-files (or makes an alphachannel) when overlaying images. Ver
4.2.9 doesn't. This creates the problem that the giffiles are often transparent in dark areas.
• "combine" interprets masks reversely to the norm. This means that any mask must be negated beforerendering.
Compatilibity:
<= 4.2.9: + NO-LZW problem - Transparency BUG - Mask negate
5-5.1.x: - NO-LZW problem + Transparency BUG - Mask negate
5.2.x: - NO-LZW problem + Transparency BUG + Mask negate
+ Gaussian?
Version 5+ Seems to be very slow.
Version 5.2.3 in test had the following problems: Using such as -sharpen and -blur was very slow compared to4.2.9. Blurring was maybe 2 or three times slower. -sharpen couldn't be used at all at values above like 10 or so(and I normally use 99). It resulted in operations never carried out.
Gaussian blurring didn't seem to work well. I succeeded in passing values of 15. There was an error if a passed"15x5" for example. High Gaussian blur values didn't make any difference.
Response from ImageMagick developers
Bob Friesenhahn <[email protected]>
> The greatest problem at this point is, that version 5+ seems to be> very slow compared to ver4: Version 5.2.3 in test had the> following problems: Using such as -sharpen and -blur was very slow> compared to 4.2.9. Blurring was maybe 2 or three times slower.> -sharpen couldn't be used at all at values above like 10 or so. It> resulted in operations never carried out. Gaussian blurring didn't> seem to work well. I succeeded in passing values of 15. There was> an error if a passed "15x5" for example. High Gaussian blur values> didn't make any difference. Now, can this be true?
Note that the form and range of the arguments has totally changed for-sharpen and -blur since 4.2.9. I suspect that this may be related tothe problem you are [email protected]
Inside Typo3 - 75
Version 5 has changed significantly from version 4. Version 4 had supportmethods for the command line utilities. Version 5 has exported it'sAPI for others to use directly rather than relying on the command lineutilities. The good news is that the new API has stabelized and it isunlikely you will see any changes to the API in the future (except for additional API called, the existing API should not change except inexeptional circumstances).
> problems: Using such as -sharpen and -blur was very slow compared to> 4.2.9. Blurring was maybe 2 or three times slower. -sharpen couldn't be> used at all at values above like 10 or so. It resulted in operations> never carried out. Gaussian blurring didn't seem to work well. I> succeeded in passing values of 15. There was an error if a passed> "15x5" for example. High Gaussian blur values didn't make any> difference. Now, can this be true?
Version 5 uses a more sophisticated sharpen/blur algorithm. The parameterhas changed as well. The best default value is just 0 which is anauto sharpen/blur value.
> - "combine" creates a transparent entry in gif-files (or makes an> alphachannel) when overlaying images. Ver 4.2.9 doesn't. This creates> the problem that the giffiles are often transparent in dark areas. -
You can always get rid of transparency with the +matte option.
> "combine" interprets masks reversely to the norm. This means that any> mask must be negated before rendering.
Opacity has reversed from version 4 to accomodate the SDL API.
> Please give me some insight in what I might do, why version 5 is so> slow for these operations.
Version 5 may be slower in general because ImageMagick always shoots forquality over speed.
Inside Typo3 - 76
