Pages, Controls, and RPC Servers

FlowBasis provides a page model for presenting content and exposing services. Pages can contain controls. Controls can contain other controls. Both pages and controls can expose RPC (remote procedure call) servers which very simply expose services that can be accessed from client-side javascript. The basic relationships between pages, controls, and RPC servers are shown in the following diagram:

Generally, a page will render its output as HTML that is returned to the browser (although pages can also hand requests off for other components to handle). Pages render page sections defined by the theme template, and they coordinate the inclusion of JavaScript source files and stylesheets.

Controls allow visual and logic components to be packaged up in a way that enables them to be embedded into any page or another control. FlowBasis_Ratings_UI_StarRatingControl provides a good example of how controls can be leveraged.

Creating Pages

The simplest way to create a page is to add a PHP file to the "pages" folder of your FlowBasis installation. Let's say you create the file at "pages/somefolder/hello.php". hello.php must contain at least one line of the form:

FlowBasis::setPageClass('HelloPage');

HelloPage must be the name of a class derived from FlowBasis_UI_Page, and HelloPage may be defined in the same file as the FlowBasis::setPageClass call, or it may be a class that exists under the "core-classes" or "classes" directories. The HelloPage page will then be accessible at http://your-flowbasis-site/somefolder/hello (if you publish FlowBasis at the root of your domain).

For an example of a real page class, see the default index page located at "core-pages/index.php" of your installation. The contents of "core-pages" and "pages" combine to form a set of reachable pages within FlowBasis. You can override the default index page at "core-pages/index.php" by adding your own at "pages/index.php". Any static files (.js, .png, .gif, .pdf, etc.) that are in "core-pages" or "pages" will be made available in the same fashion.

Now, for defining our page class, a basic implementation would look like:

class HelloPage extends FlowBasis_UI_Page {

function printMainContent() {

echo 'Hello, world.';

}

}

The default page template has a section called "MainContent", so the printMainContent function is called to render that section of the page. Page templates will be explained more thoroughly in the discussion on themes.

RPC Server

RPC servers allow pages and controls to easily expose services available via AJAX/JSON-RPC from client-side JavaScript. Both pages and controls can override their getRpcServer method to return an RPC server object. Every public method on the returned RPC server object will be available from the client.

A basic RPC server class would look like:

class HelloPageRpcServer extends FlowBasis_UI_Page {

function add($x, $y) {

return $x + $y;

}

}

To attach this to our page class, we would do the following:

class HelloPage extends FlowBasis_UI_Page {

function getRpcServer() {

return new HelloPageRpcServer();

}

function printMainContent() {

echo 'Hello, world.';

}

}

The "add" method is then accessible via JSON-RPC with a JSON post to the URI of the page. From the client-side JavaScript, you can do the following (the "null" for the first parameter just means to use the page URL for the target URL):

FlowBasis.rpc.invoke(

null, 'add', [ 4, 8 ],

function (response) {

if (response.error == null) {

alert(response.result);

}

}

);