README

Archost UI toolkit.

Installation

git clone https://github.com/archost/acore.git
cd acore
composer install
git clone https://github.com/archost/alicht.git /tmp/alicht
cp -r /tmp/alicht/{css,js} public/

Usage

Create a page

To create a page just extend the Page base class and implement its preload() method.

<?php
require __DIR__ . '/../vendor/autoload.php';
use \archost\acore\Page;
use \archost\acore\ActionQueue;

class AmazingPage extends Page {

    protected function preload()
    {
    }

}

$p = AmazingPage::instance();
echo $p->display();

This minimal code will display an empty alicht-style page.

Actions

Every non-trivial page will probably have some actions that control its behavior. Actions are triggered by user input and identified via a simple key (e.g., comment, login).

Action handlers

Action handlers are the methods of a concrete page class that respond to a given action. These action handlers are registered in preload() so the page knows how it should respond to a given action.

protected function preload()
{
    $this->register_action_handler('day', [$this, 'on_day']);
    $this->register_action_handler('night', [$this, 'on_night']);
}

As you can see, we used the register_action_handler() method to - you guessed it - register action handlers. The first argument is an action key, the second argument is a callable.

Ok, let's go and implement those action handlers inside our AmazingPage.

public function on_day()
{
    $this->alert_success('Good day!');
}

public function on_night()
{
    $this->alert_success('Good night!');
}

alert_success() prints a nice green notification on the top of the page. Check the Page API for a complete list of available methods.

Also note that there may be a whole action queue waiting to be processed when displaying a page. In other words, you really want to make sure that your action handlers do not get in each other's way in the event of multiple actions. (You may also want to think about finite state machines and such things. I'm not going into this here.)

Action queue

A page has a FIFO action queue that keeps track of pending actions. Every page obviously handles its own action queue. In fact, the Page constructor requires an instance of ActionQueue.

Now, let's push some actions in our queue!

$p->push_action('day');
$p->push_action('foobar');

Lights on!

echo $p->display();

What will happen behind the scenes?

First of all, the queue will be filled with the actions day and foobar.

Next, the display() method will cal the associated action handler for each action if there is one. In our case, there's only one for day (which is on_day()), while foobar will be ignored.

Consequently, our page will display a nice "Good day!" message.

Page API

display()

Display the page.

push_action( $action )

Push an action to the action queue. This should be automatically called by some dispatcher whenever some event happens. We won't define (and thus limit) what an event could be. It's up to you!

dump( $key [, $value = null] )

Dump arbitrary data as is into a protected associative array $dump to avoid writing a lot of redundant setter code when no special treatment is needed.

You can either pass a key-value couple or an array of data (and omit the value parameter).

preload()

This callback method must always be implemented when you extend the Page class. It will automatically be called whenever you display() your page.

This is the right place to register the action handlers.

This is also where you want to do some global things like setting the page title. (See set_title.)

register_action_handler( $action, $handler )

This method maps an action to an action handler that is called whenever an action is triggered. (See push_action.)

Example code:

protected function preload()
{
    $this->register_action_handler('explosion', [$this, 'on_explosion']);
}

Note how you pass the callable method as an array using $this and the function name.

set_title( $title )

Set the HTML title of the page.

set_meta_description( $desc )

Set the meta description text of the page.

css( $css_file )

Add a CSS file to the html head.

cover( $cover_file )

Add a cover image.

Box getters

The following methods give you access to the boxes that build up the page.

document()

This getter represents the entire document. You should append the majority of the content here.

logo()

Use this to set a logo template. This is usually at the top left corner of the page inside the header.

nav()

Use this to add a nice navigation inside the header.

Alerts

The following methods allow you to display nice alert messages above the document box.

alert_success( $msg )
alert_warning( $msg )
alert_error( $msg )
alert_info( $msg )

Demo

There is a sample code in public/. You should get something like this:

Dependencies

Contributors

Team Archost

License

acore is open-sourced software licensed under the MIT license.

archost / acore

Maintainers

Details