TicaTK Documentation

Version : 0.2
Revision Date : 31/01/2003
Author : Christophe Sollet
(c) 2003 Coleebris

Note : This document is a work in progress, any comments are welcome.

Table of Content

1. Overview

2. Quick Start

3. Understanding TicaTK

3.1 Used Terms & Concepts

3.1.1 Interface

3.1.2 Execute

3.1.3 Actions

3.1.4 ActionDef

3.2 Session workflow
3.3 Widgets

4. Using TicaTK

4.1 Software requirement
4.2 Installation

4.2.1 PHP Configuration
4.2.2 Application files Setup

4.3 PHP API
4.4 Security concerns

5. Extending TicaTK - Creating custom widget

5.1 Server part
5.2 Client part

1. Overview

TicaTK is a GUI toolkit written in Javascript on the client side and in PHP on the server side. To develop a GUI with TicaTK, you just have to manage PHP objects. TicaTK handles rendering, synchronisation and network communication.

2. Quick Start

Goal of this quick start : Allowing to quickly install TicaTK and the Tour Manager as an example application. Once you have it running, you have a working base that should allow to proceed to some experimentation.

Requirement :

PHP V4.2.3 with domxml and zlib extension compiled in.

Note :

PHP V4.3.0 should be ok but not extensively tested.
Completely untested on Windows.

Configuration :

Manage to have the "php" directory content in the PHP include_path
"htdocs" directory content must be reachable by the web server

Point your browser on demo.php (throught the web server of course)

That's all.

3. Understanding TicaTK

Let's see how all this stuff is working internaly. Note : all xml management are done transparently by TicaTK and described below for reference.

3.1 Used Terms & Concepts

3.1.1 Interface

Root element of a xml tree describing the GUI. This tree is first created on the server and, at startup, duplicated on the client. Any change made on the GUI will be reflected on it.

Example :

       An Interface containing a simple window :

       <interface>
               <window id="my_win" title="My Win" left="10" top="100" />
       </interface>

3.1.2 Execute

Root element of a xml tree describing changes on the GUI. Its primary use is to ensure Interface synchronisation between the client and the server. An Execute is a chain of Action that is sent between the server and the client.

Example :

       An Execute instructing the client that a menu has been added using an acmrginterface element:

       <execute>
               <acmrginterface>
                   <menu id="my_menu" label="My Menu">
                      <menuitem id="my_menuitem" label="Close My Win" />
                   </menu>
               </acmrginterface>
       </execute>

       Interface state after Execute processing :

       <interface>
               <window id="my_win" title="My Win" left="10" top="100" />
               <menu id="my_menu" label="My Menu">
                      <menuitem id="my_menuitem" label="Close My Win" />
               </menu>
       </interface>

3.1.3 Actions

Primary Actions allows to manipulate the Interface by adding, deleting and updating elements : acmrginterface, acclose and acsetattr, respectively. Other Actions are more specific as acloadxml which will make server request or acmsgbox which will display a message box to the user.

3.1.4 ActionDef

As Execute, an ActionDef is a chains of Actions. Main difference is that ActionDefs are parts of the Interface and, most of the time, will be triggered by an user event.

Example :

       Let's add an ActionDef to our interface and attach "my_menuitem" menu item to it. By the way, set "my_menu" menu as window's menu :

       <execute>
               <acmrginterface>
                       <actiondef id="my_actiondef">
                               <acclose target="my_win" />
                       </actiondef>
               </acmrginterface>
               <acsetattr target="my_menuitem" attribute="actiondef" value="my_actiondef" />
               <acsetattr target="my_win" attribute="topmenu" value="my_menu" />
       </execute>

       Interface state after Execute processing :

       <interface>
               <window id="my_win" title="My Win" left="10" top="100" topmenu="my_menu" />
               <menu id="my_menu" label="My Menu">
                       <menuitem id="my_menuitem" label="Close My Win" actiondef="my_actiondef" />
               </menu>
               <actiondef id="my_actiondef">
                       <acclose target="my_win" />
               </actiondef>
       </interface>

       Now, the "Close My Win" menu item close the window !

