Developer Overview

Raxan is an event driven PHP/Ajax framework that is based on a Programmable Document Interface (PDI) design. It was created to meet the needs of modern web application development while allowing separation of web application layers, re-use of business logic and parallel development by separate teams.

The core functionality of the framework was inspired by the jQuery API. This means that if you're already familiar with basic methodology of jQuery, then you can easily adapt to the methodology and concepts of this framework.

Directory Structure

If you haven't yet done so, please download and install the latest version from the Raxan website. See the Downloading and Installation Instructions web page for more information.

The "sdk/" folder contains the documentation, source code, tools and examples for the framework.

• sdk/raxan - Main raxan framework folder.
• sdk/raxan/plugins - Reusable server-side plugin folder
• sdk/raxan/ui - Contains CSS stylesheets, JavaScript libraries and server-side UI components.
• sdk/raxan/pdi - Contains Raxan server-side PHP classes and configuration files.
• sdk/raxan/pdi/shared/locale - Stores language definitions files and locale settings.

The "ui/css" folder is used for storing cascading style sheets and images. Inside this folder you will find the master.css file which contains predefined CSS classes for building web page layouts. In addition, you will also find a "default" folder that contains the default theme for the framework. Additional themes can be added and loaded when necessary.

Use the "ui/javascript" folder to store reusable JavaScript libraries.

Understanding the Framework

As a developer you have the choice to choose how they would like to build and deploy your applications. You can choose to use the framework as stand-alone dynamic JavaScript/CSS loader, or go with the built-in CSS framework and jQuery libraries build Rich Ajax/HTML Applications. And if you're into building PHP-based web sites or applications then look no further. Raxan has the right tools and APIs that you need to start building your next web application.

Each release includes the latest stable versions of the following JavaScript libraries:

• jQuery Core (jquery.js)
• jQuery UI utils (jquery-ui-utils.js)
• jQuery UI Effects (jquery-ui-effects.js)
• jQuery UI Interactions (jquery-ui-interactions.js)
• jQuery Tools (jquery-tools.js) - includes Tabs, Tooltip, Scrollable, OverLay, Expose, MouseWheel, History
• jQuery Form Tools (jquery-form-tools.js) DateInput, RangeInput, Validator
• Raxan UI (raxan-ui.js)

You can create your own customized version of the above libraries and add them to the "raxan/ui/javascripts" folder.

Separate Page Content from Logic

Building on the web design philosophy of the separation of content from logic, Raxan makes it easier for you to separate your HTML Views (or content) from your PHP/Ajax logic by adding them to a "views" folder. This approach makes it possible to load or modify the contents of existing views without having to alter the page logic.

In addition to storing HTML content, you can also use the "views" folder to store style sheets, images and JavaScript files. Once you have organized your files you can load and process the views using the built-in APIs.

The Web Page Controller

A Raxan web page normally includes a reference to the PDI gateway (or auto-start) file and a RaxanWebPage sub-class. The gateway file (raxan/pdi/gateway.php or raxan/pdi/autostart.php) is used to load the main classes that are required by the framework. These classes include Raxan, RaxanWebPage, RaxanElement, RaxanPlugin and RaxanDataSanitizer, etc. The RaxanWebPage class is responsible for collecting, processing and responding to a client's request as shown below:

When a request is received the page controller automatically initializes the web page class.

Here's quick example:

<?php
    require_once('raxan/pdi/autostart.php'); // include the auto start file

    class NewPage extends RaxanWebPage {  // extends RaxanWebPage class
        protected function _load() {
            $this->content('My first Raxan Page'); // set the content of the page
        }    
    }

?>

In the above example the "NewPage" class will be initialized when the page is requested. If there are more than one classes that extends RaxanWebPage within the same page, the framework will load the last defined class. To prevent this behavior you will have to declare the $autostart property within the startup class:

