Every page is composed of slots which are the elementary blocks. The slots that a page type includes are defined in pagexml in the SLOT tags as children of that PAGE tag.
Slot name is in relationship with its file name. In this example the NAME attribute has value core/logo and since TPL is common, the template for this slot will be looked in common/templates/core/logo.tpl. The directory has the same name as the module name, in this case core.
In this example there is no PHP script associated to this template (a simple static template), and thus PHP attribute is set to 'NONE'. The POSITION attribute specifies where the slot template should be shown in the frame as described in themes. The BLOCK attribute, instead defines the decoration to be applied to the slot, this is also described in the themes document.
<SLOT NAME="core/logo" TPL="common" PHP="none" POSITION="left2" BLOCK="title"/>In this second example there is also a PHP script associated to the template since PHP attribute value is common. This means that a PHP script located in common/pages/core/nav.php will be executed and will be able to address the common/templates/core/nav.tpl template.
<SLOT NAME="core/nav" PHP="common" TPL="common" POSITION="center1" BLOCK="none"/>This slot defines a system wide menu that changes dinamically according to the permissions of the logged user. It is reasonable to change this menu from site to site to insert new local functionalities or the like. To accomplish this result I could modify the common template and php file but this would not be advisable because an upgrade would overwrite the common files. Moreover we would like to see easily which modifications we made to implement a particular site and this approach would make this more difficult.
If we want to simply change the table in the php code, for adding a new icon, or for changing all of them we can define the PHP attribute as local. In this case the script would be loaded from local/pages/core/nav.php.
<SLOT NAME="core/nav" PHP="local" TPL="common" POSITION="center1" BLOCK="none"/>In other case we may also want to alter the templates and we can do this by defining TPL attribute as local: in this case our smarty template would be loaded from local/templates/core/nav.tpl. Of course any combination of 'common', 'local' and 'none' for PHP and TPL is valid.
While it is a good rule to have a PHP script named in the same way as the template, in some particular cases you may also want to call a PHP script and a template with different names. This is possibile and can be achieved by using NAME_PHP and NAME_TPL attributes instead of NAME.
A slot script should only define functions. It should not execute any code when it is loaded. This will allow the system to check the security authorization of the user before any slot code is executed. The default function that the system will call after the code is loaded is the name of the slot, with the slash replaced by an underscore, and an underscore added to the end. As an example, the system will call core_nav_() as the main function for the core/nav slot.
You can also define a different function to be called for a slot. Use the FUNCTION parameter in the SLOT definition.
Each slot is loaded with a require_once statement. So it will be loaded only once, no matter how many times the slot is defined in a page. The defined function will be called for each slot entry though.