3.2 Session workflow

3.3 Widgets

All elements contained in the Interface are called widgets. Most of them are visibles but somes, like ActionDef or Timer, haven't any visible conterpart.
The following figures shows relation between existing widgets :

Please refer to the PHP API Documentation for more information about individual widgets.

4. Using TicaTK

4.1 Software requirement

Server side

A PHP compatible web server (eg: Apache).
PHP 4.2.3 or superior with domxml and zlib extensions compiled in.

Client side

A DOM compatible web browser (Mozilla 1.0+ or derived / MSIE 5.5+)
Javascript and cookies ("originating only" is fine) activated.

4.2 Installation

As a toolkit, TicaTK is not an independant application so the following steps are only an approach to install and use TicaTK in your application, not the only way to do it.

4.2.1 PHP Configuration

TicaTK doesn't require any specific PHP configuration. It should handle correctly server configured with "register_global = off" or various magic quote settings. Any exception to this rules should be considered as a bug and reported as it.

TicaTK heavely relies on the PHP session management system. For now, only cookies based session are supported.

The distribution php directory content must be in the php "include_path" directive. The ticatk.inc file defines a constant "TTK_INCPATH" (default to "ticatk") that define the base path to access TicaTK php classes definitions. This file also load required base classes.

4.2.2 Application files Setup

TicaTK require some html files to be able to run. In this section, we will take the TicaTK Tour application as example.

index.php :

An index file which will define the required frameset.

The frameset must, at least, define two frames. One must be called "mainFrame" and should be visible. The other must be named "statusFrame" and is tipically hidden.

Example :

main_frame.php :

Loaded in the main frame, this file will load TicaTK javascript files and start the application.

Example :

<?php
        require_once "ticatk.inc";
        require_once TTK_INCPATH . "jsloader.inc";
?>
<html>
<head>
<?php
        TTK_JSLoader("ticatk", array("WINDOW", "MENU", "TOOLBAR", "CONTAINER", "FORM", "TREE", "BACKTOOLBAR"), "start_tour.php");
?>
</head>
<body>

</body>
</html>

status_frame.php :

A dummy file needed to fill browser request at the frameset creation.

Example :

<html>
<body>
-> TicaTK is loading...
</body>
</html>

start_tour.php :

Once TicaTK is loaded on the client side, this file will be loaded. TicaTK expect that this file sent the starting Interface. This file is requested only once at the application startup, so you can make any initialisation needed here.

Example :

<?php
require_once "tour/tktour_manager.inc";
TK_TourManager::init();
?>
<html>
<body>
<?php
$_SESSION["TKTour"]->send_interface();
?>
</body>
</html>

handle_tour.php :

As all this application's ActionDef link to handle_tour.php, this file will handle all request to the server.

Example :

<?php
require_once "tour/tktour_manager.inc";
session_start();
$_SESSION["TKTour"]->handle_event();
?>
<html>
<body>
<?php
$_SESSION["TKTour"]->send_execute();
?>
</body>
</html>

4.3 PHP API

For now, see the API Doc and examples.

4.4 Security concerns

Despite the fact that the TicaTK server side does his best to enforce what's the client sends, it has to accept Interface changes. So, always consider that what you get from TicaTK may be forged. Do not rely on object's id without further check. In short, handle TicaTK objects the same way as you process direct client requests : don't trust them.

TicaTK complexifies communication between clients and servers but do not add any security layer. This last point may change in the future.

5. Extending TicaTK - Creating custom widgets

Only some hints for now. We can create custom widgets that match your specific needs : contact us for more information.

5.1 Server part

The easiest part : add your class in widgets/mywidget.inc. You have to call it TTK_mywidget where mywidget matches the xml element tag name you want to use. Extend your class from TTK_Widget, check existing widgets...

5.2 Client part

Your new widget has to be listed in jsdep.inc. No need to modify any other file.
Look at existing widgets.