Achievo Explored

Copyright 2005-12-21 MJ Ray (GPL, see terms)
  1. Introduction
  2. The Front Page
  3. The Toolbar
  4. The Menu
  5. The Main Frame
  6. References
  7. About this document

Introduction

Achievo is a web-based work tracker which can run on Linux, Apache, MySQL and PHP (LAMP). It is published under the GNU GPL and freely available online.

Other Achievo documentation seems to be user guides, description of parts, or how to achieve tasks, such as the HOWTOs and FAQs. The distribution doc directory contains README, INSTALL and so on, but no HACKING. There seemed to be no quick developer's-eye overview of Achievo, so I (MJR) wrote this guide to help myself and anyone else who follows.

This guide is stand-alone for now, because I'm not sure of the long-term freedom of the Achievo ATK Wiki and I don't like its unusual wiki-like syntax.

I will start by looking at the system from the front page and then move through the web interface. As necessary, I will interrupt the main description to look at an underlying part of the system, or direct you to someone else's description of it. So far, I don't describe the system's modules in depth, but I might add that later.

You should have a basic working understanding of PHP, web standards and object-orientated programming. I think the chapter in Teach Yourself Scheme has a good 0-60 introduction to objects, even if PHP is not exactly the same. The description is the important thing, so don't be afraid if you don't understand the code, but maybe you remember functions from maths classes. Scheme is mostly just functions, with the function name inside the ()s instead of before them.

The Front Page - index.php

The bulk of the work here is done by the $g_layout object. The start of index.php includes atk.inc which includes atk/class.atknode.inc which includes atk/class.layout.inc which defines $g_layout.

$g_layout configures itself when initGui is called. It uses the $g_theme global or falls back to the configuration file theme defaults. index.php itself doesn't configure the achievo theme because it only outputs a frameset.

After the include, index.php calls atksession and atksecure. atksession comes from atk/session/class.atksessionmanager.inc and creates or resumes a session. You can look up atk files in the ATK API Reference for more details.

atksecure comes from atk/security/class.atksecuritymanager.inc and just asks the security manager to authenticate. The security manager will recover login status from the session and double-check it with other session data, or check against database or config files (for admin superuser). It is this method call which might send the login form and then exit(), or send the authentication HTTP headers or handle a login attempt.

getUser returns the logged-in user name or an empty string. This is used to pick the main frame action (adminpim or pim) which is wrapped in session_url() to add session-specifics.

Finally, the frames are sent along with a hostile noframe message. They contain top.php, menu.php and some query of dispatch.php

The Toolbar - top.php

This opens with similar atk, sessions, security and then theme and version configuration.

The $g_layout object is used for output again. Many of the functions have a version with a ret_ prefix which return a string instead of sending output. The ui_ functions use the theme's block_ templates. Most other templates are optional and names can be seen in atk/class.layout.inc

The dispatch_url function comes from atk/atktools.inc and builds a call to dispatch.php for the node and action (which must contain only url-safe characters). Other functions such as href and text are from the same file.

The getNode to construct the search is interesting. getNode comes from atk/modules/atkmoduletools.inc and returns an already-existing instance if there is one, or creates one otherwise. The search.search node is made from modules/search/class.search.inc and other getNode calls work in a similar way.

The Menu - menu.php

A variation on the includes, session and security, with parameters used to put the menu session in its own namespace and be smaller. Two rag-bag collections of tool functions are included, along with the menu configuration.

Each module is asked for menu items in turn, then $g_layout used to display them, sorted, with optional code to drive the projectmanagement menu listbox. Links mostly use queries to control menu.php display.

The Main Frame - dispatch.php

This is how most output reaches the user. The header variation this time is to have an optional redisplay of the login form after atksession if login isn't currently set in the session. If it is, atksecure is called and theme configured.

The node name is read from $ATK_VARS, which is built by atksession from the query and session. If it is found, ATK_VARS is passed to its dispatch method.

As one example, the default normal user call from index.php is an action of pim on node pim.pim. So, that node is created and then dispatch.php calls pim.pim's dispatch method, which is actually inherited from atkNode (see API documentation). That will call action_pim in modules/pim/class.pim.inc if the node settings are OK (look for atkActionHandler in the API).

Most of achievo's interface works in a similar way. I hope this short introduction has been enough to help you start exploring and hacking.

References

About this document

MJ Ray is a web developer, educator, statistician and writer, available for hire. He works for a cooperative enterprise partnership and contributes to free software including the koha ILS and Debian GNU/Linux.

This guide is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

Please send improvements or suggestions by email. You should find current email address and the latest version of this guide near the page linked at the top.