Intro ┬╗ Agile Toolkit - Introduction (Step 1)

If you have never used PHP

To develop Web Apps, you'll need PHP/MySQL installed on your computer before you can begin:

  1. Set up PHP and MySQL through XAMPP (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 new file "test.php" and open it in a text editor.

IMPORTANT: each PHP file must start with '<?php' on the first line. Type the following text on the second line:

echo "PHP WORKS!!";

To test that your PHP file works properly, open http://localhost:8080/test.php and you should see:

PHP WORKS!!

Install Agile Toolkit

Agile Toolkit consists of several PHP frameworks such as "Agile UI" and "Agile Data" which will help you create Web User Interface easily and connect it to your Database.

To install Agile Toolkit , open the terminal (or CMD), go inside the folder where file "test.php" is located and execute:

composer require atk4/ui

To update your version of Agile Toolkit any time later execute the composer update command.

Coding "Hello World" in Agile UI

Open your file "test.php" in a text editor and type the following code snippet. Refresh your browser after saving the file.

require 'vendor/autoload.php';

// Initialize App and Layout first
$app = new \atk4\ui\App('My First App');
$app->initLayout('Centered');

// Your application starts here
$app->layout->add('HelloWorld');

Introducing the "Button" component

In Agile Toolkit you develop your app by adding "Components" to your page. A component could be a button, a form, a menu or anything else. Try by adding a "Button" to your app's layout.

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

Square brackets indicate an Array in PHP. First argument to add() could be either a string or an array. You can specify additional properties to your component with 'icon'=>'book' like this:

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

The above code reads:

  • Create new "Button" component,
  • Set content "Hello there"
  • Set "icon" to "book"
  • Add button into Layout of the $app.
  • Keep reference to your new component in variable $button,

You can structure your code differently. The next two snippets will have the same effect. Some people may prefer one way or another:

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

or

use \atk4\ui\Button;

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

To find more examples on how to use "Button" component, check out the links below:

Working with a Button

A button needs to do something when it is clicked. To send user to a different URL, simply type:

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

If you want to have multiple pages you can navigate between them using link() with Array argument.

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

The link above contains an argument message with a value the cake is a lie. Once the user reaches the second page (located inside the file demo.php), you can access value of an argument through $_GET['message']. Create file demo.php and put the following code there:

require 'vendor/autoload.php';

// Initialize App and Layout first
$app = new \atk4\ui\App('My First App');
$app->initLayout('Centered');

// Your code starts here
$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" usage a very similar syntax. This can be said for most of the components in Agile Toolkit.

This is because both Button and Header extend the same class "View" inheriting many of its properties and methods. Read the documentation about the "View" component below, for deeper undestanding of the rendering process:

Fun with Segments

Agile Toolkit relies on a CSS framework Semantic UI to draw components in a browser. You can look through documentation of Semantic UI and use any other styling feature to further customize your components.

For example, Semantic UI has a Segment Feature. Even though Agile Toolkit does not have a dedicated component for Segments, you can still use them inside your app like this:

$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 as well.

Agile UI does not require you to write HTML (not for the basic stuff anyway), but you can still decorate your components with some Semantic UI features. Try out this code and compare the results with Semantic UI page (Look for the "Buy Now" circle):

$app->layout->add(['View', 'ui'=>'segment'])
    ->addClass('inverted red circular')
    ->add(['Header', 'Buy Now', 'inverted', 'subHeader'=>'$10.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 like this:

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

Data Models

So far, we have only looked into the UI features. In most cases web applications show the data to the user retrieved from a database.

Agile Data helps some components (like Form or Table) to communicate with your database directly.

Find PHPMyAdmin app that came with your XAMMP install. Create new database "atkui", then inside it create table "client" with the following columns: id, name and address:

Continue to add several rows of data for testing.

Our next task is to connect to the database from your PHP app, load the data and display it inside the Grid. You do this by using the following code so that $db will contain your database connection 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". There is no need to declare "id" field.

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

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

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

To verify everything, let's load up the first row of our client table and display the name as a button label:

$client = new Client($db);
$client->loadAny();

$button->set($client['name']);

Grid

The most convenient way to display data is through a Grid. To link it with the client table you will need both the Client model and the connection object:

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

You should now see your test data inside a Grid. Component stores the model inside a property $grid->model. You can perform various operations with your model such as: ordering results, adding conditions, limiting number of records etc. To find out more, read the documentation on Agile Data:

Form

The Form component offers a handy way for the user to enter data such as: contact details, to log-in credentials, settings, or order details.

Form can automatically load the data from your database if you know the ID of the record $form->model->load(5).

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

$form->model->load(5);

Unlike all the components we looked at before, Form is an interactive component. When the user submits the form, it will transmit data back to your web application. You can write the code to handle submission which, for example, will create the new record in your database table:

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

To find out more about forms, see the documentation below:

What to do next?

Agile UI and Agile Data are the tools to help you create some cool apps. We have made our syntax beginner-friendly, however Agile Toolkit is also capable of solving the most complex enterprise tasks.

We have included a few ideas for the apps which you can create with Agile Toolkit next:

App 1: Greeting program

A good excercise in a new programming language is to create an app which will greet the user with respect.

  • ask name of the user [Josh]
  • respond with a greeting "Hello, Josh".

This requires you to collect the information from the user with a Form then output a styled message.

If you complete this task, try adding a next step that asks for the user's age and respond appropriately.

App 2: Contact Form

Many sites feature a contact form. Your goal will be to create such a form, collect information and store it in the database. Next create a separate page that will display all the entries by the user through a table.

Decorate your contact form by using custom layout, use different field types (e.g. checkboxes) and include validation.

App 3: Money Lending App

Now we will start doing something useful. Create an app that will allow you to enter a list of your friends, then be able to select a friend and enter details about a loan: date, amount and when they should repay you.

Create a basic dashboard that will show you how much you are owed right now. As an extra - create a special URL that you can send to your friend to remind them how much they owe you.

Think about various real-life situations and implement them - partial repayment, multiple loans for the same friend and time limits on different loans.

App 4: Online auction

It's time to sell your old gadgets. Do you have a phone that you no longer use? Let's create an auction for it!

You have to write an app where you can enter details of your item (name, description, starting price, expiration date), then share the URL with your friends who can bid on it.

Your friends need to create an account and log-in before they can bid, so that you know who they are. Personalize your app with your unique ideas. Implement the "minimum bid" policy, e.g. If current bid is "5" and someone enters bid "10" it increases only to 6. If there is another user who bids 8, then your system automatically increases bid of the first user to "9".

Show how much time is left on a bid.

App 5: Advertisement Board

Create a site with a number of categories (household, garden, car, etc) and actions (buy, sell, rent, exchange). Allow users to fill out a form with the posting details. Displayed advertisement in the appropriate category. Extend your app to include "admin's verification" - we don't want bad ads to be advertised. Add an ability to display ads only for some time period (e.g. 30 days).

Integrate payment gateway, so that users may pay to "feature their ad". This will extend their ad's lifetime to 60 days, give it a "HOT" badge and place it on top of the list in a category.

Compare your project with a professional classifieds sites, see which features you are lacking and implement some of them into your own project.

App 6: Twitter

Time to post tweets on your timeline.

Implement your own twitter. Allow other users to follow you. Find and implement the most essential features inside your application.