URL translation into a Page Class

In Agile Toolkit, pages are objects created from classes. For each user request only one page object is initialized. The process where an API class determines the name of the page class to initilaize is called "routing".

Page Routing

Let me start with an example. The page you are reading right now was determined by Agile Toolkit as:

learn_understand_page_route

This page is determined from the URL above: /learn/understand/page/route. Please note that "/" and "_" are treated identically by Agile Toolkit.

In Agile Toolkit the API class determines how routing is done. You must already know that there is a selection of different API clasess in Agile Toolkit and their approach to page routing is different.

ApiFrontend

ApiFrontend — the application class you are most likely to use — diverts all web requests into a single file: index.php. This is achieved by either using the mod_rewrite rule (RewriteRule .* index.php) or by building the URLs with the argument "page". The default installation of Agile Toolkit uses URLs like this: "http://localhost/agiletoolkit/?page=dbtest".

Open the index.php with a text editor and notice that the job of the file is to initialize your Application class and pass execution to it.

ApiWeb

ApiWeb — is a good application class if you can't use frontend controller or will need to use different routing. It is most useful when you need to integrate Agile Toolkit with a different framework.

ApiCLI

This class assumes that you'll be executing it from the command-line and will not even try to determine the page.

The rest of this chapter will focus on ApiFrontend routing leaving other API implementations aside.

Building a URL from the page name

The logic used by ApiFrontend when determining a corresponding class to a page is simple:

Browser URL Page Notes
http://example.com/preferences.html preferences Agile Toolkit completely ignores the extension and uses remaining location to determine page name.
http://example.com/?page=user/add user/add Your default install of Agile Toolkit is not configured to use mod_rewrite. Therefore the URL in the browser will address index.php passing page=XX. GET['page'] will always override determined page-name.
http://example.com/profile/change-password.do profile/changepassword Dashes cannot be used in a function or class, they are eliminated from the page name automatically. Any extension can be used as long as .htaccess directs them to index.php
http://example.com/?abc=123 index If URL does not contain page, then "index" page name is used.
http://example.com/admin/logout logout Agile Toolkit does not have to be in your web-root directory. If it's installed into subdirectory, Agile Toolkit will detect it and will eliminate the installation point (base_path) from the name of the page.

URL Components

PageManager is a controller used by ApiFrontend. It detects the URL of the browser and splits it into 3 components:

  1. base_url — http://example.com
  2. base_path — /atktest/
  3. page — user/settings
Properties are accessible through $api->pm->base_url, $api->pm->base_path and $api->page. Pay attention to how slashes are distributed.

The page you are looking at right now is called "learn/understand/page/route".

The page object follows the standard pattern; And executes the init() method after it's initialized. A Page may have a custom template, but if it does not, the default page layout is used to display an empty page.