<?php
    require_once('raxan/pdi/autostart.php'); // include the auto start file

    class AnotherPage extends RaxanWebPage {  // extend the RaxanWebPage class
        protected $autostart;   // tells Raxan to initialize this class when the page loads 
        protected function _load() {
            $this->content('My first Raxan Page'); // set the content of the page
        }    
    }

?>

Another way to automatically initialize a page class is to set the value of the "autostart" config option to the name of the class to be initialized:

<?php
    Raxan::config('autostart','MyDefaultPageClass');
?>

To disable automatic startup, set the above "autostart" option to false:

<?php
    Raxan::config('autostart',false); // disables auto-startup
?>

In addition to the above you can manually initialize a page class by including the reference to the "gateway.php" file and calling the RaxanWebPage::init() method:

<?php
    require_once('raxan/pdi/gateway.php'); // include the gateway file

    class NewPage extends RaxanWebPage {  // extend the RaxanWebPage class
        protected function _load() {
            $this->content('My first Raxan Page'); // set the content of the page
        }    
    }

    RaxanWebPage::init('NewPage'); // manually initialize the class

?>

When the "NewPage" sub-class is initialized it will serve as the Page Controller for the web page. To access the page controller from an external class or function, use the RaxanWebPage::controller() method.

Extending the RaxanWebPage class

To receive page event notifications when your page is being processed, you will have to extend the RaxanWebPage class and add your page event handlers to the page controller.

For example, the code below will modify the content of the web page when the _load() event is triggered:

<?php
class MyPage extends RaxanWebPage {
    protected function _load() {
        $this['body']->append('Hello World');
    }
}
?>

The following is a list of supported page events:

• _config
• _init
• _authorize
• _indexView
• _load
• _prerender
• _postrender
• _reply
• _destroy

For more information about page events, visit the Page Request Cycle documentation page.

Loading HTML content into the DOM

By default any HTML content appearing after the "autostart.php" has been loaded will be buffered and used as the source for the HTML web page. This is useful if you're building a simple web page and want to include both HTML and with logic together:

<?php
    require_once('raxan/pdi/autostart.php');

    class NewPage extends RaxanWebPage {  
        protected function _load() {
            // do something here
        }
    }

?>

<div>My First Raxan App</div>
<hr />

The above will generate a basic web page with the words "My First Raxan App". In addition to the above you can load content via a master template or view. See Templates and Views for more information

Accessing DOM Elements

There are a number of ways to retrieve single or a collection of match elements. Here are a few examples:

<?php
    class NewPage extends RaxanWebPage {
        protected function _load() {
            $elm = $this->findById('panel1');     // find by element id
            $elm = $this->panel1;                 // direct property of page. quick wrapper to findById()
            $elm = $this->findByXPath('//div[@id="panel1"]'); // find element using xpath query
            $elm = $this->find('.side-panel');    // find element using CSS selectors
            $elm = $this['.side-panel'];          // wrapper to the above find() method
        }
    }
?>

<div id="panel1" class="side-panel"></div>

The above functions will return a instance of the RaxanElement class which contains the matched elements.

Where possible you should use an id when retrieving an element from the page. Other useful Tips:

• Use ids where possible. See findById(). You can directly access elements using $this->myid, where myid is the id of the element.
• Use XPath queries where possible. See findByXPath().
• Use CSS selectors if necessary. See find(). CSS selectors are a little slower than XPath queries because there’s currently no built-in DOM support for CSS selectors in PHP.

Modifying DOM Elements

To modify the content of the match elements you can use one of the following methods.

<?php
        protected function _load() {
            $elm = $this->findById('panel1');     // find element by id

            $elm->text('My sample app');    // sets the text content for match elements
            $elm->html('Hello <strong>world</strong>'); // sets the html content
            $elm->attr('title','My first Raxan web page');  // sets the title attribute

            $elm->css('color','#00ff00');// sets the css color
        }
?>

It's also possible to chain method calls together in one line of code:

