Adding Pages

Agile Toolkit has several ways to define new pages. Depending on the situation you should choose the most appropriate way.

Where a page is located depends on the API used. For example, for the command-line API (ApiCLI), the concept of pages is not defined at all. The table below shows the behaviour of ApiFrontend-based page routing.

Defined in Class used Template used Notes
API Method Page Default Probably the fastest way to create a page handler is to define a function inside the API class. The function must start with the prefix "page_", and continue with the page name, with slashes replaced by underscores. Try to avoid using this method.
File page/mypage.php custom default or custom This is preferred way to define new pages, if you need dynamic content on them and optionally custom layout.
Template Only Page custom Ideal for custom pages. Simply create a single file with no PHP in it
Your own Custom Custom Implement your own pattern in the API class. You can use this method to fetch pages from the database, or to generate them dynamically

Defining new pages through the API methods

    function page_helloworld($page){
        
$page->add('Button')->setLabel('Click Me');
    }

This is possibly the fastest way to add a new page to your Agile Toolkit application. The API will automatically create a standard page for you and will pass it to the function as an argument. You can then add objects to the page.

Creating a separate class for each page

class page_helloworld extends Page {
    function 
init(){
        
parent::init();
        
$page=$this;

        
$page->add('Button')->setLabel('Click Me');
    }
}

Creating a file inside page/helloworld.php with the contents above has the same effect. However, this time instead of a generic Page class your own class is used. This gives you the flexibility to create more methods and have more complex presentation logic without polluting the API class.

Static Pages

Static pages are the fastest way to get content into your web software. To build a high-performance application, you must make it simple and fast for it to retrieve content. The fastest way is to get content from a file.

Agile Toolkit allows you to create static pages simply by creating a file page/helloworld.html (inside the directory with your templates such as: templates/default)

<div id="<?$_name?>" class="g-10">
    <
div class="g-6">
        <
h2>Left Column</h2>
        <
p>Hello</p
    </
div>
    <
div class="g-6">
        <
h2>Right Column</h2>
        <
p>World</p
    </
div>
</
div>

The definition of the id= property in the outermost element enables Agile Toolkit to interact with it through JavaScript. It is not a mandatory attribute, but is highly suggested to have.

This example also uses a built-in Grid System for 12 columns, and should output arranged into 2 columns. Similarly, you can use your own HTML code snippet. We will get back to page layouts later.

Catch-all and 404 pages

If ApiFrontend is unable to determine the location of your templates, it executes the function api->pageNotFound($e); The argument is the exception raised when trying to include the page class or its ancestors.

You can re-define this function either by placing a redirect or by showing a custom 404 page. It is safe to "throw $e" to signal a non-existant page. The API will catch this exception and act according to the logging settings - therefore, do not use this for error-handling.

Other API Classes

Pages are a concept implemented at the API level, and some API classes may not implement the Page concept at all or implement it differently. For example, when you build a command-line utility using ApiCLI, it will never go and look for pages at all. ApiWeb, on the other hand, will use the API method page_helloworld(), and will attempt to load the page from 'page/helloworld.php', but it will not support "static" pages.

Page implementation is a case of a broader "Layout" concept. You must have a <?$Content?> tag inside your shared.html template. See the api->layout_Content method implementation for more info on creating your own logic.