Backend modules are subdivided into “main modules” and “submodules”. Generally speaking “modules” covers them all. Refering to a module is done by it's name and 'path'. For instance the submodule “List” in the “Web”-module would be refered to as “Web>List” module.
The modules are technically represented by a folder each in typo3/mod/, the first level being the main module and subfolders to this being the submodules. This structure is reflected in the backend interfaces - the Classic Backend (CB) and Alternative Backend (AB) view.
This illustration shows the relationship between them:
Notice how the Classic Backend presents access to the modules through the panes, while the Alternative Backend renders a vertical menubar. It's the same modules invoked - just different shells to manage them.
Looking at the illustration you'll see that the userdefined Photo Marathon module (from the testsite) appears within the Web module. However it's not a part of the directory structure found at typo3/mod/web/ but rather a parallel structure found in typo3conf/ where it is located in web/uPhotomarathon.
Placing custom modules - and customized material in general! - in the typo3conf/ folder is clever because the typo3/ folders content is not touched and can thus be upgraded easily by simply overriding the files when a new version is released. And so far we've seen the extTables.php files including table-description files being placed in the typo3conf/ folder in addition to the wellknown localconf.php file and now also the custom modules!
First of all, determine if you wish to make a main module or submodule. Submodules should be placed in folders in typo3conf/ named similar to the main module found in typo3/mod/. Custom main modules should of course be located in typo3conf/ directly.
Always prepend your user defined modules with a “u” like in “uPhotomarathon”. This will ensure that the module name will not be taken by a default module some day.
This is how the custom Photo Marathon module (from typo3conf/web/uPhotomarathon) is located in the Classic backend:
Regardless of a module being a main- or submodule, a file named “conf.php” must be found in the module folder:
The clear.gif file found is not required, but quite practical to have around.
index.php is not required either. It's commonly used as the main script invoking the module, but it's always configured in conf.php.
locallang.php contains labels for the interface, typically translated into the system languages.
tab_icon.gif is configured in conf.php to be the icon of the module. Max 12 pixels high.
conf.php is however the only required file. This is how it looks inside in the Photo Marathon case:
<? // Relative path to the module from the typo3/ folderdefine("TYPO3_MOD_PATH","../typo3conf/web/uPhotomarathon/"); // Relative path to the typo3/ folder$BACK_PATH="../../../typo3/"; // Module name as shown in the backend:$MLANG["default"]["tabs"]["tab"] = "Photo Marathon"; // Icon-file used with the module. Max 12 pixels high.$MLANG["default"]["tabs_images"]["tab"] = "tab_icon.gif"; // Short description for the tab image label:$MLANG["default"]["labels"]["tablabel"] = "Photo Marathon (EXAMPLE!)"; // Longer description, used in the "Help>About modules" module $MLANG["default"]["labels"]["tabdescr"] = "This is an example module related to ...."; // Danish translation of labels:$MLANG["dk"]["tabs"]["tab"] = "Fotomaraton";$MLANG["dk"]["labels"]["tablabel"] = "Fotomaraton (Eksempelmodul)";// Main script invoked:$MCONF["script"]="index.php"; // Access level. // You can specify access for both backend users and groups to this module.$MCONF["access"]="user,group"; // Syntax: [module]_[subModule] or just [module] if no submodule!! // Remember, never use underscore "_" in module names!$MCONF["name"]="web_uPhotomarathon"; ?>
As you can see both the index.php and tab_icon.gif files are configured herein. In turn the locallang.php file is included from index.php.
// Relative path to the module from the typo3/ folderdefine("TYPO3_MOD_PATH","../typo3conf/web/uPhotomarathon/"); // Relative path to the typo3/ folder$BACK_PATH="../../../typo3/"; Defining these paths correctly is vital. These vars tells the script where it is in relation to the typo3/ folder. $BACK_PATH is generally used as a script prefix to call scripts in the typo3/ folder and keeping this value correct will ensure success when linking to scripts and images. You can see how it's used in the default modules. Plenty of examples.
The TYPO3_MOD_PATH constant is used in the init.php file which must be included immediately after the conf.php file in the index.php main script (or whatever you configure it to be) of the module.
// Access level. // You can specify access for both backend users and groups to this module.$MCONF["access"]="user,group";
The access settings determines how the system handles access to your module. If you set the value to blank, then the module appears for ALL users. Like with the “exclude” option of fields in $TCA you should be very certain that you want this. Better configure the module to be specifically assigned to users/groups than having to modify a whole bunch of groups later due to a change here.
Setting it to “admin” will allow only 'Admin'-backend users to access it.
Then you can finally enter “user”, “group” or both in a list. Each code determines where the module will appear in the backend user and group settings. For instance the settings used here will result in the module list to look like this:
// Syntax: [module]_[subModule] or just [module] if no submodule!! // Remember, never use underscore "_" in module names!$MCONF["name"]="web_uPhotomarathon";
The module name is used many places to refer to the module. Not only in the access lists, but also in TSconfig where applicable.
// Danish translation of labels:$MLANG["dk"]["tabs"]["tab"] = "Fotomaraton";$MLANG["dk"]["labels"]["tablabel"] = "Fotomaraton (Eksempelmodul)";
The labels are used for the module title in the backend. You can specify the label in many languages, in this case, danish.
// Longer description, used in the "Help>About modules" module $MLANG["default"]["labels"]["tabdescr"] = "This is an example module related to ....";
In addition you can write a longer description of the module. This will be shown in the “Help>About modules” module and likewise the “tab” and “tablabel” above you can provide a localized version in another language.
When your module is configured you must also enable it in the global $TBE_MODULES array. The default values (and syntax derived from this) of this array is seen in the bottom of the default tables.php file:
$TBE_MODULES = Array ( "web" => "layout,modules,info,perm,func,list,ts", "file" => "list,images", "doc" => "", // This should always be empty! "spacer1"=>"", "user" => "task,setup", "tools" => "beuser,dbint,log,config,isearch,install,phpadmin", "help" => "welcome,aboutmodules,quick,about");
(Notice: The “doc” key is hardcoded to be ignored in the Alternative Backend (AB). In addition “spacers” and not used either in the AB)
Looking into the typo3conf/extTables.php file, we see in the very bottom how the web/uPhotomarathon module is added to the main module “Web”:
$TBE_MODULES["web"].=",uPhotomarathon";
That's basically it! You can of course also remove default modules this way by modifying the array. Or even switch them around, altering the order etc.