<?php
    protected function _load() {
        $this->panel1->text('My sample app')->css('color','#00ff00');
    }
?>

To learn more about the available element properties and methods, visit the RaxanElement API documentation page.

Loading external JavaScripts and CSS files

There are two ways to dynamically load JavaScript and CSS files inside your applications or web pages:

The first approach is to add the link or script tags inside your html views or master template page. You can then assign a class or id to the elements so that you can change the url dynamically:

<link id="link1" href="path/to/file/style.css" type="text/css" rel="stylesheet" />
<script id="script1" type="text/javascript" src="path/to/file/script.js"></script>

<?php
        protected function _load(){
            $url = ($this->dayTime==true) ? 'day.css' : 'night.css';
            $this->link1->attr('href',$url);
        }
?>

The second approach is to use the loadScript() and loadCSS() methods as shown below:

<?php
        protected function _load(){
            $url = ($this->dayTime==true) ? 'day.css' : 'night.css';

            $this->loadCSS('path/to/file/'.$url, true);
            $this->loadScript('path/to/file/script.js', true);
        }
?>

A few things to note about loadCSS() and loadScript():

1. By default the methods will attempt to load CSS and JavaScript files from the raxan/ui/css or raxan/ui/javascript folders respectively.

2. There is no need to include the .css or .js extension when load files from raxan/ui/css or raxan/ui/javascript folders:

   <?php
       // load the jquery-ui-interaction.js file
       $this->loadScript('jquery-ui-interactions');
   
       // load the myfolder/custom.js file relative to ui/javascript
       $this->loadScript('myfolder/mycustom'); 
   ?>
   

3. When loading a script or css file that's not stored inside the default raxan folders, you must include the full path and name to the file and set the second parameter to true:

   <?php
   
       // load css stylesheet
       $this->loadCSS('path/to/file/style.css', true);
   
       // load scripts
       $this->loadScript('path/to/file/main.js', true); // main.js
       $this->loadScript('views/scripts/custom.js', true); // path relative to web root
   ?>
   

Using registerScript to change or bypass default scripts

Use the registerScript() method to set or change the location of a script file:

<?php
    protected function _init {
        // set the path to the jquery.js file
        $this->registerScript('jquery','/path/to/jquery.min.js');

        // set the path of the raxan startup.js script
        $this->registerScript('startup','/path/to/startup.min.js');
    }
?>

When loadScript() method is called with the name of the script it will be loaded from the registered path:

<?php
    protected function _init {
        $this->loadScript('jquery'); // jquery will be loaded from the registered path
    }
?>

To prevent a script from being loaded, you can set the second parameter of the registerScript() method to true. This can be useful when you want to manually handle the loading of your JavaScripts:

<?php
    protected function _init {
        // prevent jquery from being loaded .
        $this->registerScript('jquery',true);

        // calling loadScript will not load the jQuery library
        $this->loadScript('jquery');
    }
?>

To load a single JavaScript file you will need to manually register the bundled jQuery libraries as shown below:

<?php
    protected function _init {
        $this->registerScript('startup','/path/to/combine.js'); // the framework will load the combine.js startup file
        $this->registerScript('jquery',true);
        $this->registerScript('jquery-ui-effects',true);
        $this->registerScript('jquery-ui-interactions',true);
        $this->registerScript('jquery-ui-utils',true);
        $this->registerScript('jquery-tools',true);
    }
?>

In addition to registering JavaScript files and libraries, you can use the registerCSS() method to set or change the location of a stylesheet:

<?php
    protected function _init {
        // set path to master stylesheet
        $this->registerCSS('master','/path/to/master.css');
        $this->loadCSS('master');

        // set path for default theme
        $this->registerCSS('default/theme','/path/to/combine.css');
        $this->loadTheme('default');
    }
?>

We have only scratch the surface of the framework. There's a lot more information available within the User Guide and I would like to encourage you to have a look at the other documentation and tutorials.

---

Up Next: An example of a Web Application