Using Layouts

ApiWeb introduces Layouts but ApiFrontend further extends them into self-sufficient class. In your application, the Layout is the region on the main template which can change under certain conditions.

The most common is the layout_Content, which uses various pages depending on currently used Page class as determined by routing logic.

The other example is the "User Menu". It's that small area on the page in the right-top corner which may contain either log-in form or user links. By default ApiFrontend only initializes the "Content" logic, but here is the example on how you can create user menu.

User Menu Example

First you will need your own application template. Create file templates/default/shared.html by copying it from atk4/templates/shared/shared.html. Open that new file in your editor and define <?UserMenu?> region somewhere. I have added it like this:

Before

<div id="atk-version"><b><?name?>Agile Toolkit™<?/?></b><br/><i><?$version?></i></div>

After

<div id="atk-version"><?UserMenu?><b><?name?>Agile Toolkit™<?/?></b><br/><i><?$version?></i><?UserMenu/?></div>

Next you will need to add this line inside your application class's (lib/Frontend.php) init():

$this->addLayout('UserMenu');

And then add the following function into your application class:

    function layout_UserMenu(){
        if(
$this->auth->isLoggedIn()){
            
$this->add('Text',null,'UserMenu')
                ->
set('Hello, '.$this->auth->get('username').' | ');
            
$this->add('HtmlElement',null,'UserMenu')
                ->
setElement('a')
                ->
set('Logout')
                ->
setAttr('href',$this->getDestinationURL('logout'))
                ;
        }else{
            
$this->add('HtmlElement',null,'UserMenu')
                ->
setElement('a')
                ->
set('Login')
                ->
setAttr('href',$this->getDestinationURL('authtest'))
                ;
        }
    }

Provided that the function is defined and tag exists in Application's template (match is case-sensitive) you should have a new dynamic element on your page. If your application uses different templates, for example for document printing, which wouldn't have such a tag, then the function will not be called and user menu will not be displayed.