Intro ┬╗ Agile Toolkit - Introduction (Step 1)

Before you embark on the journey, open this on-line chat where you can reach out to us with questions, suggestions and feedback:

If you never used PHP

If you are new to PHP or have newer developed any Web Apps, you've come to the right place. You'll need PHP/MySQL setup before you can begin:

  1. Set up PHP and MySQL (https://www.apachefriends.org)

  2. Install Composer (https://getcomposer.org).

    Mac / Linux:

    curl -sS https://getcomposer.org/installer | php
    sudo mv composer.phar /usr/local/bin/composer

    Windows: http://www.techflirt.com/install-composer-xampp

  3. Create a very basic "test.php" and open it through the browser.

IMPORTANT: each php file starts with line '<?php', then text as displayed below:

echo "PHP WORKS!!";

Open this file through through http://localhost:8080/test.php and you should see:

PHP WORKS!!

Install Agile UI

Through the terminal, go inside folder where "test.php" is located and run:

composer require atk4/ui

This will install the most recent version of "Agile UI" and "Agile Data". To update, you can always use composer update command.

"Hello World" in Agile UI

Edit your "test.php" to contain the following:

require 'vendor/autoload.php';

$app = new \atk4\ui\App('My First App');
$app->initLayout('Centered');

$app->layout->add('HelloWorld');

Keep the "test.php" open in your browser. You'll be editing it again.

If you already familiar with some full-stack PHP framework (Laravel, Symfony, Yii, FuelPHP, CakePHP etc), then you can incorporate Agile UI as part of its rendering process. (We are working on the guides).

Buttons

$button = $app->layout->add(['Button', 'Hello there']);

This should add a basic button on your page. (Don't forget square brackets; they indicate an Array in PHP). You can inject property defaults to your button like this:

$button = $app->layout->add(['Button', 'Hello there', 'icon'=>'book']);

The other approach you can use is:

$button = $app->layout->add('Button');
$button->set('Hello there');
$button->icon = 'book';

The effect is the same. Finally if you are using IDE, you may find the following format more familiar:

use \atk4\ui\Button;

$button = new Button('Hello there'); 
$button->icon = 'book';
$app->layout->add($button);

Find the syntax that's most comfortable for you. Button supports many variations, you can combine them any way you want.

You will find many other ways to create buttons here:

Working with Button

If you know "Bootstrap CSS" or "Semantic UI CSS", you know how to create buttons that do nothing. In Agile UI we make buttons (and other UI) interractive and infuse it with data.

To make button clickable specify a link to the destination:

$button->link('http://google.com/');

If you want to create several files 'test.php', 'demo.php', you can create navigation between them and even pass arguments like this:

$button->link(['demo', 'message'=>'cake is a lie']);

Now when user clicks on your button, he will be directed to "demo.php" and the argument "id" (visible in the URL) can be accessible through $_GET['message']:

$header = $app->layout->add(['Header', 'Congratulations, you have reached page 2', 'icon'=>'birthday']);

if(isset($_GET['message'])) {
    $header->subHeader = 'Message was: '.$_GET['message'];
}

You must have noticed that "Button" and "Header" follow a very similar pattern. You specify either to the add() method. You can optionally inculde 'icon'. You can specify label or subHeader.

This universal functionality is implemented through a "View" class that both Header and Button extend/inherit. Read documentation about "View" for deeper undestanding of the rendering process:

Fun with Segments

Agile UI is based on a CSS framework Semantic UI. Thanks for this integration, you can use other styling elements without dipping your hands too deep into the HTML.

Semantic UI offers a good demo-page for building segments. If you could use this inside your app, you could present your other elements better. Fortunatelly, Agile UI makes it very simple task to do.

Add the following code:

$segment = $app->layout->add(['View', 'ui'=>'segment'])
    ->addClass('red inverted');

$segment->add('Button')->set('Button in a Segment');

Previously you only added objects to $app->layout but now you can add buttons inside your new segment.

Agile UI does not require you to write HTML (not for the basic stuff anyway), but you can still decorate your objects with some Semantic UI features. Try out this code and compare result with Semantic UI page:

$app->layout->add(['View', 'ui'=>'segment'])
    ->addClass('inverted red circular')
    ->add(['Header', 'Buy Now', 'inverted', 'subHeader'=>'$9.99']);

The reason why I'm insisting on using PHP and not HTML is because you can use object-oriented qualities of PHP to encapsulate all this functionality into a new component (class) for the "Red Buy Button" then use it anywhere in your code saving you lots of time:

$app->layout->add(['RedBuyButton', 'price'=>9.99]);

If you just copy examples, this one won't work. That's because "RedBuyButton" component is not implemented yet. You can implement it as an excercise..

Data Models

So far, we have only looked into the UI features. If you wanted a non-interactive, static UI you could have just made a HTML page, or even used Photoshop. Web apps work with DYNAMIC data that is constantly changing and updating. Let's find out which components can help you work with data.

Grid (Table)

The most convenient way to display data is through a Grid:

$grid = $app->layout->add(['Grid']);
$grid->setSource(['John','Peter','Steven']);

While 'setSource' is a pretty good way to start, we want our data to come from a MySQL database. Use MySQL management tool (http://stackoverflow.com/questions/6817551/sequel-pro-alternative-for-windows) or even phpmyadmin that comes with MAMP (http://stackoverflow.com/questions/14094534/getting-to-phpmyadmin-with-mamp) to access your local MySQL server.

Create table "client" with columns "name" and "address". Add several rows of data.

Our next task is to connect to the database from your PHP app and channel the data into the Grid. You do this by using the following code so that $db will contain your database persistence object:

$db = new \atk4\data\Persistence_SQL('mysql:dbname=atkui;host=localhost','root','root');

Next, you need to describe structure of your data to the rest of the PHP application by using a "Model".

class Client extends \atk4\data\Model {
    public $table = 'client';

    function init() {
        parent::init();

        $this->addField('name');
        $this->addField('address');
    }
}

You can place this class declaration anywhere in your file, or make use of Composer's autoloader functionality by adding this inside your composer.json and running composer update afterwards.

    "autoload":{
        "psr-0":{
            "": "lib/"
        }
    },

In order to connect the component to your database, you'll need both the database persistance object and the model class:

// $grid->setSource() <----- remove this line

$grid->setModel(new Client($db));

You should now see your data inside a Grid component. If you need to access the Model object, use $grid->model and read documentation about Agile Data. This knowledge will allow you to place further conditions on your queries, join data from multiple tables, include expressions or even connect to remote APIs for the data source:

Form

The Form component offers a handy way to enter data. Form can be used to ask user for a contact details, to log-in, to change user settings, place orders and in many many other situations.

Form automatically load data from your database if you use $form->model->load(5) to load specific database record for editing.

$form = $app->layout->add('Form');
$form->setModel(new Client($db));

$form->model->loadAny();  // will load SOME record from

Form is an interractive component which allows the user to submit data back to your application. Probably one of the mundaine and annoying task in most PHP frameworks can be solved with Agile UI form in a very elegant way:

$form->onSubmit(function($form) {
    $form->model->save();
    return $form->success('Record updated');
});

You will find more information about the form here:

What to do next?

Agile UI and Agile Data are the tools to help you create something really cool. We made the syntax friendly for beginners but our intended audience are PHP enterprise apps.

If you enjoy poking in HTML / JS and have enough time to do so, most companies have other priorities, which is why component framework like Agile UI is ideal for them.

Becoming proficient in Agile UI / Agile Data will make you a more efficient web developer.

Next Release coming soon!

Agile UI is always on the move. We are working to add more standard components and give them to you under MIT license (for free). If you are interested to learn about what's coming next: