Improve this Doc

User Interface (Views)

A View is an object in Agile Toolkit which knows how to render itself. Some examples of Views are “button”, “form”, “lorem ipsum”, “menu” etc.

By default, a View relies on a template engine to produce its output. Views can contain other views. All Views in Agile Toolkit contain many useful features.

HelloWorld View

You don’t code ‘Hello World’ in Agile Toolkit. You use existing class. Placing this code inside your Page::init will display the usual greeting on your page:

$this->add('HelloWorld');

Tip

This is a good example of Agile Toolkit principle. Create object once and then re-use it.

Find HelloWorld.php file in atk4 folder and open it, you should see this:

class HelloWorld extends AbstractView
{
    // message text
    private $message = 'Hello, World';

    /**
     * Set custom message text
     *
     * @param string $msg Message text
     *
     * @return void
     */
    function setMessage($msg)
    {
        $this->message = $msg;
    }

    /**
     * Render message
     *
     * @return void
     */
    function render()
    {
        $this->output('<p>'.$this->message.'</p>');
    }
}

Warning

Class “HelloWorld” is probably the only class in Agile Toolkit which does not rely on “Template” engine. Although I have included it here to help you understand how rendering works, always use template files and never store markup in your PHP files.

Reading the class source reveals that you can set a property “message”, which will display a different greeting. Default properties can be reassigned through the add() call:

$this->add('HelloWorld', ['message' => 'Hello, Agile Toolkit']);

Another way to change the message is after the object has been initialized:

$this->add('HelloWorld')->setMessage('Hello once again');

View class

A most popular HTML element is <div>. In Agile Toolkit most objects will render into a single DIV or multiple HTML elements contained within that DIV (See :View class)

This DIV will always have an unique ID. The next example will create a DIV object but instead of rendering it normally, it will display the HTML code it generates inside a box:

$h = $this->add('View')->set('Sample Header');

$box = $this->add('View_Box');

$box->set( $h->getHTML() );

Tip

Agile Toolkit automatically encodes text into HTML, JS, SQL etc as necessary. This help you avoid some validations and prevent some nasty exploits (such as JavaScript injection)

View with Template

Create file shared/templates/view/mytemplate.html:

<div id="{$_name}">
Roses are {rose_color}Red{/}, Violets are {violet_color}Blue{/}.
I love {$Target}.
</div>

Then place this UI code:

$this->template->loadTemplate('view/mytemplate');

Notice how we are re-using the existing View class but specifying alternative template to it. This can be done with any view. For instance a Form class can use template form/compact to render your form in a different look.

A specified template is automatically parsed and a special GiTemplate object will be available through a template property of a View:

$this->template->set('rose_color', 'Pink');
$this->template->set('violet_color', 'Violet')

Finally - when you add one view into another, you may select Spot where it will appear:

$poem
    ->add('Button', null, 'Target')
    ->set('Red Buttotn')
    ->addClass('atk-swatch-red');

When Spot is ommitted, then it defaults to ‘{$Content}’, which should be defined in a template.

Composite Views

In Agile Toolkit a view consisting of other views is called a Composite View. Some examples of composite views are CRUD (which consists of Grid and Form) and also Form (consisting of Form_Field and Button)

Controller and Model

As you probably have noticed - the Views we have used so far work pretty good without models or controllers. In real world application, you are most likely to link the view with data source (by specifying a Model):

$poem->setModel('Book')->tryLoadAny();

Note

You should change name of the {tags} in mytemplate.html to correspond with the fields of the “Book” model.