Page View - Raxan User Guide

Raxan User Guide

Page-View Pattern

Raxan Beta 3 introduced a switchboard page handler that was designed to manage actions requested by the client. In RC1, the Switchboard Page Handler and Action has been replaced with individual view handlers and view mode.

The Page-View pattern makes it easier for developers to load and display multiple content views while maintaining separation between content and logic.

Page - The Page controller loads and interacts with the view and the model.
View - Stores the content to be displayed. This can be either a be a static or a dynamic page.

The page controller receives a request from the client to load and display a view. This information is passed to the view handler which then loads the requested view and the associated data/model. If a view was not specified, then the page controller will invoke the default _indexView() handler.

The view name which forms part of the page controller's url is case sensitive and can only contain characters A-Z, 0-9 and _ (underscore). For example: items, contacts, book_list, orderItems, etc.

How to request a view

To request a view you simply append the query string "vu=name" to the url of the page, where "name" is the name of the view that's being requested. The page controller url must contain the view name as part of the query sting as shown below:

http://domain.com/page-controller.php?vu=items

The "vu" query string parameter is processed internally.

Views can also be requested via an event or method call from the server.

To request a view when a click event is triggered from the browser, use the "view" option as shown below:

<?php

protected function _load() {
    $this->button1->bind('click',array(
        'callback' => '.myButtonHandler',
        'view' => 'newform' // loads the newform view when the event is triggered
    ));
}
?>

To redirect to a view from the server-side use either the redirectToView() method as shown below:

<?php
    protected function saveForm($e) {
        // do something here
        $his->redirectToView('thank-you'); // redirects to the "thank-you" view
    }
?>

Once the request is received by the page controller, the activeView property is set and the appropriate view handler will be invoked. The view handler is a special method that's only invoked when a specific view is requested. The method name consist of an underscore (_), the view mode and the suffix "View". For example:

<?php
    // items view handler
    protected function _itemsView() {
        // code here
    }
?>

Inside the view handler function you can load or initialize other html views or variables.

Note: If you attempt to request a view and there's no view handler or file present, then the system will display a "Page or view not found message"

How to load or append a view to a page

By defaults views are loaded from the "views" folder. The path to this folder can be configured using the "views.path" config option. The view can be either a .php or .html file

There are a three ways you can load or append a view to the page. The first is to use the appendView() method. This is method will append a view to the web page:

<?php
    protected function _indexView() {
        $this->appendView('dashboard.html');
    }
?>

The second option is to use the getView() method. This method will load and return the content of a view:

<?php
    protected function _indexView() {
        $view = $this->getView('customer-list.php');
        $his->content($view);  // set the content of the page

        // to return a the html of a specific element within
        // the view use the $selector option
        $header = $this->getView('new-form.php','#header');
    }
?>

The third option is to use the $autoAppendView property to automatically append the active view to the page.

When $autoAppendView is set to true the system will append views from the "views" folder using the view file name format {pagename}.{view}.php, where {pagename} is the base name of the current page and {view} is the name of the active view.

Developers can change the default view file name by applying a filter string. For example, 'myapp-{view}.html' will automatically append views that begins with "myapp-" and ends with ".html".

<?php
protected function _config() {
    $this->autoAppendView = true;   // automantically append view to page
    $this->autoAppendView = 'my-app-{view}.html';  // apply a custom filter to the active view
}
?>

The Page-View pattern allows developers to organize an application or page into Views and Events. For example, a blog application can be organized as follows:

Blog Page Controller

Page Views:

index view (default view - list blog entries)

detail view (show blog detail)

form view (create or edit blog)

Page Events:

save event

delete event

Reminder: HTML views are normally stored in a separate folder. This folder can be configured by setting the views.path option inside your config file.

Loading partial views

In addition to loading a full page view, you can use the appendView() method to load partial content from a view file. For example, let's say that you want to create a web page that allows a user to view additional information when the next button is clicked. Rather than having each view within a separate file, you could combine the views into a single file and then use appendView() to load each view separately.

The views could be combined and stored as follows:

<div id="part1">
    ... Page content goes here ...
</div>

<div id="part2">
    ... Page content goes here ...
</div>

<div id="part3">
    ... Page content goes here ...
</div>

Now you can load each view separately:

<?php
    protected function _indexView(){
        // load partial view content from combined-views.html
        $this->appendView('combined-views.html','#part1');
    }

    protected function _part2View(){
        $this->appendView('combined-views.html','#part2');
    }

    protected function _part3View(){
        $this->appendView('combined-views.html','#part3');
    }
?>

When the page is first loaded, Raxan will append the content of the DIV that matches the CSS selector #part1 to the web page.

Passing values to a view

To pass data to a view you can either manually call the appendView() or getView() method as shown below:

<?php
    protected function _indexView() {
        $data = array(1,2,3,4,5);

        // to pass data to the view for further processing use the $data parameter
        // the build-list.php view file can now access the $data variable.

        // passing data to appendView
        $this->appendView('build-list.php', null, $data);

        // passing data to getView
        $viewresult = $this->getView('build-list.php',null,$data);

    }
?>

In addition to having the $data variable available you can gain access to the current page byb using the $page variable:

Here's an example of the 'build-list.php' view file:

<h2><?php echo $page->title(); ?></h2>
<ul>
    <?php foreach($data as $i=>$value) { ?>
    <li><?php echo $value; ?></li>
    <?php } ?>
</ul>

Up Next: Server-Side Events